Table of Contents

Introduction

The Climate Data Store (CDS) API is the service to allow users to request data from CDS datasets via a python script. These scripts use a number of keywords which vary from dataset to dataset, usually following the sections of the CDS download form.

As the CDS API cannot currently return the valid keyword list on demand, they are documented on this page for some of the most popular CDS datasets.

In the table below, we present the list of keywords (also referred to as CDS vocabulary) that can be used in these CDS API requests, along with example values for each valid keyword. 

Please note that not all keywords can be used for all datasets.

The area selection is only available for the ERA5 family datasets and the Seasonal forecast datasets.

CORDEX, CMIP5 and UERRA datasets cannot be regridded.

Users are recommended to construct CDS API scripts by using the web interface of the relevant dataset to build a valid request and then using the 'Show API request' button to get the corresponding CDS API code.

Color legend

Keyword allowed
  
Keyword not allowed

If a keyword which is not allowed is used, the resulting output file could be corrupted or incomplete or an error could occurred when running the script.

ERA5 family datasets

Datasets name

Keywords


Product typevariableyearmonthdaytimeformat**

grid*


areapressure_levelExample script
ERA5 hourly data on single levels from 1979 to present:
'reanalysis-era5-single-levels'
'reanalysis''total_precipitation''2019''01''01'00:00''netcdf'[1.0,1.0][N,W,S,E]
import cdsapi

c = cdsapi.Client()

c.retrieve(
    'reanalysis-era5-single-levels',
    {
        'product_type': 'reanalysis',
        'variable': 'total_precipitation',
        'year': '2019',
        'month': '01',
        'day': '01',
        'time': '00:00',
        'format': 'netcdf',
		'grid':[1.0, 1.0],
        'area': [
            45, 0, 43,
            12,
        ],
    },
    'download.nc')

ERA5 monthly averaged data on single levels from 1979 to present:

'reanalysis-era5-single-levels-monthly-means'
'monthly_averaged_reanalysis''total_precipitation''2019''01'
'00:00''netcdf'[1.0,1.0][N,W,S,E]
import cdsapi

c = cdsapi.Client()

c.retrieve(
    'reanalysis-era5-single-levels-monthly-means',
    {
        'product_type': 'monthly_averaged_reanalysis',
        'variable': 'total_precipitation',
        'year': '2019',
        'month': '01',
        'time': '00:00',
        'format': 'netcdf',
        'area': [
            45, 0, 43,
            11,
        ],
    },
    'download.nc')

ERA5 hourly data on pressure levels from 1979 to present:

'reanalysis-era5-pressure-levels'
'reanalysis''temperature''2019''01''01'00:00''netcdf'[1.0,1.0][N,W,S,E]'850'
import cdsapi

c = cdsapi.Client()

c.retrieve(
    'reanalysis-era5-pressure-levels',
    {
        'product_type':'reanalysis',
        'variable': 'temperature',
        'pressure_level': [
            '1', '2', '3',
            '5', '7', '10',
            '20', '30', '50',
            '70', '100', '125',
            '150', '175', '200',
            '225', '250', '300',
            '350', '400', '450',
            '500', '550', '600',
            '650', '700', '750',
            '775', '800', '825',
            '850', '875', '900',
            '925', '950', '975',
            '1000',
        ],
        'year': '2019',
        'month': '01',
        'day': '01',
        'time': '00:00',
        'format': 'netcdf',
        'area': [
            45, 0, 43,
            11,
        ],
    },
    'download.nc')

ERA5 monthly averaged data on pressure levels from 1979 to present:

'reanalysis-era5-pressure-levels-monthly-means'
'monthly_averaged_reanalysis''relative humidity''2019''01'
'00:00''netcdf'[1.0,1.0][N,W,S,E]'850'
import cdsapi

c = cdsapi.Client()

c.retrieve(
    'reanalysis-era5-pressure-levels-monthly-means',
    {
        'product_type': 'monthly_averaged_reanalysis',
        'variable': 'relative_humidity',
        'pressure_level': '850',
        'year': '2019',
        'month': '01',
        'time': '00:00',
        'format': 'netcdf',
    },
    'download.nc')

ERA5-Land hourly data from 2001 to present:

'reanalysis-era5-land'

'total_precipitation''2019''01''01'00:00''netcdf'[1.0,1.0][N,W,S,E]
import cdsapi

