Skip to end of metadata
Go to start of metadata

Web API access to ERA5 was stopped on 5th March 2019.

This article describes how to switch from using the ECMWF Web API to using the CDS API for Copernicus Climate Change Service (C3S) data users.


Before the release of Copernicus Climate Change Service (C3S) Climate Data Store (CDS) on 14th June 2018, two C3S datasets ERA5 and Seasonal Forecasts were hosted at the ECMWF data server and made available though the ECMWF Web API, the programmatic way of retrieving data.

As the Climate Data Store will soon become the only source for both datasets, users need to migrate to CDS. The CDS offers many more datasets and much richer functionalities ranging from data access to tool/application development.

Good to know

  • MIR is the interpolation software used in CDS, please read MARS interpolation with MIR for more information.
  • In CDS, you can make use of tools (CDS Toolbox) to process data directly without downloading it to your local machine.
  • If you want to download data for a long time period, it is best practice to loop over years and months when making data request.


  1. Python and pip: You are expected to have at least some basic understanding of Python and in particular know how to install packages on your local machine using pip.
  2. Install the CDS API:
    • on linux or on cygwyn (using pip), please follow the instructions HERE.
    • Windows users may follow the instructions HERE instead.
    • On systems running Anaconda, you can install using conda:

      /<install_path>/conda/anaconda2/bin/conda config --add channels conda-forge
      /<install_path>/conda/anaconda2/bin/conda install cdsapi
  3. You are recommended to use the latest release of packages:  CDS API (tested with version 0.1.1)
  4. CDS account - If you do not yet have a CDS account, please create one HERE.
  5. Data licence  - Before you may download any data from the CDS, you need to have accepted the Terms and Conditions of the dataset of choice. Further details below on how to do this.

Steps to accept data licence and generate a basic CDS API script using the CDS web interface:

  1. Go to the C3S climate data store (CDS)
  2. On the top menu bar, click on 'Datasets'
  3. On the left-hand side menu, expand 'Product type' and select Product type of interest (e.g. 'Seasonal forecasts' to get all seasonal forecasts data listed, 'Reanalysis' for ERA5 datasets)
  4. Follow the dataset title link of interest to the full dataset record
  5. Accept dataset licence and generate basic CDS API script

The full dataset record includes:

  • Overview tab. This gives a description of the selected dataset and metadata information (e.g. spatial details, file format, variables, etc).
  • Documentation tab. This provides links to detailed documentation about the dataset.
  • Download data tab. This is a Download data web form. Using this web interface, you can:
    • make selections as per your requirements
    • submit your request online (you will need to login if not already logged in)  
      (warning) Tip: Upon submitting the download form, you will be prompted to accept the data licence (if you have not yet accepted it)! Please note that whether you are downloading the data through the web interface or through the CDS API, you must accept the data licence.
    • display the API script which corresponds to your selection, by clicking on the "Show API request" button.

At this stage, you can test that CDS API is working for you simply by using the basic API request script generated by the CDS Download data web form.

If you are encountering difficulties retrieving the data using your basic API script, please contact the C3S User Support Team with a copy of your API script and any error messages that you may have received.

Dataset specific CDS API guidelines