ECMWF Datastores Client

https://ecmwf.github.io/ecmwf-datastores-client/
Admin
The ECMWF Datastores Client provides programmatic access to the CDS, ADS, and EWDS data catalogues...
Tokens:14,715
Snippets:183
Trust Score:8.3
Update:1 week ago
Show doc for...
Tokens:
Raw
### Set up the environment with make install

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/README.md.txt

Command to install dependencies and set up the environment. Note that this project uses uv for dependency management and the generated uv.lock file should be committed.

```bash
make install
```

--------------------------------

### Install with pip

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/README.md.txt

Install the ecmwf-datastores-client package using pip.

```bash
$ pip install ecmwf-datastores-client
```

--------------------------------

### Configuration file example

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/README.md.txt

Shows the expected format of the configuration file located at ~/.ecmwfdatastoresrc or the path specified by ECMWF_DATASTORES_RC_FILE. Contains the API url and key.

```bash
$ cat $HOME/.ecmwfdatastoresrc
url: https://cds.climate.copernicus.eu/api
key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```

--------------------------------

### Install with conda

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/README.md.txt

Install the ecmwf-datastores-client package using conda from the conda-forge channel.

```bash
$ conda install -c conda-forge ecmwf-datastores-client
```

--------------------------------

### List available Makefile targets with make help

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/README.md.txt

Run this command to display all available utility commands and their descriptions. The output includes targets such as `make install`, `make qa`, `make unit-tests`, and `make type-check`.

```bash
make help
```

--------------------------------

### Retrieve and paginate through successful jobs

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/README.md.txt

Shows how to get jobs sorted by creation date and filter by status, then loop over pages to collect request IDs. The example checks if a specific remote request ID is in the list.

```python
>>> jobs = client.get_jobs(sortby="-created", status="successful")

>>> request_ids = []
>>> while jobs is not None:  # Loop over pages
...     request_ids.extend(jobs.request_ids)
...     jobs = jobs.next  # Move to the next page
...

>>> request_ids
[...]
>>> remote.request_id in request_ids
True
```

--------------------------------

### Interact with a previously submitted job

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/README.md.txt

Shows how to retrieve a remote by its request ID, inspect its properties (collection ID, request, status, results_ready, created_at), download a result file, get a receipt, get results, and delete the remote.

```python
>>> remote = client.get_remote(remote.request_id)

>>> remote.collection_id == collection_id
True
>>> remote.request
{...}

>>> remote.status
'successful'
>>> remote.results_ready
True

>>> remote.created_at  # See also started_at, finished_at, updated_at
datetime.datetime(...)

>>> remote.download("target_6.grib")
'target_6.grib'

>>> remote.get_receipt()
{...}

>>> remote.get_results()
Results(...)

>>> remote.delete()
{...}
```

--------------------------------

### Apply constraints to find available days in a month

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/README.md.txt

Shows how to apply constraints to a collection for a specific month and retrieve the number of available days. The example uses year '2000' and month '02', resulting in 29 days.

```python
>>> month = {"year": "2000", "month": "02"}
>>> constrained_request = client.apply_constraints(collection_id, month)

>>> len(constrained_request["day"])
29
```

--------------------------------

### Set Up the Environment

Source: https://ecmwf.github.io/ecmwf-datastores-client/README.html

Run this command to configure your virtual environment and pre-commit hooks. This project uses uv for dependency management; commit the generated uv.lock file to version control.

```shell
make install

```

--------------------------------

### Run all quality checks, tests, and build steps with make all

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/README.md.txt

Run this command to execute the full set of quality checks, tests, and build steps in a single command.

```bash
make all
```

--------------------------------

### Instantiate client and check authentication

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/README.md.txt

Creates a Client instance and optionally verifies authentication with check_authentication().

```python
>>> from ecmwf.datastores import Client
>>> client = Client()
>>> client.check_authentication()  # optional check
{...}
```

--------------------------------

### Run quality assurance with make qa

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/README.md.txt

Command to check formatting, linting, and lockfile consistency.

```bash
make qa
```

--------------------------------

### datastores.Client

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Client.html

Constructor for the datastores.Client class.

```APIDOC
## datastores.Client

### Description
ECMWF Data Stores Service (DSS) API Python client.

### Constructor Parameters
- **url** (`str` or `None`, default: `None`) – API URL. If None, infer from ECMWF_DATASTORES_URL or ECMWF_DATASTORES_RC_FILE.
- **key** (`str` or `None`, default: `None`) – API Key. If None, infer from ECMWF_DATASTORES_KEY or ECMWF_DATASTORES_RC_FILE.
- **verify** (`bool`, default: `True`) – Whether to verify the TLS certificate at the remote end.
- **timeout** (`float` or `tuple[float,float]`, default: `60`) – How many seconds to wait for the server to send data, as a float, or a (connect, read) tuple.
- **progress** (`bool`, default: `True`) – Whether to display the progress bar during download.
- **cleanup** (`bool`, default: `False`) – Whether to delete requests after completion.
- **sleep_max** (`float`, default: `120`) – Maximum time to wait (in seconds) while checking for a status change.
- **retry_after** (`float`, default: `120`) – Time to wait (in seconds) between retries.
- **maximum_tries** (`int`, default: `500`) – Maximum number of retries.
- **session** (`requests.Session`) – Requests session.
```

