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.

The ADS :

• is designed as a distributed system which provides improved access to local and remote datasets via a powerful service-oriented architecture.
• offers seamless web-based and API-based search and retrieve facilities to access air quality data and information.

The data provided by the ADS are free and open data, subject to the user agreeing to the relevant dataset licence(s). For further details about the underlying infrastructure, please see this article from the ECMWF Newsletter 151.

How the ADS works

The ADS provides a Catalogue which lists CAMS data and products, such as observations, reanalyses and air quality forecasts. Users can search through the catalogue, and can filter the entries by means of both a faceted search (Variable domain, Parameter family, Spatial coverage, Product type, Temporal coverage) and a textual search. 

Users can request data from the ADS using a variety of methods:

• the ADS web interface
• the CDS Application Programming Interface (CDS API)

1) The ADS web interface is an interactive system: the user fills a web form to construct their query (please note that only a valid query can be submitted via the web form).

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

The user can then currently choose between two options:

• submit the form and download the result of the query;
• show the query as an API request

In the future, a third option - the ADS Toolbox - will be added.

These are shown in the following figures:

2) The CDS API is a service providing programmatic access in Python to ADS data. 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.

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)

As the ADS is a distributed platform, the datasets are hosted at a number of different locations. Some data are stored on the ADS disks themselves; others are hosted remotely on the data providers' storage systems, e.g. the ECMWF Meteorological Archival and Retrieval System (MARS).

Table 2 shows where the ADS datasets are currently stored.

Please note that the items the user selects to include in a single ADS request can make a significant difference in terms of performance i.e. how long a given request will take to run. Please see the page Efficiency tips for how to build an efficient request.

On the ADS cache disks, requests and relevant results are generally stored for 1.5 to 2 days, depending on the user load on the ADS system. After this period, files can be deleted, starting from the oldest.

Please note that cached data (if present) is used to fulfill an ADS request only if the ADS request is exactly identical to a previous one. This means that data will be extracted from the cache, rather than being re-retrieved from the dataset itself.

Request states

After sending a request, the user can track its state on the 'Your Requests' page of the ADS web interface. There are five different states of a request:

1. Queued. Each request is assigned a unique ID and a priority. The priority is chosen according to different criteria, such as the origin of the request (ADS web interface/API). For example, the ADS web interface usually has higher priority because it is an interactive application and users expect an immediate response to their request.
2. In progress. The request is being fulfilled and the data is being collected from the relevant datasets.
   
3. Failed. The request encountered problems and did not complete.
   
4. Unavailable. The data has expired from cache and therefore cannot be retrieved at the current time. In this case the request should be resubmitted by the user.
   
5. Complete. The resulting data file is ready to download for ADS web interface requests (Completed CDS API requests are not shown, please see note below).
   

User can check the live status of the ADS queues here https://ads.atmosphere.copernicus.eu/live/queue.

Users can also check the overall status of the ADS system at the live page.

Limits

Limits are set on usage of ADS resources to ensure an appropriate level of performance for users.

They are divided in three categories: 1) per-user, 2) global and 3) system, and the current values for these limits are shown in Table 1 (last reviewed on 26 Jun 2020).

Please note that these limits are changed from time to time according to the current workload of the system and number of concurrent tasks.

The ADS will queue requests which would otherwise cause any of these limits to be exceeded.

The 'live' status of the limits values can be checked here https://ads.atmosphere.copernicus.eu/live/limits

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.

Please note, that these limits are also enforced for requests sent via the CDS API.

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.

CDS API examples

CDS API Request for sulphate aerosol optical depth 550nm from CAMS global reanalysis (EAC4) dataset on on 01-01-2004, at 00 UTC.

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