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 type	variable	year	month	day	time	format**	grid*	area	pressure_level	Example 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]		Expand source 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]		Expand source 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'	Expand source 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'	Expand source 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]		Expand source 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]		Expand source 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'

[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 type	variable	year	month	day	time	format	grid	area	pressure_level	originating_centre	system	leadtime_hour	leadtime_month	Example script
Seasonal forecast daily data on single levels from 2017 to present: 'seasonal-original-single-levels'		'2m_temperature'	'2019'	'10'	'01	'00:00'	'grib'	[1.0,1.0]	[N,W,S,E]		'ukmo'	'142'	'6'		Expand source 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'			'grib'	[1.0,1.0]	[N,W,S,E]		'ecmwf'	'4'		'1'	Expand source 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'			'grib'	[1.0,1.0]	[N,W,S,E]		'ecmwf'	'5'		'1'	Expand source 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'	'grib'	[1.0,1.0]	[N,W,S,E]	'10'	'ukmo'	'12'	'12'		Expand source 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'			'grib'	[1.0,1.0]	[N,W,S,E]	'200'	'cmcc'	'3'		'2'	Expand source 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'	Expand source 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
	variable	year	month	day	time	format	pressure_level	height_level	soil_level	origin	Example 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'	Expand source 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'			Expand source 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'				Expand source 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'	Expand source 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

class

dataset

date

expver

levtype

origin

param

stream

time

type

target

Example 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

variable

start year

end year

format

experiment

ensemble_member

simulation_version

temporal_resolution

gcm_model

rcm_model

Example 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
	variable	format	experiment	ensemble_member	period	model	Example script
CMIP5 daily data on single levels: 'projections-cmip5-daily-single-levels'	'2m_temperature'	'zip'	'historical'	'r1i1p1'	'19750101-19991231'	'access1_3'	Expand source 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'	Expand source 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'	Expand source 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'	Expand source 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')

Space shortcuts

Page tree

Introduction

ERA5 family datasets

Datasets name

Keywords

Datasets name

Keywords

Seasonal forecasts datasets

Datasets name

Keywords

UERRA datasets

Datasets name

Keywords

Datasets name

Keywords

CORDEX regional climate model dataset

Datasets name

Keywords

CMIP5 climate projections datasets

Datasets name

Keywords

Related articles

Space shortcuts

Page tree

Climate Data Store (CDS) API Keywords

Introduction

ERA5 family datasets

Datasets name

Keywords

Datasets name

Keywords

Seasonal forecasts datasets

Datasets name

Keywords

UERRA datasets

Datasets name

Keywords

Datasets name

Keywords

CORDEX regional climate model dataset

Datasets name

Keywords

CMIP5 climate projections datasets

Datasets name

Keywords

Related articles