--------------------------------

### datastores.Results.download()

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Results.html

Downloads the results to a specified target path or the working directory if no target is given. Returns the path to the retrieved file.

```APIDOC
## datastores.Results.download()

### Description
Downloads the results of a job to a target path. If no target is provided, downloads to the working directory.

### Method
`download(target=None)`

### Parameters
- **target** (`str` or `None`) - Optional - Target path. If None, download to the working directory.

### Returns
- **str** - Path to the retrieved file.

```

--------------------------------

### download(target = None)

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/_api/datastores/Remote.rst.txt

Downloads the results of the job. If target is None, downloads to the working directory. Returns the path to the retrieved file.

```APIDOC
## download(target = None)

### Description
Downloads the results of the job.

### Method
download

### Parameters
- **target** (str or None) - Optional - Target path. If None, download to the working directory.

### Returns
- **str** - Path to the retrieved file.
```

--------------------------------

### Alternative retrieval methods

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/README.md.txt

Shows three alternative ways to retrieve data: submit (non-blocking), submit_and_wait_on_results (blocking), and download_results (blocking).

```python
>>> remote = client.submit(collection_id, request)  # doesn't block
>>> remote
Remote(...)
>>> remote.download("target_2.grib")  # blocks
'target_2.grib'

>>> results = client.submit_and_wait_on_results(collection_id, request)  # blocks
>>> results
Results(...)
>>> results.download("target_3.grib")
'target_3.grib'

>>> client.download_results(remote.request_id, "target_4.grib")  # blocks
'target_4.grib'
```

--------------------------------

### License

Source: https://ecmwf.github.io/ecmwf-datastores-client/README.html

The project's license text.

```text
Copyright 2022, European Union.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

```

--------------------------------

### datastores.Collection.begin_datetime

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Collection.html

Begin datetime of the collection.

```APIDOC
## datastores.Collection.begin_datetime

### Description
Begin datetime of the collection.

### Type
`datetime.datetime | None`

```

--------------------------------

### datastores.Remote.download()

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Remote.html

Downloads the results of the job. Optionally specifies a target path; if None, downloads to the working directory. Returns the path to the retrieved file.

```APIDOC
## datastores.Remote.download()

### Description
Download the results.

### Parameters
- **target** (str or None) - Optional - Target path. If None, download to the working directory.

### Returns
- **str** - Path to the retrieved file.

```

--------------------------------

### datastores.Client.submit()

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Client.html

Submits a request. This method is part of the datastores.Client class.

```APIDOC
## datastores.Client.submit()

### Description
Submits a request. This method is part of the datastores.Client class.

### Method
submit

### Signature
`datastores.Client.submit()`

### Return Type
`datastores.Results`
```

--------------------------------

### Retrieve data with client.retrieve

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/README.md.txt

Defines a request dictionary and retrieves data using client.retrieve, which blocks until the download is complete.

```python
>>> collection_id = "reanalysis-era5-pressure-levels"
>>> request = {
...     "product_type": ["reanalysis"],
...     "variable": ["temperature"],
...     "year": ["2022"],
...     "month": ["01"],
...     "day": ["01"],
...     "time": ["00:00"],
...     "pressure_level": ["1000"],
...     "data_format": "grib",
...     "download_format": "unarchived",
... }

>>> client.retrieve(collection_id, request, target="target_1.grib")  # blocks
'target_1.grib'
```

--------------------------------

### datastores.Collection.description

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Collection.html

Description of the collection.

```APIDOC
## datastores.Collection.description

### Description
Description of the collection.

### Type
`str`

```

--------------------------------

### datastores.Collection.url

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Collection.html

URL.

```APIDOC
## datastores.Collection.url

### Description
URL.

### Type
`str`

```

--------------------------------

### datastores.Client

Source: https://ecmwf.github.io/ecmwf-datastores-client/genindex.html

The Client class provides methods to interact with the datastores API, including authentication, collection retrieval, job submission, and result downloading.

```APIDOC
## datastores.Client

### Description
The Client class is the main entry point for interacting with the ECMWF Datastores API. It provides methods for authentication, retrieving collections, submitting jobs, and downloading results.

### Methods
- **apply_constraints()** - Applies constraints to a collection.
- **check_authentication()** - Checks if the client is authenticated.
- **delete()** - Deletes a remote resource.
- **download_results()** - Downloads results from a job.
- **get_collection()** - Retrieves a specific collection.
- **get_collections()** - Retrieves all collections.
- **get_jobs()** - Retrieves all jobs.
- **get_receipt()** - Retrieves a receipt for a job.
- **get_remote()** - Retrieves a remote resource.
- **get_results()** - Retrieves results from a job.
- **retrieve()** - Retrieves data from a collection.
- **submit()** - Submits a job.
- **submit_and_wait_on_results()** - Submits a job and waits for results.
```

--------------------------------

### Configure logging level

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/README.md.txt

Sets the logging level to INFO to display informational messages.

