{"id":5919,"library":"ecmwf-datastores-client","title":"ECMWF Data Stores Service (DSS) API Python Client","description":"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.","status":"active","version":"0.5.1","language":"en","source_language":"en","source_url":"https://github.com/ecmwf/ecmwf-datastores-client","tags":["ECMWF","data-access","climate","meteorology","API client"],"install":[{"cmd":"pip install ecmwf-datastores-client","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"Client","correct":"from ecmwf.datastores import Client"}],"quickstart":{"code":"import os\nfrom ecmwf.datastores import Client\n\n# Configure API key and URL via environment variables for a runnable example\n# Alternatively, pass 'url' and 'key' as keyword arguments to Client()\n# or use a configuration file (~/.ecmwfdatastoresrc).\n\nclient = Client(\n    url=os.environ.get('ECMWF_DATASTORES_URL', 'https://data-stores.ecmwf.int/api'),\n    key=os.environ.get('ECMWF_DATASTORES_KEY', '')\n)\n\n# Optional: verify authentication (requires a valid key/url)\n# try:\n#     client.check_authentication()\n#     print(\"Authentication successful!\")\n# except Exception as e:\n#     print(f\"Authentication failed: {e}\")\n\n# Example: List available collections (requires authentication and access rights)\n# try:\n#     collections = client.list_collections()\n#     for collection in collections:\n#         print(f\"Collection ID: {collection.id}, Title: {collection.title}\")\n# except Exception as e:\n#     print(f\"Could not list collections: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Monitor official GitHub releases and documentation for updates. Pin specific versions in your `requirements.txt` or `pyproject.toml`.","message":"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.","severity":"gotcha","affected_versions":"All versions up to 0.5.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions up to 0.5.1"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}