Page History

Page info

infoType	Modified date
prefix	Last modified on
type	Flat

Show If

special	@self

Major modification in progress for this article - please DO NOT UPDATE THIS PAGE or your edits will get overwritten when the new modified article will be published. Please edit the working copy of this page in the C3S Modified CKB articles section.

Info

icon	false
title	Table of Contents

Table of Contents

maxLevel	3

...

This article describes how users can access the family of ERA5 datasets via the Climate Data Store (CDS) infrastructure.

...

2 - Prerequisites

Learn more about the family of ERA5 datasets, and browse through the ERA5 data documentation and ERA5-Land data documentation.
CDS account - If you do not yet have a CDS account, please create one HERE.
Accept the Copernicus licence by creating a test download using the CDS Download web form interface (see below).

...

Go to the C3S climate data store (CDS).
Type 'ERA5' in the search box.
Follow the ERA5 dataset title link of interest (there will be many more hits).

Currently there are eight online ERA5 and two ERA5-Land catalogue entries

Expand

title	Show ERA5 catalogue entries in the CDS

Each of these dataset catalogue entries includes the following tabs:
- Overview . This gives a description of the selected dataset and metadata information (e.g. spatial details, file format, variables, etc).
- Documentation . This provides links to detailed documentation about the dataset.
- Download data . This is a download web form.
Go to the Download data tab to make your selection for ERA5 data retrieval. Using this web interface, you can:
- make selections as per your requirements. For your convenience only valid combinations will show; invalid combinations are greyed out interactively.
- accept the data licence in the Terms of use section (in case you had not yet accepted it). You will only see this section after you have logged in.
  Note
  You will need to do this regardless whether you are accessing data through the web interface or through the CDS API (see below).
Click on the button Submit Form at the bottom right to submit your data request (you must be logged in and have accepted the terms and conditions before submitting your request).
You will now be redirected to the Your requests page.

...

Build a basic CDS API request.

You can use the CDS web interface to help you build your CDS API download script.
In the Download data tab, make some selections, then click the button Show API request at the bottom left and you will be presented with the script.

Copy and paste this to your preferred text editor.

Expand

title	Basic CDS API script example (for ERA5 19791940-present) to download temperature at a given pressure level, 1000 hPa is shown HERE.

Code Block

language	text

#!/usr/bin/env python

import cdsapi

c = cdsapi.Client()

c.retrieve(
    'reanalysis-era5-pressure-levels',
    {
        'product_type': 'reanalysis',
        'variable': 'temperature',
        'pressure_level': '1000',
        'year': '2008',
        'month': '01',
        'day': '01',
        'time': '12:00',
        'format': 'netcdf',                 # Supported format: grib and netcdf. Default: grib
    },
    'download.nc')                          # Output file. Adapt as you wish.

Refine your CDS API script for ERA5 data listed in CDS for optional post-processing.

For a different grid resolution, use the key 'grid'.
Please note that the ERA5 native grid of online CDS is 0.25°x0.25° (atmosphere), 0.5°x0.5° (ocean waves), mean, spread and members: 0.5°x0.5° (atmosphere), 1°x1° (ocean waves). ERA5-Land: 0.1°x0.1°. So this will be returned by default.

Expand

title	Click here for a sample script (for ERA5 19591940-present) that downloads temperature at a given pressure level at 1000 hPa for a geographical subset of the data and specified grid

Code Block

language	text

#!/usr/bin/env python
import cdsapi

c = cdsapi.Client()

c.retrieve(
    'reanalysis-era5-pressure-levels',
    {
        'product_type': 'reanalysis',
        'variable': 'temperature',
        'pressure_level': '1000',
        'year': '2008',
        'month': '01',
        'day': '01',
        'time': '12:00',
        'format': 'netcdf',                 # Supported format: grib and netcdf. Default: grib
        'area'          : [60, -10, 50, 2], # North, West, South, East.          Default: global
        'grid'          : [1.0, 1.0],       # Latitude/longitude grid.           Default: 0.25 x 0.25
    },
    'era5_temperature_sub_area.nc')         # Output file. Adapt as you wish.

...

Note
Please be aware that there is an additional queueing system for downloading data from the ECMWF's MARS archive - expect several hours to several days for submitted requests to complete at this time. You can check the Live status of your request

You can discover the ERA5-complete structure (

...

1940-present) and learn how to build a CDS API request by following these steps:

Open the MARS ERA5 catalogue

browse for discovery, and browse your way to the parameter level to build a request.

Info

More information on the available streams, product types and levels is available in the ERA5 data documentation.
On the parameter level, use the left-mouse button and the shift key to select more than one field in one retrieval.
The MARS catalogue only shows data for the final quality controlled data that is made available 2-3 months in arrear. However, data is also available from preliminary timely updates up to 5 days behind real time, using the same retrieval structure.

Note

To retrieve MARS data efficiently (and get your data quicker!) you should retrieve all the data you need from one tape, then from the next tape, and so on.

As a rule of thumb everything shown on one page at parameter level in the MARS ERA5 catalogue is grouped together on one tape

For analysis fields this is one month of data with respect to one particular level type (e.g. surface).
For forecast fields on model levels this is limited to one single day.

Use the " View MARS request " feature - this will help you build your own CDS API Python script to retrieve the data through the CDS API.

Expand

title	Example: Download ERA5 model level analysis data (temperature) in the native spherical harmonics representation in GRIB format.

Code Block