```python
>>> import logging
>>> logging.basicConfig(level="INFO")
```

--------------------------------

### check_authentication()

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Client.html

Verifies authentication and returns the response content.

```APIDOC
## check_authentication()

### Description
Verify authentication.

### Returns
Content of the response.

### Return Type
`dict[str,Any]`

### Raises
- **requests.HTTPError** – If the authentication fails.
```

--------------------------------

### Explore a collection

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/README.md.txt

Fetches a collection and inspects its metadata, including id, title, description, timestamps, bounding box, and methods to submit requests or apply constraints.

```python
>>> collection = client.get_collection(collection_id)

>>> collection.id == collection_id
True
>>> collection.title
'...'
>>> collection.description
'...'

>>> collection.published_at
datetime.datetime(...)
>>> collection.updated_at
datetime.datetime(...)

>>> collection.begin_datetime
datetime.datetime(...)
>>> collection.end_datetime
datetime.datetime(...)
>>> collection.bbox
(...)

>>> collection.submit(request)
Remote(...)

>>> collection.apply_constraints(request)
{...}
```

--------------------------------

### datastores.Remote.get_receipt()

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Remote.html

Retrieves the receipt for the job. Returns the content of the receipt as a dictionary.

```APIDOC
## datastores.Remote.get_receipt()

### Description
Retrieve receipt.

### Returns
- **dict[str, Any]** - Content of the receipt.

```

--------------------------------

### datastores.Collection.apply_constraints()

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Collection.html

Apply constraints to the parameters in a request. Returns a dictionary of valid values.

```APIDOC
## datastores.Collection.apply_constraints()

### Description
Apply constraints to the parameters in a request. Returns a dictionary of valid values.

### Method
apply_constraints

### Parameters
- **request** (`dict[str, Any]`) - Required - Request parameters.

### Returns
- `dict[str, Any]` - Dictionary of valid values.

```

--------------------------------

### datastores.Client.retrieve()

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Client.html

Retrieves data or resources. This method is part of the datastores.Client class.

```APIDOC
## datastores.Client.retrieve()

### Description
Retrieves data or resources. This method is part of the datastores.Client class.

### Method
retrieve

### Signature
`datastores.Client.retrieve()`

### Return Type
`datastores.Results`
```

--------------------------------

### datastores.Results.download

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/_api/datastores/Results.rst.txt

Downloads the results of a job to a specified target path or the working directory if no target is given. Returns the path to the retrieved file.

```APIDOC
## datastores.Results.download

### Description
Downloads the results of a job. If target is None, downloads to the working directory.

### Method
download

### Parameters
#### Parameters
- **target** (str or None) - Optional - Target path. If None, download to the working directory.

### Returns
- **str** - Path to the retrieved file.

```

--------------------------------

### datastores.Client.apply_constraints()

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Client.html

Applies constraints to a request or query. This method is part of the datastores.Client class.

```APIDOC
## datastores.Client.apply_constraints()

### Description
Applies constraints to a request or query. This method is part of the datastores.Client class.

### Method
apply_constraints

### Signature
`datastores.Client.apply_constraints()`

### Return Type
`datastores.Results`
```

--------------------------------

### datastores.Client.get_collections()

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Client.html

Retrieves all collections. This method is part of the datastores.Client class.

```APIDOC
## datastores.Client.get_collections()

### Description
Retrieves all collections. This method is part of the datastores.Client class.

### Method
get_collections

### Signature
`datastores.Client.get_collections()`

### Return Type
`datastores.Results`
```

--------------------------------

### datastores.Results.url

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Results.html

Property that returns the URL.

```APIDOC
## datastores.Results.url

### Description
Property that returns the URL.

### Returns
- **str** - URL.

```

--------------------------------

### datastores.Collection.bbox

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Collection.html

Bounding box of the collection (W, S, E, N).

```APIDOC
## datastores.Collection.bbox

### Description
Bounding box of the collection (W, S, E, N).

### Type
`tuple[float, float, float, float]`

```

--------------------------------

### datastores.Client.download_results()

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Client.html

Downloads the results of a request. This method is part of the datastores.Client class.

```APIDOC
## datastores.Client.download_results()

### Description
Downloads the results of a request. This method is part of the datastores.Client class.

### Method
download_results

### Signature
`datastores.Client.download_results()`

### Return Type
`datastores.Results`
```

--------------------------------

### apply_constraints(request)

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/_api/datastores/Collection.rst.txt

Applies constraints to the parameters in a request and returns a dictionary of valid values.

```APIDOC
## apply_constraints(request)

### Description
Applies constraints to the parameters in a request.

### Method
apply_constraints

### Parameters
- **request** (dict[str, Any]) - Required - Request parameters.

### Returns
- **dict[str, Any]** - Dictionary of valid values.

```

--------------------------------

### datastores.Collections.prev

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Collections.html

Property that returns the previous page of results, or None if there is no previous page.

```APIDOC
## datastores.Collections.prev

### Description
Returns the previous page of the paginated response.

### Property
`prev`

### Returns
- **Self | None** - Previous page or None if no previous page.

```

--------------------------------

### Commit and push formatted changes

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/README.md.txt