c = cdsapi.Client()

c.retrieve(
    'reanalysis-era5-land',
    {
        'variable': 'total_precipitation',
        'year': '2019',
        'month': '01',
        'day': '01',
        'time': '00:00',
        'format': 'netcdf',
        'area': [
            45, 0, 43,
            11,
        ],
    },
    'download.nc')

ERA5-Land monthly averaged data from 2001 to present:

'reanalysis-era5-land-monthly-means'
'monthly_averaged_reanalysis''total_precipitation''2019''01'
'00:00''grib'[1.0,1.0][N,W,S,E]
import cdsapi

c = cdsapi.Client()

c.retrieve(
    'reanalysis-era5-land-monthly-means',
    {
        'format': 'grib',
        'product_type': 'monthly_averaged_reanalysis',
        'variable': '2m_temperature',
        'year': '2019',
        'month': '01',
        'time': '00:00',
    },
    'download.grib')

* Latitude/longitude grid. Default: 0.25 x 0.25

** If 'netcdf' selected, the keyword 'grid' must be included.

Datasets name

Keywords


class

date*

levelist*

levtype

param

stream

time

type

grid

area

format**

Example script

reanalysis-era5-complete:

https://apps.ecmwf.int/data-catalogues/era5/?class=ea

'ea'

'2020-01-01'

'1'

'ml'

'155'

'oper'

'00:00'

'an'

If 'fc' the keyword 'step' have to be added to the script.

[1.0,1.0]

[N,W,S,E]

'grib' or 'netcdf'

#!/usr/bin/env python
import cdsapi
c = cdsapi.Client()
c.retrieve('reanalysis-era5-complete', {
    'class': 'ea',
    'date': '2020-01-01',
    'expver': '1',
    'levelist': '1/to/137',
    'levtype': 'ml',
    'param': '155',
    'stream': 'oper',
    'time': '00:00:00',
    'type': 'an',
	'format': 'grib'
}, 'output.grib')

*The syntax '/to/' could be use for intervals.
** If 'netcdf' selected, the keyword 'grid' must be included.

Seasonal forecasts datasets

Datasets name

Keywords


Product typevariableyearmonthdaytimegridareapressure_leveloriginating_centresystemleadtime_hourleadtime_monthExample script

Seasonal forecast daily data on single levels from 2017 to present:

'seasonal-original-single-levels'

'2m_temperature'

'2019''10''01'00:00'[1.0,1.0][N,W,S,E]
'ukmo''142''6'
import cdsapi

c = cdsapi.Client()

c.retrieve(
    'seasonal-original-single-levels',
    {
        'originating_centre': 'ukmo',
        'system': '14',
        'variable': '2m_temperature',
        'year': '2019',
        'month': '10',
        'day': '01',
        'leadtime_hour': '6',
        'format': 'grib',
    },
    'download.grib')

Seasonal forecast anomalies on single levels from 2017 to present:

'seasonal-postprocessed-single-levels'
'ensemble_mean''10m_u_component_of_wind_anomaly''2017''09'

[1.0,1.0][N,W,S,E]
'ecmwf''4'
'1'
import cdsapi

c = cdsapi.Client()

c.retrieve(
    'seasonal-postprocessed-single-levels',
    {
        'format': 'grib',
        'originating_centre': 'ecmwf',
        'system': '4',
        'product_type': 'ensemble_mean',
        'year': '2017',
        'variable': '10m_u_component_of_wind_anomaly',
        'month': '09',
        'leadtime_month': '1',
    },
    'download.grib')

Seasonal forecast monthly statistics on single levels from 2017 to present:

'seasonal-monthly-single-levels'
'monthly_mean''10m_u_component_of_wind''1993''09'

[1.0,1.0][N,W,S,E]
'ecmwf''5'
'1'
import cdsapi

c = cdsapi.Client()

c.retrieve(
    'seasonal-monthly-single-levels',
    {
        'originating_centre': 'ecmwf',
        'system': '5',
        'variable': '10m_u_component_of_wind',
        'product_type': 'monthly_mean',
        'year': '1993',
        'month': '09',
        'leadtime_month': '1',
        'format': 'grib',
    },
    'download.grib')

Seasonal forecast daily data on pressure levels from 2017 to present:

'seasonal-original-pressure-levels'

'v_component_of_wind'

'2018''4''01'00:00'[1.0,1.0][N,W,S,E]'10''ukmo''12''12'
import cdsapi

