Short guide how to download ECMWF ERA INTERIM data

Downloading ERA INTERIM Data

The European Centre for Medium-Range Weather Forecasts (ECMWF) provides some nice data sets to the public. One data set is the ERA INTERIM reanalysis data set. In combination with the ECMWF python API it is quite easy to download these data. This post gives a short introduction and an example script how specify a specific subset and download the data.

ERA-Interim is a global reanalysis data set produced by the European Centre for Medium-Range Weather Forecasts (ECMWF) with a horizontal resolution of approximately 80km x 80km (T255). In degrees (on a regular longitude-latitude grid) this is round about 360 / 255 / 2 = .7058 degrees, wherefore my demo request uses a 0.75/0.75 degree grid. Retrievals with a higher spatial resolution do not make sense, especially as the true resolution (the resolution of the information content) is 5-10 times rougher than the actual resolution (according to ECMWF).

Ho to get the data via ECMWF API using Python:

First of all you need to register yourself on the ECMWF website. An active user account is required, even for the public data sets. After registraction, activation, and login, you can create yourself the required ECMWF API key. There is a small tutorial on their website:

After you’ve created your personal API key you’ll have you have to create an access token file in your home folder (~/.ecmwfapirc) which looks similar to this:

    "url"   : "",
    "key"   : "abcd12348b81311adcdbf123c2f7e",
    "email" : ""

Please note: before you are able to use the API key you have to accept the terms and conditions of the ECMWF.

If you forget to do this the python package will give you a gentle hint.

Installing the python package to retrieve data

To be able to access the data, the python package has to be installed. Simply download the .tgz and install the python package (e.g., sudo pip install ecmwf-api-client-python.tgz). Download are avialable on:

Once the package is installed and the access file has been created, you can retrieve public data sets from ECMWF via python. Let’s set up a small demo file to download ERA-Interim data.

Basically all you need is a python dict containing the retrieval settings which specify what you want to download (which time period, parameter sets, model, …). As this is a tutorial for the publicly available ERA-Interim data set some of the arguments are fixed:

  • "dataset":"interim": downloading interim data
  • "class":"ei": era interim (see mars classes
  • "expver":"1": experiment version 1
  • "stream":"oper": operational data stream
  • "type":"an": analysis (there are also short-term forecasts in the INTERM data set for some quantities

All additional arguments define what we to fetch from the archive.

  • "levtype":"...": level type (pressure level or surface)
  • "levelist":"...": list of levels (only if "levtype":"pl")
  • "date":"...": date/time period
  • "time":"...": time of the day/initialization
  • "pararm":"...": specification of the parameters
  • "target":"...": output file (grib1)
  • "area":"...": areal subset (if required). Format: North/West/South/East in degrees
  • "grid":"...": output grid/resolution
args = {
         "dataset"  : "interim",
         "class"    : "ei",
         "expver"   : "1",
         "stream"   : "oper",
         "type"     : "an",
         "date"     : "2000-01-01",
         "time"     : "0000/0600/1200/1800",
         "area"     : "90/0/0/360",
         "grid"     : "0.75/0.75",
         "levtype"  : "pl",
         "levelist" : "500/700/925",
         "param"    : "129.128",
         "target"   : "demo.grib",

In this case we are downloading analysis data for one specific day ("date":"2000-01-01"), all four analysis time steps ("time":"0000/0600/1200/1800" HHmm in UTC) for the northern hemisphere ("area":"90/0/0/360") on a regular longitude/latitude grid with a grid spacing of 0.75 degrees ("grid":"0.75/0.75").

All we have to do in advance is to specify the parameters we would like to download. In this case parameter "129.128" on pressure levels ("levtype":"pl") for the 500, 700, and 925 hectopascal surface. The parameter database contains the description of the parameters (129.128: 128 is the centre (ECMWF), 129 the parameter ID, in this case geopotential height).

The output should be written into demo.grib in GRIB1 format. Once your argument list is specified we only have to call the ECMWF data API.

# Python: import the ECMWFDataServer form the ecmwfapi package
from ecmwfapi import ECMWFDataServer

# Initialize new instance
server = ECMWFDataServer()

# Retrieve data with our argument dict.
server.retrieve( args )

Full example script

I’ve written a small python example script which can be downloaded here. Have fun!