Commands to stage, commit, and push automatically formatted changes. The CI/CD pipeline triggers on pull requests, merges to main/upstream, and new releases.

```bash
git add .
git commit -m "format codebase and sync lockfile"
git push origin HEAD
```

--------------------------------

### submit(request)

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/_api/datastores/Collection.rst.txt

Submits a request and returns a Remote object for the submitted request.

```APIDOC
## submit(request)

### Description
Submits a request.

### Method
submit

### Parameters
- **request** (dict[str, Any]) - Required - Request parameters.

### Returns
- **datastores.Remote** - Remote object for the submitted request.

```

--------------------------------

### datastores.Client.submit_and_wait_on_results()

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Client.html

Submits a request and waits for the results. This method is part of the datastores.Client class.

```APIDOC
## datastores.Client.submit_and_wait_on_results()

### Description
Submits a request and waits for the results. This method is part of the datastores.Client class.

### Method
submit_and_wait_on_results

### Signature
`datastores.Client.submit_and_wait_on_results()`

### Return Type
`datastores.Results`
```

--------------------------------

### datastores.Collections.next

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Collections.html

Property that returns the next page of results, or None if there is no next page.

```APIDOC
## datastores.Collections.next

### Description
Returns the next page of the paginated response.

### Property
`next`

### Returns
- **Self | None** - Next page or None if no next page.

```

--------------------------------

### datastores.Collection.json

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Collection.html

Content of the response.

```APIDOC
## datastores.Collection.json

### Description
Content of the response.

### Type
`Any`

```

--------------------------------

### datastores.Client.check_authentication()

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Client.html

Checks the authentication status for the client. This method is part of the datastores.Client class.

```APIDOC
## datastores.Client.check_authentication()

### Description
Checks the authentication status for the client. This method is part of the datastores.Client class.

### Method
check_authentication

### Signature
`datastores.Client.check_authentication()`

### Return Type
`datastores.Results`
```

--------------------------------

### datastores.Collection.published_at

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Collection.html

When the collection was first published.

```APIDOC
## datastores.Collection.published_at

### Description
When the collection was first published.

### Type
`datetime.datetime`

```

--------------------------------

### submit(collection_id, request)

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/_api/datastores/Client.rst.txt

Submits a request to the datastore and returns a Remote object representing the submitted request.

```APIDOC
## submit(collection_id, request)

### Description
Submits a request to the datastore and returns a Remote object representing the submitted request.

### Method
submit

### Parameters
- **collection_id** (str) - Required - Collection ID (e.g., "projections-cmip6").
- **request** (dict[str, Any]) - Required - Request parameters.

### Returns
- **datastores.Remote** - Remote object for the submitted request.
```

--------------------------------

### retrieve(collection_id, request, target=None)

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/_api/datastores/Client.rst.txt

Retrieves data from a collection using the given request parameters and downloads it to the specified target path. Returns the path to the retrieved file.

```APIDOC
## retrieve(collection_id, request, target=None)

### Description
Retrieves data from a collection using the given request parameters and downloads it to the specified target path. Returns the path to the retrieved file.

### Method
retrieve

### Parameters
- **collection_id** (str) - Required - Collection ID (e.g., "projections-cmip6").
- **request** (dict[str, Any]) - Required - Request parameters.
- **target** (str or None) - Optional - Target path. If None, download to the working directory.

### Returns
- **str** - Path to the retrieved file.
```

--------------------------------

### datastores.Client

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/_api/datastores/Client.rst.txt

The main client class for the ECMWF Data Stores Service (DSS) API. It handles authentication, request submission, and result retrieval.

