ECMWF Data Stores Service (DSS) API Python Client

0.5.1 · active · verified Tue Apr 14

The `ecmwf-datastores-client` is a Python library providing programmatic access to the ECMWF Data Stores Service (DSS) API. It allows users to interact with data catalogues like the Climate Data Store (CDS), Atmosphere Data Store (ADS), and Early Warning Data Store (EWDS) for metadata retrieval, synchronous or asynchronous job submission, and data download. Currently at version 0.5.1, it is in an 'Incubating' state, implying a mostly stable interface but with a readiness for incoming changes.

Warnings

gotcha This library is 'Incubating'. While the interface is mostly stable, users should anticipate and be willing to accept breaking changes or bug fixes that may require adaptations in their code. It is not yet recommended for critical operational systems without careful version pinning.
Fix: Monitor official GitHub releases and documentation for updates. Pin specific versions in your `requirements.txt` or `pyproject.toml`.
gotcha Users of the older `cdsapi` package are explicitly *not* requested to migrate to `ecmwf-datastores-client` at this time. `cdsapi` remains a supported and distinct client for some use cases.
Fix: Carefully review ECMWF's recommendations for your specific data access needs. Do not migrate from `cdsapi` unless explicitly advised or if the advanced features of `ecmwf-datastores-client` are required.
breaking Before requesting data for certain datasets, users must manually agree to the Terms of Use via the dataset's web page on the respective Data Store (e.g., CDS). API requests will fail if these terms are not accepted.
Fix: Always visit the dataset's page on the ECMWF Data Store website and explicitly agree to its terms and conditions before attempting to retrieve data programmatically.
gotcha Authentication requires an API key and a URL. These can be provided via keyword arguments to `Client()`, environment variables (`ECMWF_DATASTORES_URL`, `ECMWF_DATASTORES_KEY`), or a configuration file (e.g., `~/.ecmwfdatastoresrc`). Incorrect or missing credentials will lead to authentication failures.
Fix: Ensure `ECMWF_DATASTORES_URL` and `ECMWF_DATASTORES_KEY` are set in your environment, or pass them directly to the `Client` constructor. For production, consider using a configuration file or a secure secrets management system.
gotcha Common issues encountered with ECMWF APIs (which may also apply to `ecmwf-datastores-client`) include network-related timeouts, invalid request parameters (e.g., no data for the requested subset, ambiguous keywords), or connection problems with underlying data archives (MARS).
Fix: For timeouts, check network connectivity and server status at status.ecmwf.int. For invalid requests, verify parameters against the dataset's web form. Consult ECMWF's troubleshooting documentation.

Install

pip install ecmwf-datastores-client Install stable version

Imports

Client
```
from ecmwf.datastores import Client
```

Quickstart

Initializes the `ecmwf-datastores-client` and demonstrates how to configure it using environment variables for API URL and key. It also includes commented-out examples for checking authentication and listing data collections, which require a valid API key and URL.

import os
from ecmwf.datastores import Client

# Configure API key and URL via environment variables for a runnable example
# Alternatively, pass 'url' and 'key' as keyword arguments to Client()
# or use a configuration file (~/.ecmwfdatastoresrc).

client = Client(
    url=os.environ.get('ECMWF_DATASTORES_URL', 'https://data-stores.ecmwf.int/api'),
    key=os.environ.get('ECMWF_DATASTORES_KEY', '')
)

# Optional: verify authentication (requires a valid key/url)
# try:
#     client.check_authentication()
#     print("Authentication successful!")
# except Exception as e:
#     print(f"Authentication failed: {e}")

# Example: List available collections (requires authentication and access rights)
# try:
#     collections = client.list_collections()
#     for collection in collections:
#         print(f"Collection ID: {collection.id}, Title: {collection.title}")
# except Exception as e:
#     print(f"Could not list collections: {e}")

view raw JSON →