Instructions

Register at Copernicus Climate Data Service

  • You have to register at Copernicus Climate Data Service: copernicus. After activating your account use your new account to log in. In you profile page you can find your user ID and your API key.
  • Copy your user ID and API key.

Create a key ascii file

Linux

In Linux create a new file called .cdsapirc in the home directory of your user and add the following two lines:

url: https://cds.climate.copernicus.eu/api/v2

key: UID:KEY

Replace UID with your user ID and KEY with your API key

Windows

In Windows create a new file called .cdsapirc (e.g. with Notepad) where in your windows environment, %USERPROFILE% is usually located at C:UsersUsername folder). And add the following two lines

url: https://cds.climate.copernicus.eu/api/v2

key: UID:KEY

Replace UID with your user ID and KEY with your API key

MacOS

In MacOS create a new file called .cdsapirc in the home directory of your user and add the following two lines:

url: https://cds.climate.copernicus.eu/api/v2

key: UID:KEY

Replace UID with your user ID and KEY with your API key

Info on available variables

Show information on available variables and levels.

usage: era5cli info [-h] name

Positional Arguments

name

Enter list name to print info list:

levels for all available pressure levels

2Dvars for all available single level or 2D variables

3Dvars for all available 3D variables

land for all available variables in ERA5-land

Enter variable name (e.g. total_precipitation) or pressure level (e.g. 825) to show if the variable or level is available, and in which list.

Tip: search in variables

To quickly search the list of variables for a specific word, you can use the built-in grep command. For example:

era5cli info "2Dvars" | grep temperature

should list all single level variables that contain the word ‘temperature’, so they can be easily identified for an era5cli request.

Running era5cli from the command line

era5cli can be used to fetch both hourly data and monthly averaged data.

Fetching hourly data

Fetch hourly data through an cdsapi call via command line. More information on the available data and options can be found on:

Execute the data fetch process for hourly data.

usage: era5cli hourly [-h] --variables VARIABLES [VARIABLES ...] --startyear
                      STARTYEAR [--endyear ENDYEAR]
                      [--levels LEVELS [LEVELS ...]]
                      [--outputprefix OUTPUTPREFIX] [--format {netcdf,grib}]
                      [--merge] [--threads {1,2,3,4,5,6}] [--ensemble]
                      [--dryrun] [--prelimbe] [--land]
                      [--area LAT_MAX LON_MIN LAT_MIN LON_MAX]
                      [--months MONTHS [MONTHS ...]] [--days DAYS [DAYS ...]]
                      [--hours HOURS [HOURS ...]] [--statistics]

Named Arguments

--variables The variables to download data for. This can be a single variable, or multiple. See the Copernicus Climate Data Store website or run era5cli info -h for available variables.
--startyear Single year or first year of range for which data should be downloaded. Every year will be downloaded in a separate file by default. Set –split false to change this.
--endyear Last year of range for which data should be downloaded. If only a single year is needed, only –startyear needs to be specified. Every year will be downloaded in a separate file by default. Set –split false to change this.
--levels

Pressure level(s) to download 3D variables for. Default is all available levels. See the Copernicus Climate Data Store website or run era5cli info -h for available pressure levels. For geopotential, –levels surface can be used to request data from the single level dataset (previously called orography).

Default: [1, 2, 3, 5, 7, 10, 20, 30, 50, 70, 100, 125, 150, 175, 200, 225, 250, 300, 350, 400, 450, 500, 550, 600, 650, 700, 750, 775, 800, 825, 850, 875, 900, 925, 950, 975, 1000]

--outputprefix

Prefix to be used for the output filename. Default prefix is era5.

Default: “era5”

--format

Possible choices: netcdf, grib

Output file type. Defaults to netcdf.

Default: “netcdf”

--merge

Merge yearly output files. Default is split output files into separate files for every year.

Default: False

--threads

Possible choices: 1, 2, 3, 4, 5, 6

Number of parallel threads to use when downloading. Defaults to a single process.

--ensemble

Whether to download high resolution realisation (HRES) or a reduced resolution ten member ensemble (EDA). Providing the –ensemble argument downloads the reduced resolution ensemble. –ensemble is incompatible with –land.

Default: False

--dryrun

Whether to print the cdsapi request to the screen, or make the request to start downloading the data. Providing the –dryrun argument will print the request to stdout. By default, the data will be downloaded.

Default: False

--prelimbe

Whether to download the preliminary back extension (1950-1978). Note that when –prelimbe is used, –startyear and –endyear should be set between 1950 and 1978. –prelimbe is incompatible with –land.

Default: False

--land

Whether to download data from the ERA5-Land dataset. Note that the ERA5-Land dataset starts in 1981. –land is incompatible with the use of –prelimbe and –ensemble.

Default: False