```APIDOC
## datastores.Client

### Description
ECMWF Data Stores Service (DSS) API Python client.

### Constructor Parameters
- **url** (str or None) - Optional - API URL. If None, inferred from ECMWF_DATASTORES_URL or ECMWF_DATASTORES_RC_FILE.
- **key** (str or None) - Optional - API Key. If None, inferred from ECMWF_DATASTORES_KEY or ECMWF_DATASTORES_RC_FILE.
- **verify** (bool) - Optional - Whether to verify the TLS certificate at the remote end. Default: True.
- **timeout** (float or tuple[float,float]) - Optional - How many seconds to wait for the server to send data, as a float, or a (connect, read) tuple. Default: 60.
- **progress** (bool) - Optional - Whether to display the progress bar during download. Default: True.
- **cleanup** (bool) - Optional - Whether to delete requests after completion. Default: False.
- **sleep_max** (float) - Optional - Maximum time to wait (in seconds) while checking for a status change. Default: 120.
- **retry_after** (float) - Optional - Time to wait (in seconds) between retries. Default: 120.
- **maximum_tries** (int) - Optional - Maximum number of retries. Default: 500.
- **session** (requests.Session) - Optional - Requests session.

### Methods

#### apply_constraints(collection_id, request)

Apply constraints to the parameters in a request.

**Parameters**
- **collection_id** (str) - Required - Collection ID (e.g., "projections-cmip6").
- **request** (dict[str,Any]) - Required - Request parameters.

**Returns**
- Dictionary of valid values (dict[str,Any]).

#### check_authentication()

Verify authentication.

**Returns**
- Content of the response (dict[str,Any]).

**Raises**
- requests.HTTPError - If the authentication fails.

#### delete(*request_ids)

Delete requests.

**Parameters**
- **\*request_ids** (str) - Required - Request IDs.

**Returns**
- Content of the response (dict[str,Any]).

#### download_results(request_id, target = None)

Download the results of a request.

**Parameters**
- **request_id** (str) - Required - Request ID.
- **target** (str or None) - Optional - Target path. If None, download to the working directory.

**Returns**
- Path to the retrieved file (str).

#### get_collection(collection_id)

Retrieve a catalogue collection.

**Parameters**
- **collection_id** (str) - Required - Collection ID (e.g., "projections-cmip6").

**Returns**
- datastores.Collection

#### get_collections(limit = None, sortby = None, query = None, keywords = None)

Retrieve catalogue collections.

**Parameters**
- **limit** (int or None) - Optional - Number of collections per page.
- **sortby** ({None, 'id', 'relevance', 'title', 'update'}) - Optional - Field to sort results by.
- **query** (str or None) - Optional - Full-text search query.
- **keywords** (list[str] or None) - Optional - Filter by keywords.

**Returns**
- datastores.Collections

#### get_jobs(limit = None, sortby = None, status = None)

Retrieve submitted jobs.

**Parameters**
- **limit** (int or None) - Optional - Number of jobs per page.
- **sortby** ({None, 'created', '-created'}) - Optional - Field to sort results by.
- **status** (None or {'accepted', 'running', 'successful', 'failed', 'rejected'} or list) - Optional - Status of the results.

**Returns**
- datastores.Jobs

#### get_receipt(request_id)

Retrieve the receipt of a request.

**Parameters**
- **request_id** (str) - Required - Request ID.

**Returns**
- Content of the receipt (dict[str,Any]).

#### get_remote(request_id)

Retrieve the remote object of a request.

**Parameters**
- **request_id** (str) - Required - Request ID.

**Returns**
- datastores.Remote

#### get_results(request_id)

Retrieve the results of a request.

**Parameters**
- **request_id** (str) - Required - Request ID.

**Returns**
- datastores.Results

#### retrieve(collection_id, request, target = None)

Submit a request and retrieve the results.

**Parameters**
- **collection_id** (str) - Required - Collection ID (e.g., "projections-cmip6").
- **request** (dict) - Required - Request parameters.
- **target** (str or None) - Optional - Target path for download.

**Returns**
- Path to the retrieved file (str).
```

--------------------------------

### datastores.Client.get_jobs()

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Client.html

Retrieves the jobs associated with the client. This method is part of the datastores.Client class.

```APIDOC
## datastores.Client.get_jobs()

### Description
Retrieves the jobs associated with the client. This method is part of the datastores.Client class.

### Method
get_jobs

### Signature
`datastores.Client.get_jobs()`

### Return Type
`datastores.Results`
```

--------------------------------

### get_results()

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/_api/datastores/Remote.rst.txt

Retrieves the results of the job. Returns a datastores.Results object.

```APIDOC
## get_results()

### Description
Retrieves the results.

### Method
get_results

### Returns
- **datastores.Results** - The results object.
```

--------------------------------

### datastores.Client.get_receipt()

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Client.html

Retrieves a receipt for a request. This method is part of the datastores.Client class.

```APIDOC
## datastores.Client.get_receipt()

### Description
Retrieves a receipt for a request. This method is part of the datastores.Client class.

### Method
get_receipt

### Signature
`datastores.Client.get_receipt()`

### Return Type
`datastores.Results`
```

--------------------------------

### get_receipt()

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/_api/datastores/Remote.rst.txt

Retrieves the receipt for the job. Returns the content of the receipt.

```APIDOC
## get_receipt()

### Description
Retrieves the receipt.

### Method
get_receipt

### Returns
- **dict[str, Any]** - Content of the receipt.
```

--------------------------------

### submit_and_wait_on_results(collection_id, request)

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/_api/datastores/Client.rst.txt

Submits a request and waits for the results to be ready, then returns a Results object.

```APIDOC
## submit_and_wait_on_results(collection_id, request)

### Description
Submits a request and waits for the results to be ready, then returns a Results object.

### Method
submit_and_wait_on_results

### Parameters
- **collection_id** (str) - Required - Collection ID (e.g., "projections-cmip6").
- **request** (dict[str, Any]) - Required - Request parameters.

### Returns
- **datastores.Results** - Results object containing the retrieved data.
```

--------------------------------

### datastores.Client.get_results()

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Client.html

Retrieves the results of a request. This method is part of the datastores.Client class.

```APIDOC
## datastores.Client.get_results()

### Description
Retrieves the results of a request. This method is part of the datastores.Client class.

### Method
get_results

### Signature
`datastores.Client.get_results()`

### Return Type
`datastores.Results`
```

--------------------------------

### datastores.Collection.title

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Collection.html

Title of the collection.

```APIDOC
## datastores.Collection.title

### Description
Title of the collection.

### Type
`str`

```

--------------------------------

### submit(collection_id, request)

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Client.html

