Page info

infoType	Modified date
prefix	Last modified on
type	Flat

Note
Please be aware that the following page is relevant for the CDS API package of the current CDS system. Although some of the functionalities are common to the new CDS-Beta system we invite you to read the following page for information on some of the changes: Please read: CDS and ADS migrating to new infrastructure: Common Data Store (CDS) Engine

Info

icon	false
title	Table of Contents

Table of Contents

maxLevel	1

Easy Heading Macro

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.

Note

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:

Table of Contents
maxLevel 1
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.

Note

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

...

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

grid*

Datasets name

Keywords

Product type

variable

year

month

day

time

format**

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]

Code Block

language	py
collapse	true

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]

Code Block

language	py
collapse	true

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'

Code Block

language	py
collapse	true

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'

Code Block

language	py
collapse	true

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]

Code Block

language	py
collapse	true

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]

Code Block

language	py
collapse	true

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,1.0]

[N,W,S,E]

'grib' or 'netcdf'

Code Block

collapse	true

#!/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'

Code Block

language	py
collapse	true

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'

Code Block

language	py
collapse	true

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'

Code Block

language	py
collapse	true

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'

Code Block

language	py
collapse	true

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'

Code Block

language	py
collapse	true

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'

Code Block

language	py
collapse	true

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

...

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'

Code Block

language	py
collapse	true

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'

Code Block

language	py
collapse	true

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'

Code Block

language	py
collapse	true

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'

Code Block

language	py
collapse	true

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

Info

icon	false

_{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.}

Space shortcuts

Page tree

Versions Compared

Old Version 2

New Version Current

Key

Introduction

ERA5 family datasets

Datasets name

Keywords

Table of Contents
maxLevel 1
Introduction

ERA5 family datasets

Datasets name

Keywords

Datasets name

Keywords

Seasonal forecasts datasets

Datasets name

Keywords

Datasets name

Keywords

Related articles

Related articles

ERA5 hourly data on single levels from 1979 to present

ERA5 monthly averaged data on single levels from 1979 to present

ERA5 hourly data on pressure levels from 1979 to present:

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

ERA5-Land hourly data from 2001 to present:

ERA5-Land monthly averaged data from 2001 to present:

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

Seasonal forecast anomalies on single levels from 2017 to present:

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

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

Seasonal forecast anomalies on pressure levels from 2017 to present:

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

CMIP5 daily data on single levels:
'19750101-19991231'

CMIP5 monthly data on single levels:

CMIP5 daily data on pressure levels:

CMIP5 monthly data on pressure levels:

Space shortcuts

Page tree

Page History

Versions Compared

Old Version 2

New Version Current

Key

Introduction

ERA5 family datasets

Datasets name

Keywords

Table of ContentsmaxLevel1Introduction

ERA5 family datasets

Datasets name

Keywords

Datasets name

Keywords

Seasonal forecasts datasets

Datasets name

Keywords

Datasets name

Keywords

Related articles

Table of Contents
maxLevel 1
Introduction