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:
- 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.
- Install the CDS API:
- on linux or on cygwyn (using pip), please follow the instructions HERE.
- Windows users may follow the instructions HERE instead.
- macOS user, please read instructions HERE
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
- 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/api-how-to
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.
- 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:
- Go to the CAMS atmosphere data store (ADS)
- On the top menu bar, click on 'Datasets'
- On the left-hand side menu, expand 'Product type' and select Product type of interest (e.g. "Analysis", "Forecast", "Reanalysis")
- Follow the dataset title link of interest to the full dataset record
- Accept dataset licence and generate basic 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). Upon submitting the download form, you will be prompted to accept the data licence (if you have not yet accepted it)!
- display the API script which corresponds to your selection, by clicking on the "Show API request" button. We strongly suggest to use this feature to build your CDS API request.
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.