Submits a request.

```APIDOC
## submit(collection_id, request)

### Description
Submit a request.

### Parameters
- **collection_id** (`str`) – Collection ID (e.g., `"projections-cmip6"`).
- **request** (`dict[str,Any]`) – Request parameters.

### Return Type
`datastores.Remote`
```

--------------------------------

### get_jobs(limit=None, sortby=None, status=None)

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Client.html

Retrieves submitted jobs with optional filtering and sorting.

```APIDOC
## get_jobs(limit=None, sortby=None, status=None)

### Description
Retrieve submitted jobs.

### Parameters
- **limit** (`int` or `None`) – Number of jobs per page.
- **sortby** (`{None, 'created', '-created'}`) – Field to sort results by.
- **status** (`None` or `{'accepted', 'running', 'successful', 'failed', 'rejected'}` or `list`) – Status of the results.

### Return Type
`datastores.Jobs`
```

--------------------------------

### datastores.Results.json

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Results.html

Property that returns the content of the response.

```APIDOC
## datastores.Results.json

### Description
Property that returns the content of the response.

### Returns
- **Any** - Content of the response.

```

--------------------------------

### Interact with results

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/README.md.txt

Retrieves results for a given request ID and downloads the data, checking content length, type, and location.

```python
>>> results = client.get_results(remote.request_id)

>>> results.content_length > 0
True
>>> results.content_type
'application/x-grib'
>>> results.location
'...'

>>> results.download("target_5.grib")
'target_5.grib'
```

--------------------------------

### datastores.Results.location

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Results.html

Property that returns the file location.

```APIDOC
## datastores.Results.location

### Description
Property that returns the file location.

### Returns
- **str** - File location.

```

--------------------------------

### get_collections(limit=None, sortby=None, query=None, keywords=None)

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Client.html

Retrieves catalogue collections with optional filtering and sorting.

```APIDOC
## get_collections(limit=None, sortby=None, query=None, keywords=None)

### Description
Retrieve catalogue collections.

### Parameters
- **limit** (`int | None`) – Number of collections per page.
- **sortby** (`{None, 'id', 'relevance', 'title', 'update'}`) – Field to sort results by.
- **query** (`str` or `None`) – Full-text search query.
- **keywords** (`list[str]` or `None`) – Filter by keywords.

### Return Type
`datastores.Collections`
```

--------------------------------

### datastores.Results.content_length

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Results.html

Property that returns the file size in bytes.

```APIDOC
## datastores.Results.content_length

### Description
Property that returns the file size in bytes.

### Returns
- **int** - File size in Bytes.

```

--------------------------------

### datastores.Collections.url

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Collections.html

Property that returns the URL of the current page.

```APIDOC
## datastores.Collections.url

### Description
Returns the URL of the current page.

### Property
`url`

### Returns
- **str** - URL.

```

--------------------------------

### datastores.Results.content_type

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Results.html

Property that returns the file MIME type.

```APIDOC
## datastores.Results.content_type

### Description
Property that returns the file MIME type.

### Returns
- **str** - File MIME type.

```

--------------------------------

### Apache License 2.0 text

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/README.md.txt

The project is licensed under the Apache License, Version 2.0. This block contains the full license text as displayed on the page.

```text
Copyright 2022, European Union.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```

--------------------------------

### datastores.Client.get_collection()

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Client.html

Retrieves a specific collection. This method is part of the datastores.Client class.

```APIDOC
## datastores.Client.get_collection()

### Description
Retrieves a specific collection. This method is part of the datastores.Client class.

### Method
get_collection

### Signature
`datastores.Client.get_collection()`

### Return Type
`datastores.Results`
```

--------------------------------

### datastores.Results

Source: https://ecmwf.github.io/ecmwf-datastores-client/genindex.html

The Results class represents the results of a job and provides methods to download and access result metadata.

```APIDOC
## datastores.Results

### Description
The Results class represents the results of a job. It provides methods to download results and access result metadata.

### Methods
- **download()** - Downloads the results.

### Properties
- **content_length** - The content length of the results.
- **content_type** - The content type of the results.
- **json** - The JSON representation of the results.
- **location** - The location of the results.
- **url** - The URL of the results.
```

--------------------------------

### List all collection IDs sorted by last update

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/README.md.txt

Retrieves all collection IDs using pagination, sorting by the 'update' field.

```python
>>> collections = client.get_collections(sortby="update")

>>> collection_ids = []
>>> while collections is not None:  # Loop over pages
...     collection_ids.extend(collections.collection_ids)
...     collections = collections.next  # Move to the next page
...

>>> collection_ids
[...]
>>> collection_id in collection_ids
True
```

--------------------------------

### Properties

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/_api/datastores/Collection.rst.txt

Collection properties providing metadata about the collection.

```APIDOC
## Properties

### bbox
- **type**: tuple[float, float, float, float]
- Bounding box of the collection (W, S, E, N).

### begin_datetime
- **type**: datetime.datetime | None
- Begin datetime of the collection.

### description
- **type**: str
- Description of the collection.

### end_datetime
- **type**: datetime.datetime | None
- End datetime of the collection.

### id
- **type**: str
- Collection ID.

### json
- **type**: Any
- Content of the response.

### published_at
- **type**: datetime.datetime
- When the collection was first published.

### title
- **type**: str
- Title of the collection.

### updated_at
- **type**: datetime.datetime
- When the collection was last updated.

### url
- **type**: str
- URL.

```

