How to use the CDS API

There will be no access to CAMS European forecast data for dates more than 4 days old on Wednesday 24 April from 8am to 1pm BST due to essential maintenance work. We apologise for any inconvenience. Forecasts for the past 4 days will continue to be available as usual.
A new ADS soon to be launched - expect some disruptions and watch this page for latest. Thank you.

The CDS API is a service providing programmatic access to ADS data. In this page you will find explanations and examples showing how to use the CDS API

For Windows users, please read How to install and use CDS API on Windows

For macOS users, please read How to install and use CDS API on macOS

For linux users, please proceed as follows:

  1. Install the CDS API key
  2. Install the CDS API client
  3. Use the CDS API client for data access

If, after installing the API, you encounter errors in your requests please consult this page on common error messages for CDS requests.

Install the CDS API key
  1. If you don't have an account, please self register at the ADS registration page and go to the steps below.

  2. If you are not logged, please login and go to the step below.

  3. Copy the code displayed beside, in the file $HOME/.cdsapirc (in your Unix/Linux environment).

    (Note that the separate Copernicus Climate Change Service uses the same CDS API software while providing access to different datasets. If you are using this service and so already have a key stored in ~/.cdsapirc then you will have to store your ADS key elsewhere and pass the key information to the client library explicitly. See below for more details).

url: {api-url}
key: {uid}:{api-key}
Install the CDS API client

The CDS API client is a python based library. It provides support for both Python 2.7.x and Python 3.

You can Install the CDS API client via the package management system pip, by running on Unix/Linux the command shown in the box beside.

$ pip install cdsapi
Use the CDS API client for data access

Once the CDS API client is installed, it can be used to request data from the datasets listed in the CDS catalogue. It is necessary to agree to the Terms of Use of every datasets that you intend to download.

Attached to each dataset download form, the following button    displays the python code to be used. The request can be formatted using the interactive form. The api call must follow the syntax:

    import cdsapi
    c = cdsapi.Client()

    c.retrieve("dataset-short-name", 
               {... sub-selection request ...}, 
               "target-file")

If you have more than one CDS API key and therefore have to pass credentials in explicitly (see above) you can use the following method:

    import cdsapi
    import yaml

    with open('/path/to/ads/cdsapirc', 'r') as f:
            credentials = yaml.safe_load(f)

    c = cdsapi.Client(url=credentials['url'], key=credentials['key'])

    c.retrieve("dataset-short-name", 
               {... sub-selection request ...}, 
               "target-file")