Page History

Introduction

The Atmosphere Data Store (ADS) is the cornerstone infrastructure which supports the implementation of the Copernicus Atmosphere Monitoring Service (CAMS). It is built on the same infrastructure as the Climate Data Store (CDS). It enables the provision of reliable data and expertise related to air quality, solar energy, and the role atmospheric gases and particles play in climate change.

...

Note
Please make sure that you select all the mandatory fields before submit a request. Image Modified

The user can then currently choose between two options:

...

These are shown in the following figures:

2) The CDS API is a service providing programmatic access in Python to ADS data. CDS API example queries can be conveniently constructed by using the ADS web interface and clicking on the "Show API request" button. For a description and some useful examples, please see How to use the CDS API. Users need to have a CDS account to use it with their related CDS API credentials. For a full description and some useful examples, please see How to use the CDS API. 

If users have more than one ADS API key (e.g. you also have a Climate Data Store (CDS) account), you have to pass credentials in explicitly and the following method can be used:

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

We strongly suggest to construct CDS API requests by using the web interface of the relevant dataset and using the 'Show API request' button to get the code.

Image Added

For non-Python users, please note that the CDS API is REST-based so it can be wrapped by any programming language. Please see this example with the R package: Download CDS ERA5 data using R.

Users can also set the PROXY within the CDS API script:

import requests
import cdsapi


session = requests.Session()

session.proxies = {
   'http': 'http://10.10.10.10:8000',
   'https': 'http://10.10.10.10:8000',
}

client = cdsapi.Client(session=session)

...

Also, ADS data requests have limits in terms of number of fields and volume size, which are different for each dataset (see the "Datasets" Table 2 below). These values are dependent on each dataset's structure and where the dataset is actually stored. Again, these restrictions are introduced to help the system maintain good performance and minimise the queuing time for all users.

For example, when a user ADS web request exceeds the number of fields limit, an information message appears at the bottom of the web interface page (Figure 3). Please note, that these limits are also enforced for requests sent via the CDS API.

Image Removed

Figure 3 Information message when a user ADS web request exceeds the number of fields limit.

Datasets

...

Table 2 Summary of the number of fields limits, as well as the major features of all ADS datasets (last reviewed on

...

26 April 2023)

Efficiency tips

1. Where the data are actually stored can make a significant difference in the speed at which a request is processed. ADS data hosted in 'MARS internal' is stored on ADS disks, and so is faster to retrieve. The 'MARS external' datasets are stored in the ECMWF MARS (tape) archive, and in this case it is important to request as much data as possible from the same tape file in your ADS request.
   
2. It is better to submit small requests rather than very large requests. This will ensure your requests are not given a lower priority in the ADS request queue.
3. When using the CDS API, it is strongly recommended that users take as a starting point the example API request script shown at the bottom of the ADS web  'Download data' page for the dataset of interest, and use this as the basis for your request.

...

import cdsapi

c = cdsapi.Client()

c.retrieve(
    'cams-global-reanalysis-eac4',
    {
        'variable': 'sulphate_aerosol_optical_depth_550nm',
        'date': '2004-01-18/2004-01-18',
        'time': '00:00',
        'format': 'netcdf',
    },
    'download.nc')

Related articles

...