Climate Data Store API Client

0.7.7 · active · verified Tue Apr 14

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.

Warnings

gotcha Authentication 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.
breaking Since `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`.
gotcha The 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.
gotcha Retrieving 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.

Install

pip install cdsapi Install `cdsapi`

Imports

Client
```
import cdsapi
c = cdsapi.Client()
```
The primary class for interacting with the CDS API.

Quickstart

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

view raw JSON →