c = cdsapi.Client()

c.retrieve(
    'seasonal-original-pressure-levels',
    {
        'format': 'grib',
        'originating_centre': 'ukmo',
        'system': '12',
        'variable': 'v_component_of_wind',
        'pressure_level': '10',
        'year': '2018',
        'month': '04',
        'day': '01',
        'leadtime_hour': '12',
    },
    'download.grib')

Seasonal forecast anomalies on pressure levels from 2017 to present:

'seasonal-postprocessed-pressure-levels'
'ensemble_mean''geopotential_anomaly''2018''11'

[1.0,1.0][N,W,S,E]'200''cmcc''3'
'2'
import cdsapi

c = cdsapi.Client()

c.retrieve(
    'seasonal-postprocessed-pressure-levels',
    {
        'format': 'grib',
        'originating_centre': 'cmcc',
        'system': '3',
        'variable': 'geopotential_anomaly',
        'pressure_level': '200',
        'product_type': 'ensemble_mean',
        'year': '2018',
        'month': '11',
        'leadtime_month': '2',
    },
    'download.grib')

Seasonal forecast monthly statistics on pressure levels from 2017 to present:

'seasonal-monthly-pressure-levels'

'monthly_mean'

'geopotential''2017''09'

[1.0,1.0][N,W,S,E]'10'

'meteo_france'

'5'
'2'
import cdsapi

c = cdsapi.Client()

c.retrieve(
    'seasonal-monthly-pressure-levels',
    {
        'format': 'grib',
        'originating_centre': 'meteo_france',
        'system': '5',
        'variable': 'geopotential',
        'pressure_level': '10',
        'product_type': 'monthly_mean',
        'year': '2017',
        'month': '09',
        'leadtime_month': '2',
    },
    'download.grib')

UERRA datasets

Datasets name

Keywords


variableyearmonthdaytimeformatpressure_levelheight_levelsoil_leveloriginExample script

UERRA regional reanalysis for Europe on single levels from 1961 to present:

'reanalysis-uerra-europe-single-levels'
'total_precipitation''2018''12''30''06:00''grib'


'mescan_surfex'
import cdsapi

c = cdsapi.Client()

c.retrieve(
    'reanalysis-uerra-europe-single-levels',
    {
        'origin': 'mescan_surfex',
        'variable': 'total_precipitation',
        'year': '2018',
        'month': '12',
        'day': '30',
        'time': '06:00',
        'format': 'grib',
    },
    'download.grib')

UERRA regional reanalysis for Europe on height levels from 1961 to present:

'reanalysis-uerra-europe-height-levels'
'pressure''1961''01''01''00:00''grib'
'15_m'

import cdsapi

c = cdsapi.Client()

c.retrieve(
    'reanalysis-uerra-europe-height-levels',
    {
        'format': 'grib',
        'variable': 'pressure',
        'height_level': '15_m',
        'year': '1961',
        'month': '01',
        'day': '01',
        'time': '00:00',
    },
    'download.grib')

UERRA regional reanalysis for Europe on pressure levels from 1961 to present:

'reanalysis-uerra-europe-pressure-levels'
'geopotential''1967'

'10'

'07''00:00''grib''10'


import cdsapi

c = cdsapi.Client()

c.retrieve(
    'reanalysis-uerra-europe-pressure-levels',
    {
        'format': 'grib',
        'variable': 'geopotential',
        'pressure_level': '10',
        'year': '1967',
        'month': '10',
        'day': '07',
        'time': '00:00',
    },
    'download.grib')

UERRA regional reanalysis for Europe on soil levels from 1961 to present:

'reanalysis-uerra-europe-soil-levels'
'soil_temperature'1968''08'02''06:00''netcdf'

'2''uerra_harmonie'
import cdsapi

c = cdsapi.Client()

c.retrieve(
    'reanalysis-uerra-europe-soil-levels',
    {
        'format': 'netcdf',
        'origin': 'uerra_harmonie',
        'variable': 'soil_temperature',
        'soil_level': '2',
        'year': '1968',
        'month': '08',
        'day': '02',
        'time': '06:00',
    },
    'download.nc')

Datasets name

Keywords


classdatasetdateexpverlevtypeoriginparamstreamtimetypetargetExample script
Complete UERRA regional reanalysis for Europe from 1961 to present'ur''uerra''2017-11-01/to/2017-11-30''prod''sfc''eswi'

