How to download ERA5

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

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 and ERA5 monthly means archived at ECMWF's MARS 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

1. Go to the C3S climate data store (CDS).
2. On the top menu bar, click on 'Datasets'.
3. 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.
4. Follow the ERA5 dataset title link of interest 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
     • submit your request online (you will need to login if not already logged in)  
       Tip: Upon submitting the download form, you will be prompted to 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.
5. Go to the Download data tab to make your selection for ERA5 data retrieval.
6. 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 (tested with version 0.1.1).

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

1. 1. Build the basic CDS API request.
      As described in on How to migrate from ECMWF Web API to CDS API, 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.
      
      

      Basic CDS API script example to download temperature at a given pressure level, 1000 hPa is shown HERE.

      #!/usr/bin/env python
      import cdsapi
      
      c = cdsapi.Client()
      c.retrieve('reanalysis-era5-pressure-levels', {
              'variable'      : 'temperature',
              'pressure_level': '1000',
              'product_type'  : 'reanalysis',
              'year'          : '2008',
              'month'         : '01',
              'day'           : '01',
              'time'          : '12:00',
              'format'        : 'netcdf' # Supported format: grib and netcdf. Default: grib
          }, 'test.nc')
      
      

   2. Refining your CDS API script for ERA5 data listed in CDS.
      Currently the interactive CDS forms don't allow users to perform a regional sub-selection or an interpolation of the selected data. However, both actions can be performed using the following CDS API keywords:
      
      1. For a geographical area subset, use key area.

      2. For a different grid resolution, use key grid.
         Please note that the ERA5 native grid in 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).
         
         Below is a sample script for downloading temperature at a given pressure level, 1000 hPa. It also shows how to request for a geographical subset of the data.
         
         

         Show basic CDS API script including geographical subset

         #!/usr/bin/env python
         import cdsapi
         
         c = cdsapi.Client()
         c.retrieve('reanalysis-era5-pressure-levels', {
                 'variable'      : 'temperature',
                 'pressure_level': '1000',
                 'product_type'  : 'reanalysis',
                 'year'          : '2008',
                 'month'         : '01',
                 'day'           : '01',
                 '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). Default: 0.25 x 0.25
                 'time'          : '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 ERA5 datasets do not appear in CDS, but they are accessible through CDS API, for example, ERA5 model level data and ERA5 monthly means archived at ECMWF's MARS archive. This implies, in some situations, accessing data not available on disks but archived in the tape library.

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 will have to use ECMWF MARS keywords in the CDS API request AND follow the MARS efficiency rules to avoid disappointment with your data retrieval! You must also retrieve dataset 'reanalysis-era5-complete'.

We provide some examples of retrieval scripts but of course a wide range of scripts can be built. Under any circumstances, to make sure you are using the correct MARS keywords and values, we ask you to proceed as follows:

1. 1. Explore the ECMWF MARS ERA5 catalogue all the way to the parameters of interest.
   2. 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:
      
      
      Full Transcript (pdf)

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

   4. 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) :

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

      #!/usr/bin/env 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',
          'levelist': '1/10/50/100',
          'date'    : '2013-01-01',
          'time'    : '06/18',
          'area'    : '80/-50/-25/0', # North, West, South, East. Default: global
          'grid'    : '1.0/1.0', # Latitude/longitude grid: east-west (longitude) and north-south resolution (latitude). Default: reduced Gaussian grid
          'format'  : 'netcdf', # Default: grib
      }, 'temp-fc-ml.nc')
      

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

      #!/usr/bin/env python
      import cdsapi
      
      c = cdsapi.Client()
      c.retrieve('reanalysis-era5-complete', {    # do not change this!
          'class'   : 'ea',
          'expver'  : '1',
          'stream'  : 'oper',
          'type'    : 'an',
          'param'   : '130.128',
          'levtype' : 'ml',
          'levelist': '1/10/50/100',
          'date'    : '2013-01-01',
          'time'    : '00/to/23/by/6',
      }, 'temp-an-ml.grib')

      Example 3: Download ERA5 monthly mean of daily means data (surface level 2m temperature) at the default reduced Gaussian grid in GRIB format.

      #!/usr/bin/env python
      import cdsapi
      
      c = cdsapi.Client()
      c.retrieve('reanalysis-era5-complete', {    # do not change this!
          'class'   : 'ea',
          'expver'  : '1',
          'stream'  : 'moda',
          'type'    : 'an',
          'param'   : '167.128',
          'levtype' : 'sfc',
          'date'    : '2018-01-01',
          'decade'  : '2010',
      }, 'monthly-mean-daily-mean-temp-an-sfc.grib')

      Example 4: Download ERA5 synoptic monthly mean data (pressure level temperature and relative humidity) at the default reduced Gaussian grid in GRIB format.

      #!/usr/bin/env python
      import cdsapi
      
      c = cdsapi.Client()
      c.retrieve('reanalysis-era5-complete', {   # do not change this!
          'class'   : 'ea',
          'expver'  : '1',
          'stream'  : 'mnth',
          'type'    : 'an',
          'param'   : '130.128/157.128',
          'levtype' : 'pl',
          'levelist': '850',
          'date'    : '2017-01-01',
          'time'    : '00:00:00/03:00:00/06:00:00/09:00:00/12:00:00/15:00:00/18:00:00/21:00:00',
      
      }, 'monthly-mean-daily-mean-temp-an-sfc.grib')

Related articles

• Page:
  ERA5: How to calculate wind speed and wind direction from u and v components of the wind?
• Page:
  Parameters valid at the specified time
• Page:
  Convective and large-scale precipitation
• Page:
  Model grid box and time step
• Page:
  EQC documentation