--area Coordinates in case extraction of a subregion is requested. Specified as LAT_MAX LON_MIN LAT_MIN LON_MAX (counterclockwise coordinates, starting at the top) with longitude in the range -180, +180 and latitude in the range -90, +90. For example: –area 90 -180 -90 180. Requests are rounded down to two decimals. By default, the entire available area will be returned.
--months

Month(s) to download data for. Defaults to all months. For every year, only these months will be downloaded.

Default: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]

--days

Day(s) to download data for. Defaults to all days. For every year, only these days will be downloaded.

Default: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31]

--hours

Time of day in hours to download data for. Defaults to all hours. For every year, only these hours will be downloaded.

Default: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23]

--statistics

When downloading hourly ensemble data, provide the –statistics argument to download statistics (ensemble mean and ensemble spread).

Default: False

Fetching monthly data

Fetch monthly data through an cdsapi call via command line. More information on the available data and options can be found on:

For the monthly data, some of the variables are not available. Exceptions on the single level data can be found in table 8 of ERA5 parameter listings

Execute the data fetch process for monthly data.

usage: era5cli monthly [-h] --variables VARIABLES [VARIABLES ...] --startyear
                       STARTYEAR [--endyear ENDYEAR]
                       [--levels LEVELS [LEVELS ...]]
                       [--outputprefix OUTPUTPREFIX] [--format {netcdf,grib}]
                       [--merge] [--threads {1,2,3,4,5,6}] [--ensemble]
                       [--dryrun] [--prelimbe] [--land]
                       [--area LAT_MAX LON_MIN LAT_MIN LON_MAX]
                       [--months MONTHS [MONTHS ...]]
                       [--synoptic [SYNOPTIC [SYNOPTIC ...]]]

Named Arguments

--variables The variables to download data for. This can be a single variable, or multiple. See the Copernicus Climate Data Store website or run era5cli info -h for available variables.
--startyear Single year or first year of range for which data should be downloaded. Every year will be downloaded in a separate file by default. Set –split false to change this.
--endyear Last year of range for which data should be downloaded. If only a single year is needed, only –startyear needs to be specified. Every year will be downloaded in a separate file by default. Set –split false to change this.
--levels

Pressure level(s) to download 3D variables for. Default is all available levels. See the Copernicus Climate Data Store website or run era5cli info -h for available pressure levels. For geopotential, –levels surface can be used to request data from the single level dataset (previously called orography).

Default: [1, 2, 3, 5, 7, 10, 20, 30, 50, 70, 100, 125, 150, 175, 200, 225, 250, 300, 350, 400, 450, 500, 550, 600, 650, 700, 750, 775, 800, 825, 850, 875, 900, 925, 950, 975, 1000]

--outputprefix

Prefix to be used for the output filename. Default prefix is era5.

Default: “era5”

--format

Possible choices: netcdf, grib

Output file type. Defaults to netcdf.

Default: “netcdf”

--merge

Merge yearly output files. Default is split output files into separate files for every year.

Default: False

--threads

Possible choices: 1, 2, 3, 4, 5, 6

Number of parallel threads to use when downloading. Defaults to a single process.

--ensemble

Whether to download high resolution realisation (HRES) or a reduced resolution ten member ensemble (EDA). Providing the –ensemble argument downloads the reduced resolution ensemble. –ensemble is incompatible with –land.

Default: False

--dryrun

Whether to print the cdsapi request to the screen, or make the request to start downloading the data. Providing the –dryrun argument will print the request to stdout. By default, the data will be downloaded.

Default: False

--prelimbe

Whether to download the preliminary back extension (1950-1978). Note that when –prelimbe is used, –startyear and –endyear should be set between 1950 and 1978. –prelimbe is incompatible with –land.

Default: False

--land

Whether to download data from the ERA5-Land dataset. Note that the ERA5-Land dataset starts in 1981. –land is incompatible with the use of –prelimbe and –ensemble.

Default: False

--area Coordinates in case extraction of a subregion is requested. Specified as LAT_MAX LON_MIN LAT_MIN LON_MAX (counterclockwise coordinates, starting at the top) with longitude in the range -180, +180 and latitude in the range -90, +90. For example: –area 90 -180 -90 180. Requests are rounded down to two decimals. By default, the entire available area will be returned.
--months

Month(s) to download data for. Defaults to all months. For every year, only these months will be downloaded.

Default: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]

--synoptic

Time of day in hours to get the synoptic means (monthly averaged by hour of day) for. For example –synoptic 0 4 5 6 23. Give empty option –synoptic to download all hours (0-23). The option defaults to None in which case the monthly average of daily means is chosen.

Default: False

Removing or canceling requests

ERA-5 download requests will be saved in the Your requests section in your profile on the Copernicus Climate Data Store. Here you can re-download the requested data, cancel active requests, or remove old requests.

Note that it is currently not possible to cancel active requests from the command line: Killing the process will not download the data to your local machine but still add it to your Copernicus account.