--------------------------------

### datastores.Results properties

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/_api/datastores/Results.rst.txt

Properties of the Results class that provide metadata about the job results: content_length, content_type, json, location, and url.

```APIDOC
## datastores.Results properties

### Description
Properties that expose metadata about the job results.

### Properties
- **content_length** (int) - File size in Bytes.
- **content_type** (str) - File MIME type.
- **json** (Any) - Content of the response.
- **location** (str) - File location.
- **url** (str) - URL.

```

--------------------------------

### download_results(request_id, target=None)

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Client.html

Downloads the results of a request.

```APIDOC
## download_results(request_id, target=None)

### Description
Download the results of a request.

### Parameters
- **request_id** (`str`) – Request ID.
- **target** (`str` or `None`) – Target path. If None, download to the working directory.

### Returns
Path to the retrieved file.

### Return Type
`str`
```

--------------------------------

### datastores.Jobs

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Jobs.html

A class to interact with submitted jobs. It inherits from ApiResponsePaginated and provides properties to access the response content, pagination links, request IDs, and URL.

```APIDOC
## datastores.Jobs

### Description
A class to interact with submitted jobs. It inherits from ApiResponsePaginated and provides properties to access the response content, pagination links, request IDs, and URL.

### Properties

#### json
- **Type**: Any
- **Description**: Content of the response.

#### next
- **Type**: Self | None
- **Description**: Next page.

#### prev
- **Type**: Self | None
- **Description**: Previous page.

#### request_ids
- **Type**: list[str]
- **Description**: List of request IDs.

#### url
- **Type**: str
- **Description**: URL.
```

--------------------------------

### apply_constraints(collection_id, request)

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Client.html

Applies constraints to the parameters in a request.

```APIDOC
## apply_constraints(collection_id, request)

### Description
Apply constraints to the parameters in a request.

### Parameters
- **collection_id** (`str`) – Collection ID (e.g., `"projections-cmip6"`).
- **request** (`dict[str,Any]`) – Request parameters.

### Returns
Dictionary of valid values.

### Return Type
`dict[str,Any]`
```

--------------------------------

### datastores.Collection

Source: https://ecmwf.github.io/ecmwf-datastores-client/genindex.html

The Collection class represents a data collection and provides methods to apply constraints, submit jobs, and access collection metadata.

```APIDOC
## datastores.Collection

### Description
The Collection class represents a data collection in the datastores system. It provides methods to apply constraints, submit jobs, and access collection metadata.

### Methods
- **apply_constraints()** - Applies constraints to the collection.
- **submit()** - Submits a job for this collection.

### Properties
- **bbox** - The bounding box of the collection.
- **begin_datetime** - The beginning datetime of the collection.
- **description** - The description of the collection.
- **end_datetime** - The ending datetime of the collection.
- **id** - The unique identifier of the collection.
- **json** - The JSON representation of the collection.
- **published_at** - The publication timestamp of the collection.
- **title** - The title of the collection.
- **updated_at** - The last update timestamp of the collection.
- **url** - The URL of the collection.
```

--------------------------------

### datastores.Remote properties

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Remote.html

Properties of the Remote class that provide metadata about the job.

```APIDOC
## datastores.Remote Properties

### collection_id
- **str** - Collection ID.

### created_at
- **datetime.datetime** - When the job was created.

### finished_at
- **datetime.datetime | None** - When the job finished (None if pending execution or served from cache).

### json
- **dict[str, Any]** - Content of the response.

### request
- **dict[str, Any]** - Request parameters.

### request_id
- **str** - Request ID.

### results_ready
- **bool** - Check if results are ready.

### started_at
- **datetime.datetime | None** - When the job started (None if pending execution or served from cache).

### status
- **str** - Request status.

### updated_at
- **datetime.datetime** - When the job was last updated.

```

--------------------------------

### datastores.Remote

Source: https://ecmwf.github.io/ecmwf-datastores-client/genindex.html

The Remote class represents a remote resource and provides methods to delete, download, and retrieve receipts and results.

```APIDOC
## datastores.Remote

### Description
The Remote class represents a remote resource, such as a job or a result. It provides methods to delete, download, and retrieve receipts and results.

### Methods
- **delete()** - Deletes the remote resource.
- **download()** - Downloads the remote resource.
- **get_receipt()** - Retrieves the receipt for the remote resource.
- **get_results()** - Retrieves the results of the remote resource.

### Properties
- **collection_id** - The ID of the collection associated with the remote resource.
- **content_length** - The content length of the remote resource.
- **content_type** - The content type of the remote resource.
- **created_at** - The creation timestamp of the remote resource.
- **finished_at** - The finish timestamp of the remote resource.
- **json** - The JSON representation of the remote resource.
- **request** - The request associated with the remote resource.
- **request_id** - The request ID of the remote resource.
- **results_ready** - Indicates if results are ready.
- **started_at** - The start timestamp of the remote resource.
- **status** - The status of the remote resource.
- **updated_at** - The last update timestamp of the remote resource.
```

