Created by Anabelle Guillory

Reviewed by CUS team members

Approved on  


The Atmosphere Data Store (ADS) will soon become the primary source for access to CAMS datasets and updates, users need to migrate to ADS as soon as possible. The CDS API is a service providing programmatic access to ADS data. Note that access to the CAMS global forecast NRT data on the operational FTP server will remain in place.

This article describes how to switch to using the CDS API for Copernicus Atmosphere Monitoring Service (CAMS) data users. This is the programmatic way of downloading data from the Atmosphere Data Store (ADS).

The ADS also offers an interactive way of downloading the CAMS data through its web interface ("Download Data tab").

Background:

Before the release of Copernicus Atmosphere Monitoring Service (CAMS) Atmosphere Data Store (ADS) in March 2020, CAMS datasets were made available through various means depending on data host (e.g. Global CAMS analysis and forecast data hosted at the ECMWF data server and made available though the ECMWF Web API, the programmatic way of retrieving data; European air quality forecast or analysis data through www.regional.atmosphere.copernicus.eu and download.regional.atmosphere.copernicus.eu; etc...)

As the Atmosphere Data Store (ADS) will soon become the only source for access to CAMS datasets and updates, users need to migrate to ADS as soon as possible. The CDS API is a service providing programmatic access to ADS data.

Prerequisites:

  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:
  3. You are recommended to use the latest release of packages:  CDS API and see the following page for more details: https://ads.atmosphere.copernicus.eu/how-to-api

  4. ADS account - If you do not yet have a ADS account, please create one HERE.

    We have had some problems with mail servers rejecting address confirmation emails from the ADS. We are working on this but if you register on the site and don't receive the registration email, please contact User Support and we will authorise your address manually.


  5. Data licence  - Before you may download any data from the ADS, 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 API script using the ADS web interface:

  1. Go to the CAMS atmosphere data store (ADS)
  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. "Analysis", "Forecast", "Reanalysis")
  4. Follow the dataset title link of interest to the full dataset record
  5. Accept dataset licence and generate basic API script

The full dataset record includes:

Please note that whether you are downloading the data through the web interface or through the CDS API, you must accept the data licence.

At this stage, you can test that CDS API is working for you simply by using the basic API request script generated by the ADS Download data web form. Copy this script to a file on your local system and run it using the version of python you installed the CDS API into.

Please ensure you have your ADS userID and key in your .cdsapirc file if you are requesting data from the ADS.

If you have more than one CDS API key (e.g. one for your account on the CDS, one for your account on the ADS, stored in separate files), you can use the following method to pass credentials in explicitly (see below):

    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")

If you are encountering difficulties retrieving the data using your basic API script, please have a look at the following page: Common Error Messages for CDS API Requests or contact the User Support with a copy of your API script and any error messages that you may have received.

The keyword 'grid' is not support for CDS API requests on the ADS.


This document has been produced in the context of the Copernicus Atmosphere Monitoring Service (CAMS).

The activities leading to these results have been contracted by the European Centre for Medium-Range Weather Forecasts, operator of CAMS on behalf of the European Union (Delegation Agreement signed on 11/11/2014 and Contribution Agreement signed on 22/07/2021). All information in this document is provided "as is" and no guarantee or warranty is given that the information is fit for any particular purpose.

The users thereof use the information at their sole risk and liability. For the avoidance of all doubt , the European Commission and the European Centre for Medium - Range Weather Forecasts have no liability in respect of this document, which is merely representing the author's view.

Related articles

Related articles appear here based on the labels you select. Click to edit the macro and add or change labels.