Login - Register
CDSAPI setup
The Climate Data Store (CDS) Application Program Interface (API) is a service providing programmatic access to CDS, ADS, ECDS and CEMS Early Warning DS 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
Windows users
Please read How to install and use CDS API on Windows
macOS users
Please read How to install and use CDS API on macOS
Linux users
Please proceed as follows:1. Setup the CDS API personal access token
Here is how to setup the CDS API personal access token:- If you do not have an account yet, please register.
- If you are not logged in, please login.
- Once logged in, copy the code displayed below to the file $HOME/.cdsapirc
(in your Unix/Linux environment)
url: https://ecds-prod.ecmwf.int/api
key: <PERSONAL-ACCESS-TOKEN>
2. Install the CDS API client
The CDS API client is a Python based library. It provides support for Python 3.
You can install the CDS API client via the package management system pip, by running on Unix/Linux the command below.
$ pip install "cdsapi>=0.7.2"3. 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, ADS, ECDS and CEMS Early Warning DS catalogues.
One must agree to the Terms of Use of a dataset before downloading any data out of it. This step must be done manually from the dataset page (at the bottom of the download form).
At the bottom of each dataset download form, press the "Show API request code" button to display a Python code snippet that can be used to run the manually built request. The API call must have this syntax:
import cdsapi
client = cdsapi.Client()
dataset = "<DATASET-SHORT-NAME>"
request = {
<SELECTION-REQUEST>
}
target = "<TARGET-FILE>"
client.retrieve(dataset, request, target)
Example
import cdsapi
client = cdsapi.Client()
dataset = 's2s-forecasts'
request = {
'origin': 'ecmwf',
'forecast_type': 'control_forecast',
'level_type': 'single_level',
'variable': ['2m_temperature'],
'year': ['2023'],
'month': ['01'],
'day': ['30'],
'leadtime_hour': ['024'],
'time': ['00:00'],
'data_format': 'grib',
}
target = 'download.grib'
client.retrieve(dataset, request, target)