--------------------------------

### datastores.Collection.id

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Collection.html

Collection ID.

```APIDOC
## datastores.Collection.id

### Description
Collection ID.

### Type
`str`

```

--------------------------------

### datastores.Collections.json

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Collections.html

Property that returns the content of the response as a JSON object.

```APIDOC
## datastores.Collections.json

### Description
Returns the content of the response.

### Property
`json`

### Returns
- **Any** - Content of the response.

```

--------------------------------

### datastores.Client.delete()

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Client.html

Deletes a resource or data. This method is part of the datastores.Client class.

```APIDOC
## datastores.Client.delete()

### Description
Deletes a resource or data. This method is part of the datastores.Client class.

### Method
delete

### Signature
`datastores.Client.delete()`

### Return Type
`datastores.Results`
```

--------------------------------

### datastores.Client.get_remote()

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Client.html

Retrieves remote data or resources. This method is part of the datastores.Client class.

```APIDOC
## datastores.Client.get_remote()

### Description
Retrieves remote data or resources. This method is part of the datastores.Client class.

### Method
get_remote

### Signature
`datastores.Client.get_remote()`

### Return Type
`datastores.Results`
```

--------------------------------

### datastores.Remote.delete()

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Remote.html

Deletes the job. Returns the content of the response as a dictionary.

```APIDOC
## datastores.Remote.delete()

### Description
Delete the job.

### Method
DELETE

### Returns
- **dict[str, Any]** - Content of the response.

```

--------------------------------

### delete()

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/_api/datastores/Remote.rst.txt

Deletes the job. Returns the content of the response.

```APIDOC
## delete()

### Description
Deletes the job.

### Method
delete

### Returns
- **dict[str, Any]** - Content of the response.
```

--------------------------------

### datastores.Collection.updated_at

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Collection.html

When the collection was last updated.

```APIDOC
## datastores.Collection.updated_at

### Description
When the collection was last updated.

### Type
`datetime.datetime`

```

--------------------------------

### datastores.Collections

Source: https://ecmwf.github.io/ecmwf-datastores-client/_sources/_api/datastores/Collections.rst.txt

A class to interact with catalogue collections. It inherits from ApiResponsePaginated and provides properties for collection IDs, JSON content, pagination (next/prev), and the URL.

```APIDOC
## datastores.Collections

### Description
A class to interact with catalogue collections. It inherits from `ecmwf.datastores.processing.ApiResponsePaginated`.

### Properties

#### collection_ids
- **type**: list[str]
- **description**: List of collection IDs.

#### json
- **type**: Any
- **description**: Content of the response.

#### next
- **type**: Self | None
- **description**: Next page.

#### prev
- **type**: Self | None
- **description**: Previous page.

#### url
- **type**: str
- **description**: URL.

```

--------------------------------

### get_receipt(request_id)

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Client.html

Retrieves the receipt of a request.

```APIDOC
## get_receipt(request_id)

### Description
Retrieve the receipt of a request.

### Parameters
- **request_id** (`str`) – Request ID.

### Returns
Content of the receipt.

### Return Type
`dict[str,Any]`
```

--------------------------------

### get_results(request_id)

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Client.html

Retrieves the results of a request.

```APIDOC
## get_results(request_id)

### Description
Retrieve the results of a request.

### Parameters
- **request_id** (`str`) – Request ID.

### Return Type
`datastores.Results`
```

--------------------------------

### get_collection(collection_id)

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Client.html

Retrieves a catalogue collection by ID.

```APIDOC
## get_collection(collection_id)

### Description
Retrieve a catalogue collection.

### Parameters
- **collection_id** (`str`) – Collection ID (e.g., `"projections-cmip6"`).

### Return Type
`datastores.Collection`
```

--------------------------------

### datastores.Collection.end_datetime

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Collection.html

End datetime of the collection.

```APIDOC
## datastores.Collection.end_datetime

### Description
End datetime of the collection.

### Type
`datetime.datetime | None`

```

--------------------------------

### get_remote(request_id)

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Client.html

Retrieves the remote object of a request.

```APIDOC
## get_remote(request_id)

### Description
Retrieve the remote object of a request.

### Parameters
- **request_id** (`str`) – Request ID.

### Return Type
`datastores.Remote`
```

--------------------------------

### datastores.Collections.collection_ids

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Collections.html

Property that returns a list of collection IDs from the catalogue collections response.

```APIDOC
## datastores.Collections.collection_ids

### Description
Returns the list of collection IDs.

### Property
`collection_ids`

### Returns
- **list[str]** - List of collection IDs.

```

--------------------------------

### delete(*request_ids)

Source: https://ecmwf.github.io/ecmwf-datastores-client/_api/datastores/Client.html

Deletes the specified requests.

```APIDOC
## delete(*request_ids)

### Description
Delete requests.

### Parameters
- ***request_ids** (`str`) – Request IDs.

### Returns
Content of the response.

### Return Type
`dict[str,Any]`
```
Tokens:
Raw