How to use the CDS API

A new CDS soon to be launched - expect some disruptions and watch this page for latest. Thank you.

The Climate Data Store (CDS) Application Program Interface (API) is a service providing programmatic access to CDS data. In this page you will find explanations and examples showing how to use the CDS API. 

For troubleshooting, check Common Error Messages for CDS Requests

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
Install the CDS API key
  1. If you don't have an account, please self register at the CDS 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).

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")
ERA5 request example:
#!/usr/bin/env python
import cdsapi
c = cdsapi.Client()
c.retrieve("reanalysis-era5-pressure-levels",
{
"variable": "temperature",
"pressure_level": "1000",
"product_type": "reanalysis",
"year": "2008",
"month": "01",
"day": "01",
"time": "12:00",
"format": "grib"
}, "download.grib")
​
 

 

Glaciers request example:
#!/usr/bin/env python
import cdsapi
c = cdsapi.Client()
c.retrieve("insitu-glaciers-elevation-mass",
{
"variable": "all",
"product_type": "elevation_change",
"file_version": "20170405",
"format": "tgz"
},
"download.tar.gz")
​