{"id":5873,"library":"cdsapi","title":"Climate Data Store API Client","description":"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.","status":"active","version":"0.7.7","language":"en","source_language":"en","source_url":"https://github.com/ecmwf/cdsapi","tags":["climate data","ECMWF","API client","Copernicus"],"install":[{"cmd":"pip install cdsapi","lang":"bash","label":"Install `cdsapi`"}],"dependencies":[{"reason":"Core client for interacting with the CDS API, tightly coupled and frequently updated.","package":"cads-api-client","optional":false}],"imports":[{"note":"The primary class for interacting with the CDS API.","symbol":"Client","correct":"import cdsapi\nc = cdsapi.Client()"}],"quickstart":{"code":"import cdsapi\nimport os\n\n# Your CDS API Key and URL are required for authentication.\n# These are typically stored in a file ~/.cdsapirc or as environment variables.\n# For this quickstart, we simulate fetching from environment variables.\n# In a real setup, ensure CDSAPI_URL and CDSAPI_KEY are properly configured.\n# Example:\n# export CDSAPI_URL=\"https://cds.climate.copernicus.eu/api/v2\"\n# export CDSAPI_KEY=\"YOUR_UID:YOUR_API_KEY\"\n\ncds_url = os.environ.get('CDSAPI_URL', 'https://cds.climate.copernicus.eu/api/v2')\ncds_key = os.environ.get('CDSAPI_KEY', '12345:some-dummy-key-for-test-validation')\n\nif 'some-dummy-key' in cds_key:\n    print(\"WARNING: CDSAPI_URL and CDSAPI_KEY environment variables are not set, \"\n          \"or ~/.cdsapirc is missing. This code will likely fail without proper credentials.\")\n\ntry:\n    # Initialize the client. It will automatically look for .cdsapirc or environment variables.\n    # Explicitly passing url/key is also an option.\n    c = cdsapi.Client(url=cds_url, key=cds_key)\n\n    print(\"Attempting to retrieve 2m temperature for Jan 1, 2023, 12:00 from ERA5 single levels...\")\n    c.retrieve(\n        'reanalysis-era5-single-levels',\n        {\n            'product_type': 'reanalysis',\n            'variable': '2m_temperature',\n            'year': '2023',\n            'month': '01',\n            'day': '01',\n            'time': '12:00',\n            'format': 'grib',\n            'area': '50/-10/40/0' # N/W/S/E, e.g., for a small area over UK/France\n        },\n        'era5-2m-temperature-2023-01-01-subset.grib' # Output filename\n    )\n    print(\"Retrieval request sent. Check for 'era5-2m-temperature-2023-01-01-subset.grib' file.\")\nexcept Exception as e:\n    print(f\"An error occurred during data retrieval: {e}\")\n    print(\"Please ensure your CDS API credentials are correctly configured in ~/.cdsapirc or as environment variables.\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always ensure `cads-api-client` is updated to the version required by your `cdsapi` version. Use `pip install --upgrade cdsapi cads-api-client`.","message":"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.","severity":"breaking","affected_versions":">=0.7.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","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"}