#!/usr/bin/env python
import cdsapi
c = cdsapi.Client()
c.retrieve('reanalysis-era5-complete', { # Requests follow MARS syntax
                                         # Keywords 'expver' and 'class' can be dropped. They are obsolete
                                         # since their values are imposed by 'reanalysis-era5-complete'
    'date'    : '2013-01-01',            # The hyphens can be omitted
    'levelist': '1/10/100/137',          # 1 is top level, 137 the lowest model level in ERA5. Use '/' to separate values.
    'levtype' : 'ml',
    'param'   : '130',                   # Full information at https://apps.ecmwf.int/codes/grib/param-db/
                                         # The native representation for temperature is spherical harmonics
    'stream'  : 'oper',                  # Denotes ERA5. Ensemble members are selected by 'enda'
    'time'    : '00/to/23/by/6',         # You can drop :00:00 and use MARS short-hand notation, instead of '00/06/12/18'
    'type'    : 'an',
}, 'output')                             # Output file; in this example containing fields in grib format. Adapt as you wish.

Tailor your request to

re-grid to the desired regular lat-lon resolution
convert to NetCDF (works for regular grids only, i.e., so you need to use the 'grid' keyword as well)

select sub areas

Expand

title	Example to download model level ERA5 analysis data (temperature) for a given area at a regular lat/lon grid in NetCDF format.

Code Block

#!/usr/bin/env python
import cdsapi
c = cdsapi.Client()
c.retrieve('reanalysis-era5-complete', { # Requests follow MARS syntax
                                         # Keywords 'expver' and 'class' can be dropped. They are obsolete
                                         # since their values are imposed by 'reanalysis-era5-complete'
    'date'    : '2013-01-01',            # The hyphens can be omitted
    'levelist': '1/10/100/137',          # 1 is top level, 137 the lowest model level in ERA5. Use '/' to separate values.
    'levtype' : 'ml',
    'param'   : '130',                   # Full information at https://apps.ecmwf.int/codes/grib/param-db/
                                         # The native representation for temperature is spherical harmonics
    'stream'  : 'oper',                  # Denotes ERA5. Ensemble members are selected by 'enda'
    'time'    : '00/to/23/by/6',         # You can drop :00:00 and use MARS short-hand notation, instead of '00/06/12/18'
    'type'    : 'an',
    'area'    : '80/-50/-25/0',          # North, West, South, East. Default: global
    'grid'    : '1.0/1.0',               # Latitude/longitude. Default: spherical harmonics or reduced Gaussian grid
    'format'  : 'netcdf',                # Output needs to be regular lat-lon, so only works in combination with 'grid'!
}, 'ERA5-ml-temperature-subarea.nc')     # Output file. Adapt as you wish.

...

Expand

title	Example to download ERA5.1 monthly mean temperature at 50 hPa at a regular lat/lon grid in NetCDF format.

Code Block

#!/usr/bin/env python
import cdsapi
c = cdsapi.Client()
c.retrieve('reanalysis-era5.1-complete', { # Please note the addition '.1' for ERA5.1!
                                           # Keywords 'expver' and 'class' can be dropped. They are obsolete
                                           # since their values are imposed by 'reanalysis-era5.1-complete'
    'date': '2005-01-01',                  # Valid range:  2000-01-01 to 2006-12-31. Always first of the month for monthly means
    'levelist': '50',                      # Pressure level at 50 hPa
    'levtype': 'pl',
    'param': '130.128',                    # Full information at https://apps.ecmwf.int/codes/grib/param-db/
    'stream': 'moda',                      # Monthly means (of Daily means).
    'type': 'an',
    'grid'    : '1.0/1.0',                 # Latitude/longitude grid resolution.
    'format'  : 'netcdf',                  # Output needs to be regular lat-lon, so only works in combination with 'grid'!
}, 'era5.1-temperature-monthly-mean.nc')

For ERA5-complete preliminary back-extension (1950-1978, superseded now, users are advised to access the final release from 1940 instead) follow the same procedure as for era5-complete explained above, however:

edit the script to change:
Code Block
'reanalysis-era5-complete' to 'reanalysis-era5-complete-preliminary-back-extension'
data Data is available for the years 1950-1978 inclusive - so make sure that your request dates are within this time period.
Also, please note that this preliminary release has now been superseded by the final, full release from 1940. Access will be deprecated in due time.

Expand

title	Example to download ERA5 back extension (preliminary 1950-1978) hourly temperature from model level 1 to 5 at a regular lat/lon grid in NetCDF format

Code Block

language	py

import cdsapi
c = cdsapi.Client()
c.retrieve('reanalysis-era5-complete-preliminary-back-extension', { # Please note the name of the dataset
                                           # Keywords 'expver' and 'class' can be dropped. They are obsolete
                                           # since their values are imposed by 'reanalysis-era5-complete-preliminary-back-extension'
    'date': '1970-01-01',                  # Valid range:  1950-01-01 to 1978-12-31.
    'levelist': '1/2/3/4/5',               # Model levels from 1 to 5
    'levtype': 'ml',
    'param': '130.128',                    # Full information at https://apps.ecmwf.int/codes/grib/param-db/
    'stream': 'oper',                      # Hourly data.
    'type': 'an',
    'grid': '1.0/1.0',                     # Latitude/longitude grid resolution.
	'time':'00/to/23', 		               # You can drop :00:00 and use MARS short-hand notation, instead of '00/06/12/18', full information at https://confluence.ecmwf.int/pages/viewpage.action?pageId=118817378
    'format':'netcdf',                     # Output needs to be regular lat-lon, so only works in combination with 'grid'!
}, 'era5.preliminary-back-extension-temperature-monthly-mean.nc')

...

Space shortcuts

Page tree

Versions Compared

Old Version 64

New Version 65

Key

2 - Prerequisites

You can discover the ERA5-complete structure (

1940-present) and learn how to build a CDS API request by following these steps:

For ERA5-complete preliminary back-extension (1950-1978, superseded now, users are advised to access the final release from 1940 instead) follow the same procedure as for era5-complete explained above, however: