Page History

...

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

1 - Introduction

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

ERA5 data can be downloaded through the CDS either via the CDS web ERA5 data can be downloaded through the CDS either through the CDS web interface or programmatically using the CDS API service.

Some ERA5 datasets do not appear in CDS, but they are accessible through CDS API, for example, ERA5 model level data archived at Any data in the CDS catalogue can be accessed in these two ways. And since such data is kept online, access is usually fast. Some parts of the ERA5 dataset are not listed in the CDS catalogue. These are only accessible through the CDS API service. An example is ERA5 model level data that resides in the  ECMWF's MARS tape archive. This implies, in some situations, accessing data not available on disks but archived in the tape library (hence longer retrieval times).

1 - Prerequisites

• Read What is ERA5 and the ERA5 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).

2 - Downloading ERA5 data through the CDS web interface

The extraction of such data from tape can lead to significantly longer retrieval times than data that is available online.

2 - Prerequisites

• Read What is ERA5, 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).

3 - Downloading online ERA5 family data through the CDS web interface

1. Go to the C3S climate data store (CDS).
2. Type 
3. Go to the C3S climate data store (CDS).
4. On the top menu bar, click on 'Datasets'.
5. On the left-hand side menu, expand 'Product type' and select Product type of interest (e.g. 'Reanalysis' for ERA5 datasets). Or you can search 'ERA5' in the search box.
6. Follow the ERA5 dataset title link of interest (there will be many more hits).

7. Currently there are four online ERA5 and two ERA5-Land catalogue entries

   Expand
   title Show ERA5 catalogue entries in the CDS
   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 1981 to present ERA5-Land monthly averaged data from 1981 to present

   
   

8. 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.
   to the full dataset record.
   

   The full dataset record includes:

   • Overview tab. This gives a description of the selected dataset and metadata information (e.g. spatial details, file format, variables, etc).
   • Documentation tab. This provides links to detailed documentation about the dataset.
   • Download data tab. This is a Download data web form. Using this web interface, you can:
   • make selections as per your requirements
   • accept the data licence (if you have not yet accepted it)!  Please note that whether you are downloading the data through the web interface or through the CDS API, you must accept the data licence.
   • display the API script which corresponds to your selection, by clicking on the Show API request button.
   submit your request online (you will need to login if not already logged in)  
9. Go to the Download data tab to make your selection for ERA5 data retrieval.
10. Click on button 'Submit Form' to submit  your data request. Provided you have accepted the Copernicus Licence, 'your requests' page will be displayed showing the status of your submitted request.

3 - Download ERA5 data through the CDS API

Step A: Install CDS API on your machine

1. Python and pip: You are expected to have at least some basic understanding of Python and in particular know how to install packages on your local machine using pip.
2. Install the CDS API:
   • on linux or on cygwin, please follow the instructions HERE.
   • Windows users may follow the instructions HERE instead.
3. You are recommended to use the latest release of package CDS API.

Step B: Download ERA5 data listed in CDS through CDS API

1. 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).

     
     

2. 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).

3. You will now be redirected to the Your requests page.

Once your request has been processed you can download the data by clicking the green Download button. You can check the Live status of your request .

4 - Download ERA5 family data through the CDS API

First: Install CDS API on your machine

1. This is Python based.
   • This may require some basic knowledge of Python. However, in most cases common-sense adaptions of example requests obtained from the web interface should be sufficient.
2. Install the CDS API:
   • this may require some basic knowledge of pip, in particular know how to install packages on your local machine using pip.
   • On linux or on cygwin, please follow the instructions HERE.
   • Windows users may follow the instructions HERE instead.
   • Mac users may follow the instructions HERE.
3. You are recommended to use the latest release of package CDS API.
4. Run CDS API requests, either interactively or in batch mode.

Option A: Download ERA5 family data stored on CDS disks - FAST ACCESS

1. 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 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'

Build the basic CDS API request.
As mentioned above, you can use the CDS web interface to help you build your CDS API download script. In the download form, make some selections, then click the button Show API request and you will be presented with the script.
Expand

title	Basic CDS API script example 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', { 'variable' : 'temperature', 'pressure_level': '1000', 'product_type'

2. • : 'reanalysis', '

year

3. • variable': 'temperature',

4. • 'pressure_level': '

2008

5. • 1000', '

month

6. • year': '2008', 'month': '01', 'day'

7. • : '01', 'time'

8. • : '12:00', 'format': 'netcdf',

: 'netcdf'

9. • # Supported format: grib and netcdf. Default: grib }, '

test

10. • download.nc') # Output file. Adapt as you wish. import cdsapi

Refining

11. • 
      

12. Refine your CDS API script for ERA5 data listed in CDS
.
For a geographical area subset, use key area
13. for optional post-processing.
    
    • For a different grid resolution, use the key 'grid'.
    • Please note that the ERA5 native grid
in
14. • of online CDS is 0.25°x0.25° (atmosphere), 0.5°x0.5° (ocean waves),
Mean
15. • mean, spread and members: 0.5°x0.5° (atmosphere), 1°x1° (ocean waves).

Below is
16. • ERA5-Land: 0.1°x0.1°. So this will be returned by default.

    • 
      

      Expand
      title Click here for a sample script

for downloading

17. • that downloads temperature at a given pressure level

,

18. • at 1000 hPa

. It also shows how to request for a Expand

title	Show basic CDS API script including geographical subset

19. • for a geographical subset of the data

.


20. • and specified grid

21. • Code Block language text #!/usr/bin/env python import cdsapi c = cdsapi.Client() c.retrieve( 'reanalysis-era5-pressure-levels', {

'variable'

22. • 'product_type': 'reanalysis', 'variable': 'temperature', 'pressure_level': '1000', '

product_type

23. • year'

24. • : '

reanalysis

25. • 2008', '

year

26. • month': '01',

27. • 'day': '

2008

28. • 01', '

month

29. • time': '12:00', 'format': '

01

30. • netcdf',

'day'

32. • # Supported format: grib and netcdf. Default:

'01',

33. • grib 'area' : [60, -10, 50, 2], # North, West, South, East. Default: global 'grid' : [1.0, 1.0],

#
Latitude/longitude grid: east-west (longitude) and north-south resolution (latitude).

35. • # Latitude/longitude grid. Default: 0.25 x 0.25 }, '

time'

36. • era5_temperature_sub_area.nc') #

: '12:00', 'format' : 'netcdf' # Supported format: grib and netcdf. Default: grib }, 'test.nc')

Step C: Download ERA5 data NOT listed in CDS through CDS API

Some validated ERA5 datasets  (i.e. updated with a 2-3 months delay) do not appear in CDS, but they are accessible through CDS API, for example, ERA5 model level data archived at ECMWF's MARS archive. This implies, in some situations, accessing data not available on disks but archived in the tape library.

...

1. • Output file. Adapt as you wish.

     
     

Option B: Download ERA5 family data that is NOT listed in the CDS online catalogue - SLOW ACCESS

Although some flavours of the ERA5 family data is not online in the CDS (i.e. not available through the interactive web download form), it is accessible through CDS API. This embraces ERA5-complete and ERA5.1-complete, which provide data in the 'raw' format as they were produced:

• native grid rather than regridded into regular lat-lon,
• model and potential temperature/vorticity levels, in addition to  pressure levels and  surface fields,
• full two-dimensional ocean-wave spectra in addition to integrated wave parameters,
• explicit distinction between analysis, short-forecast and other, more technical, products.

The ERA5-Land dataset at the native 9km octahedral grid is an exception and is currently not available via the CDS API protocol. However, all information is available online at the slightly reduced 0.1°x0.1° regular lat-lon grid (access via Option A, above).

