Registry / http-networking / ecmwf-datastores-client

ecmwf-datastores-client

library0.5.1pypypi✓ verified 86d ago

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.

http-networking data

pip install ecmwf-datastores-client

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · ECMWF-DATASTORES-C

ecmwf-datastores-client

http-networkingpythonv0.5.1

Install

2.7s avg

Import

716ms

Disk

25MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.5.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.755s · 26.6MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.7s · import 0.677s · 27MB

25MB installed

● package 25MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client

✓ from ecmwf.datastores import Client

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}")

edc --version

Debug

Known issues

gotchaThis 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`.

affects: All versions up to 0.5.1

gotchaUsers 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.

affects: All versions up to 0.5.1

breakingBefore 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.

affects: All versions

gotchaAuthentication 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.

affects: All versions

gotchaCommon 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.

affects: All versions

Errors

Common errors & fixes

Missing or invalid authentication credentials

The API client cannot authenticate because the necessary API URL and key are not provided or are incorrect. This can be due to missing environment variables (ECMWF_DATASTORES_URL, ECMWF_DATASTORES_KEY), an incorrect `~/.ecmwfdatastoresrc` configuration file, or not passing them directly to the `Client` constructor.

fix

Ensure that `ECMWF_DATASTORES_URL` and `ECMWF_DATASTORES_KEY` environment variables are set, or provide them as `url` and `key` keyword arguments when instantiating `Client()`. Alternatively, create or verify the `~/.ecmwfdatastoresrc` file with `url` and `key` entries in the correct format.

Connection timed out. (connect timeout=XX)

The client failed to establish a connection to the ECMWF Data Stores API within the allotted time, often due to network issues, firewall restrictions, or the server being unresponsive.

fix

Check your internet connection and proxy settings. Ensure that the necessary ports (HTTPS, 443) are open on your firewall. You can also try increasing the timeout duration if supported by the client, or check the ECMWF status page (status.ecmwf.int) for service outages.

Client has not agreed to the required terms and conditions.

To download data from certain datasets, users must manually agree to their specific terms and conditions via the dataset's web page on the respective Data Store (e.g., CDS, ADS). Programmatic requests will fail if this step is not completed.

fix

Visit the specific dataset's page on the ECMWF Data Store website (e.g., CDS, ADS portal), log in, and explicitly agree to the terms of use before attempting to retrieve the data programmatically.

HTTPError: 404 Client Error: Not Found for url:

This error typically indicates that the requested dataset ID or API endpoint is incorrect, or the URL configured for the client does not match the service where the data resides (e.g., trying to access ADS data via a CDS URL). It can also mean that no data matches the submitted request parameters.

fix

Verify the `collection_id` (dataset ID) in your request. Check that the `url` in your client configuration (or environment variable `ECMWF_DATASTORES_URL`) points to the correct Data Store API (e.g., CDS, ADS, EWDS) for the data you are trying to access. Use the web form on the dataset's page to confirm valid request parameters and generate a correct API request code.

Upgrade

Version history

0.5.1latest on PyPI · released Mar 31, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

34 hits · last 30 days

node