'260242'

'oper''00:00:00''an''output.grib'
#!/usr/bin/env python
from ecmwfapi import ECMWFDataServer
server = ECMWFDataServer()
server.retrieve({
    "class": "ur",
    "dataset": "uerra",
    "date": "2017-11-01/to/2017-11-30",
    "expver": "prod",
    "levtype": "sfc",
    "origin": "eswi",
    "param": "260242",
    "stream": "oper",
    "time": "00:00:00",
    "type": "an",
    "target": "output",
})

260242 corresponds to 2 metre relative humidity. You can check the parameter ID from the Parameter Database.

CORDEX regional climate model dataset

Datasets name

Keywords


variablestart yearend yearformatexperimentensemble_membersimulation_versiontemporal_resolutiongcm_modelrcm_modelExample script

CORDEX regional climate model data on single levels for Europe:

'projections-cordex-single-levels'
'mean_precipitation_flux''2006''2008''zip''evaluation''r1i1p1''v1''daily_mean''era_interim''cclm4_8_17'
import cdsapi

c = cdsapi.Client()

c.retrieve(
    'projections-cordex-single-levels',
    {
        'experiment': 'evaluation',
        'variable': 'mean_precipitation_flux',
        'gcm_model': 'era_interim',
        'rcm_model': 'cclm4_8_17',
        'ensemble_member': 'r1i1p1',
        'format': 'zip',
        'temporal_resolution': 'daily_mean',
        'simulation_version': 'v1',
        'start_year': '2006',
        'end_year': '2008',
    },
    'download.zip')

CMIP5 climate projections datasets

Datasets name

Keywords


variableformatexperimentensemble_memberperiodmodelExample script

CMIP5 daily data on single levels:

'projections-cmip5-daily-single-levels'

'2m_temperature'

'zip''historical'

'r1i1p1'

'19750101-19991231'

'access1_3'
import cdsapi

c = cdsapi.Client()

c.retrieve(
    'projections-cmip5-daily-single-levels',
    {
        'ensemble_member': 'r1i1p1',
        'format': 'zip',
        'experiment': 'historical',
        'variable': '2m_temperature',
        'model': 'access1_3',
        'period': '19750101-19991231',
    },
    'download.zip')

CMIP5 monthly data on single levels:

'projections-cmip5-monthly-single-levels'
'10m_wind_speed''zip''amip''r1i1p1''197901-200812''cnrm_cm5'
import cdsapi

c = cdsapi.Client()

c.retrieve(
    'projections-cmip5-monthly-single-levels',
    {
        'ensemble_member': 'r1i1p1',
        'format': 'zip',
        'experiment': 'amip',
        'variable': '10m_wind_speed',
        'model': 'cnrm_cm5',
        'period': '197901-200812',
    },
    'download.zip')

CMIP5 daily data on pressure levels:

'projections-cmip5-daily-pressure-levels'
'u_component_of_wind''zip''historical''r1i1p1''20050101-20051231''access1_0'
import cdsapi

c = cdsapi.Client()

c.retrieve(
    'projections-cmip5-daily-pressure-levels',
    {
        'ensemble_member': 'r1i1p1',
        'format': 'zip',
        'experiment': 'historical',
        'variable': 'u_component_of_wind',
        'model': 'access1_0',
        'period': '20050101-20051231',
    },
    'download.zip')

CMIP5 monthly data on pressure levels:

'projections-cmip5-monthly-pressure-levels'
'u_component_of_wind''tgz''rcp_2_6''r3i1p1''200601-210012''ipsl_cm5a_lr'
import cdsapi

c = cdsapi.Client()

c.retrieve(
    'projections-cmip5-monthly-pressure-levels',
    {
        'ensemble_member': 'r3i1p1',
        'format': 'tgz',
        'experiment': 'rcp_2_6',
        'variable': 'u_component_of_wind',
        'model': 'ipsl_cm5a_lr',
        'period': '200601-210012',
    },
    'download.tar.gz')

This document has been produced in the context of the Copernicus Climate Change Service (C3S).

The activities leading to these results have been contracted by the European Centre for Medium-Range Weather Forecasts, operator of C3S 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.

Feedback: C3S User Satisfaction Survey - CAMS User Satisfaction Survey

Web: C3S Help and Support - CAMS Help and Support