Due to the vast volume of these datasets (currently about 6 petabyte) these are not stored on spinning disk, but reside in the ECMWF's MARS tape archive, instead. Access to this data is in general much slower.

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 and learn how to build a CDS API request by following these steps:

1. Open the MARS ERA5 catalogue

2. 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.

   
   

   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.

   
   

3. 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

4. Explore the ECMWF MARS ERA5 catalogue all the way to the parameters of interest.
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. A demonstration on how to use the ERA5 Catalogue is available as part of the video tutorial below:


Multimedia
name Final-ERA5.mp4 width 20% height 20%

Full Transcript (pdf)

5. 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. In most cases, this means retrieving all the data you need for one month, then for the next month, and so on. To find out what data is available on each tape, browse the ERA5 Catalogue and make your way until the bottom of the tree archive (where parameters are listed). Once you will have reached that level of the archive, what you see is what you can find on one single tape. See Retrieval efficiency page for more details.

Transpose the MARS keywords into the CDS API script as shown on the examples below (please note that you need to give  'reanalysis-era5-complete ' as the dataset name in your script) :

ExpandtitleExample 1: Download model level forecast ERA5 data (temperature) for a given area at a regular lat/lon grid in NetCDF

6. 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.

   
   

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

   3. 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.

      
      

For ERA5.1-complete follow the same procedure as for era5-complete explained above, however:

1. edit the script to change:

   
   

   Code Block
   'reanalysis-era5-complete' to 'reanalysis-era5.1-complete

   
   

2. data is only available for the years 2000-2006 inclusive - so make sure that your request dates are within this time period.

   
   

   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

python import cdsapi c = cdsapi.Client() c.retrieve('reanalysis-era5-complete', { # do not change this! 'class' : 'ea', 'expver' : '1', 'stream' : 'oper', 'type' : 'fc', 'step' : '3/to/12/by/3', 'param' : '130.128', 'levtype' : 'ml',

3. 'levelist': '

1/10/

4. 50

/100

5. ',

'date'
: '2013-01-01', 'time'
:
'06/18',
'area'
:
'80/-50/-25/0',

13. #

North,

14. Pressure

West,

15. level

South,

16. at

East. Default: global

17. 50 hPa '

grid'

18. levtype': 'pl', 'param': '

1.0/1.0

19. 130.128',

#
Latitude/longitude grid: east-west
(longitude)
and
north-south
resolution
(latitude).
Default:
reduced
Gaussian
grid
'format'
:
'netcdf',
#
Default: grib }, 'temp-fc-ml.nc') Expand

title	Example 2: Download ERA5 model level analysis data (temperature) at the default reduced Gaussian grid in GRIB format.

Code Block#!/usr/bin/env python import cdsapi c = cdsapi.Client() c.retrieve('reanalysis-era5-complete', { # do not change this! 'class' : 'ea',

35. # Full information at https://apps.ecmwf.int/codes/grib/param-db/ 'stream': 'moda', # Monthly means (of Daily means). '

expver

36. type'

37. : '

1

38. an', '

stream

39. grid' : '

oper

40. 1.0/1.0',

'type'
:
'an',
'param'

45. #

: '130.128',

46. Latitude/longitude grid resolution. '

levtype

47. format' : '

ml

48. netcdf',

'levelist':
'1/10/50/100',
'date'
:
'2013-01-01',
'time'

55. # Output

:

56. needs

'00/to/23/by/6', }, 'temp-an-ml.grib') Hide contentExample 3: Download ERA5 monthly mean of daily means data (surface level 2m temperature) at the default reduced Gaussian grid in GRIB format.Example 4: Download ERA5 synoptic monthly mean data (pressure level temperature and relative humidity) at the default reduced Gaussian grid in GRIB format.

57. to be regular lat-lon, so only works in combination with 'grid'! }, 'era5.1-temperature-monthly-mean.nc')

    
    

Related articles

...