An Overview of the Download Functionality

The download functionality of ERA5Reanalysis.jl is built upon a Julia version of the CDSAPI (see here and here). In ERA5Reanalysis.jl, downloading a dataset can be as easy as

download(
    <ERA5Dataset>,
    <ERA5Variable>,
    <ERA5Region>,
    kwargs...
)

See below for the different examples and methods. Note that downloading a PressureVariable is a bit more complicated and involved than downloading a SingleVariable because we need to also specify the range of pressures to download the data from the CDS when a PressureVariable is chosen.

Setting up the CDSAPI Key

In order for your downloads to work with ERA5Reanalysis, you first need to set up your CDSAPI key. To do this, you must first register with the Climate Data Store in order to obtain your key here.

Then, you can either follow the instructions above in the API-how-to, or you can simply use the function addCDSAPIkey() to do it for you if you don't want to fiddle around with hidden files and the like.

So, example

julia> using ERA5Reanalysis
julia> ckeys = ERA5Reanalysis.cdskey()[ Info: 2025-11-29T00:49:38.989 - CDSAPI - Loading CDSAPI credentials from /home/runner/.cdsapirc ...
Dict{Any, Any} with 2 entries:
  "key" => "199699:c52da207-6f7d-4ae8-bd33-085246faee6e"
  "url" => "https://cds.climate.copernicus.eu/api"
julia> addCDSAPIkey("<your-key-here>")[ Info: 2025-11-29T00:49:39.468 - CDSAPI - Existing .cdsapirc file detected at /home/runner/.cdsapirc, since overwrite options is not selected, leaving file be ...  ...

See the API below for more details.

Examples

The following is the most basic download example

using ERA5Reanalysis
e5ds = ERA5Hourly(start=Date(2015),stop=Date(2015))
evar = SingleVariable("t2m")
egeo = ERA5Region("AR6_SEA")
download(e5ds,evar,egeo)

The following downloads pressure-level data between 500 hPa and 600 hPa (note, we must specify that the keyword argument pall is true.)

using ERA5Reanalysis
e5ds = ERA5Hourly(start=Date(2015),stop=Date(2015))
evar = PressureVariable("cc")
egeo = ERA5Region("AR6_SEA")
download(e5ds,evar,egeo,pall=true,ptop=500,pbot=600)

TL;DR

The backend download functionality of ERA5Reanalysis.jl are based upon the build of CDSAPI.jl, but with the following extensions:

Eliminates the need to know the CDSAPI syntax for the frontend - all you need is to specify the Dataset, Variable and Region of interest
Extracts and places the downloaded data in a patterned, organized and systematic manner for easy retrieval
More detailed and organized logging information during the downloading process similar to the python version of CDSAPI
Allowing for repeated (up to 20) attempts at downloading a specific set of data

However, the download functionality of ERA5Reanalysis.jl is also limited in several ways:

It currently only is able to download the reanalysis data, not ensemble members
It currently is unable to retrieve any dataset outside the ERA5 Reanalysis datasets, including ERA5-Land data
It is not possible to specify multiple Pressure-Level variables for download in the same manner as Single-Level variables

API

ERA5Reanalysis.addCDSAPIkey — Function

addCDSAPIkey(
    key :: AbstractString;
    url :: AbstractString = "https://cds.climate.copernicus.eu/api/v2",
    filename  :: AbstractString = ".cdsapirc",
    overwrite :: Bool = false
) -> nothing

Adds the user's CDSAPI key to a file in the homedir() (by default specified as .cdsapirc)

Arguments

key : The user's CDSAPI key

Keyword Arguments

url : The user's CDSAPI key
filename : The name of the file the url and key are saved to in the homedir()
overwrite : If true and if filename already exists, then overwrite

source

Base.download — Method

download(
    e5ds :: Union{ERA5Hourly,ERA5Monthly},
    evar :: SingleVariable,
    ereg :: ERA5Region;
    ispy :: Bool = false,
    overwrite :: Bool = false
) -> nothing

Downloads ERA5 data from the CDS datastore for a specified Single-Level variable and geographic region. You can specify to download via python scripts generated by selecting ispy to true, or to instead use Julia directly.

You must have installed the CDSAPI on your machine and have accepted the terms and conditions on the CDS website in order for this to work.

Arguments

e5ds : The ERA5Dataset specified (Hourly or Monthly)
- e5ds.start defines the start date
- e5ds.stop defines the end date
- e5ds.path defines the path to which all reanalysis data is saved
evar : Specifies the Single-Level variable to be downloaded
ereg : Specifies the GeoRegion and the resolution of the data to be downloaded
ipsy : Specifies whether to generate a python script that can be used to download the data instead of Julia
overwrite : false by default. If set to true, existing data will be overwritten.

source

Missing docstring.

Missing docstring for `ERA5Reanalysis.download( e5ds :: Union{ERA5Hourly,ERA5Monthly}, evar :: Vector{SingleVariable}, ereg :: ERA5Region; overwrite :: Bool = false

Base.download — Method

download(
    e5ds :: Union{ERA5Hourly,ERA5Monthly},
    evar :: PressureVariable,
    ereg :: ERA5Region;
    ispy :: Bool = false,
    pall :: Bool = false,
    ptop :: Int = 0,
    pbot :: Int = 0,
    pvec :: Vector{Int} = [0],
    overwrite :: Bool = false
) -> nothing

Downloads ERA5 data from the CDS datastore for a specified Pressure-Level variable and geographic region. You can choose to specify (1) one pressure level, (2) a vector of pressure levels or (3) a set of pressure levels defined by their top and bottom levels. A python option is also available, but this will generate python scripts for all pressure levels.

You must have installed the CDSAPI on your machine and have accepted the terms and conditions on the CDS website in order for this to work.

Arguments

e5ds : The ERA5Dataset specified (Hourly or Monthly)
- e5ds.start defines the start date
- e5ds.stop defines the end date
- e5ds.path defines the path to which all reanalysis data is saved
evar : Specifies a Pressure-Level variable to be downloaded. By default (if pall is not selected), then the pressure level closest to what is specified in evar.hPa will be downloaded.
ereg : Specifies the GeoRegion and the resolution of the data to be downloaded
ipsy : Specifies whether to generate a python script that can be used to download the data instead of Julia. If true, scripts for all pressure levels will be generated
pall : Indicates that we are selecting a range of pressure levels to be downloaded at the same time.
- ptop : Indicates the pressure level at the top layer. ptop must be < pbot
- pbot : Indicates the pressure level at the bottom layer. pbot must be > ptop
- pvec : Defines a set of pressure levels to download. Overrides ptop and pbot
overwrite : false by default. If set to true, existing data will be overwritten.

source