Page History

...

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:

...

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)

...

Table 2 Summary of the number of fields limits, as well as the major features of all ADS datasets (last reviewed on 16 September 202126 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

...