Registry / http-networking / cdsapi

cdsapi

JSON →
library0.7.7pypypi✓ verified 87d ago

The `cdsapi` library provides a Python interface to access the Copernicus Climate Change Service (C3S) Climate Data Store (CDS) API. It allows users to programmatically search, retrieve, and download vast amounts of climate data. Currently at version 0.7.7, it receives active maintenance and updates, with minor releases typically every few weeks to months, often addressing compatibility with the evolving CDS backend.

pip install cdsapi
INSTALL
IMPORT
SIG · CDSAPI
C
cdsapi
http-networkingpythonv0.7.7
Install
2.8s avg
Import
640ms
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.7.7 · 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.673s · 26.7MB
glibc
py 3.10–3.920 runs
installs and imports cleanly · install 2.8s · import 0.607s · 27MB
25MB installed
● package 25MB
Code
Verified usage

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

Client
✓ from cdsapi import Client
✗ import cdsapi

This quickstart demonstrates how to initialize the `cdsapi.Client` and make a basic data retrieval request for ERA5 reanalysis data. Ensure your CDS API credentials are set up either in `~/.cdsapirc` or via environment variables (`CDSAPI_URL`, `CDSAPI_KEY`) before running, as the example uses placeholders.

import cdsapi import os # Your CDS API Key and URL are required for authentication. # These are typically stored in a file ~/.cdsapirc or as environment variables. # For this quickstart, we simulate fetching from environment variables. # In a real setup, ensure CDSAPI_URL and CDSAPI_KEY are properly configured. # Example: # export CDSAPI_URL="https://cds.climate.copernicus.eu/api/v2" # export CDSAPI_KEY="YOUR_UID:YOUR_API_KEY" cds_url = os.environ.get('CDSAPI_URL', 'https://cds.climate.copernicus.eu/api/v2') cds_key = os.environ.get('CDSAPI_KEY', '12345:some-dummy-key-for-test-validation') if 'some-dummy-key' in cds_key: print("WARNING: CDSAPI_URL and CDSAPI_KEY environment variables are not set, " "or ~/.cdsapirc is missing. This code will likely fail without proper credentials.") try: # Initialize the client. It will automatically look for .cdsapirc or environment variables. # Explicitly passing url/key is also an option. c = cdsapi.Client(url=cds_url, key=cds_key) print("Attempting to retrieve 2m temperature for Jan 1, 2023, 12:00 from ERA5 single levels...") c.retrieve( 'reanalysis-era5-single-levels', { 'product_type': 'reanalysis', 'variable': '2m_temperature', 'year': '2023', 'month': '01', 'day': '01', 'time': '12:00', 'format': 'grib', 'area': '50/-10/40/0' # N/W/S/E, e.g., for a small area over UK/France }, 'era5-2m-temperature-2023-01-01-subset.grib' # Output filename ) print("Retrieval request sent. Check for 'era5-2m-temperature-2023-01-01-subset.grib' file.") except Exception as e: print(f"An error occurred during data retrieval: {e}") print("Please ensure your CDS API credentials are correctly configured in ~/.cdsapirc or as environment variables.")
cdsapi --version
Debug
Known issues
gotchaAuthentication requires a `.cdsapirc` file in the user's home directory (`~/.cdsapirc`) or setting `CDSAPI_URL` and `CDSAPI_KEY` environment variables. Missing or incorrect credentials are the most common reason for connection errors.
fix
Create `~/.cdsapirc` with `url: <CDSAPI_URL>` and `key: <YOUR_UID>:<YOUR_API_KEY>`, or set the corresponding environment variables. Register at [cds.climate.copernicus.eu](https://cds.climate.copernicus.eu/user/register) to get your UID and API Key.
affects: All versions
breakingSince `cdsapi` versions 0.7.x (e.g., 0.7.1, 0.7.2), the library enforces strict minimum versions for its underlying `cads-api-client` dependency. Upgrading `cdsapi` without also upgrading `cads-api-client` to a compatible version will lead to import or runtime errors.
fix
Always ensure `cads-api-client` is updated to the version required by your `cdsapi` version. Use `pip install --upgrade cdsapi cads-api-client`.
affects: >=0.7.0
gotchaThe parameters for the `retrieve()` method are highly specific to the dataset being requested from the CDS. Supplying incorrect or incompatible parameters will result in API errors (e.g., `KeyError`, `ClientError`) or unexpected data.
fix
Consult the CDS website for the specific dataset's documentation and available parameters. Use the web interface to build a request, then translate the generated API request into Python code.
affects: All versions
gotchaRetrieving large datasets can consume significant bandwidth and storage, and operations can be blocking for extended periods. Network timeouts can occur for very large requests or slow connections, potentially leading to incomplete downloads.
fix
For large datasets, consider requesting smaller chunks (e.g., by year/month) or using asynchronous download mechanisms if available. Implement robust error handling and retry logic around `retrieve()` calls.
affects: All versions
Upgrade
Version history
0.7.7latest on PyPI · released Sep 30, 2025
Audit
Dependencies
cads-api-clientrequiredCore client for interacting with the CDS API, tightly coupled and frequently updated.
Agent activity
58 hits · last 30 days
node
56
OpenAI (training)
1
Resources
cdsapi — pip install cdsapi · libregistry