Skip to end of metadata
Go to start of metadata

This article describes how to migrate from ECMWF Web API to CDS API for Copernicus Climate Change Service (C3S) ERA5 data users.

Before proceeding with the steps below, users must be CDS registered and have gone through the steps described on How to migrate from ECMWF Web API to CDS API.


  1. Download ERA5 data listed in CDS through CDS API


    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 'area' key
      2. For a different grid resolution, use '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')
  1. Download ERA5 data NOT listed in CDS through CDS

    At the time this knowledge is written, all pressure and single level data are stored in CDS. Other ERA5 data do not appear in CDS, but they are accessible through CDS API. For example, ERA5 model level data and ERA5 monthly means are archived at ECMWF's MARS archive. This implies, in some situations, accessing data not available online (on disk) but archived in the tape library.

    (warning)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! 

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

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