ERA5Reanalysis.jl

Appearance

Downloading and Reading ERA5 Datasets ​

In this page we show how you can download and read data for a given ERA5 dataset.

Setup ​

julia
using ERA5Reanalysis
using CairoMakie
using DelimitedFiles

download("https://raw.githubusercontent.com/natgeo-wong/GeoPlottingData/main/coastline_resl.txt","coast.cst")
coast = readdlm("coast.cst",comments=true)
clon  = coast[:,1]
clat  = coast[:,2]
nothing

Required Dependencies ​

Since we are downloading from the Copernicus Climate Data Store (CDS), you are required to:

  1. Register an account at the Climate Data Store

  2. Obtain your API key from the CDS API How-To page

  3. Set up your API key using addCDSAPIkey()

If this sounds complicated, fear not! You need only perform the first two steps yourself. Once you have your API key, you can use the function addCDSAPIkey() to set it up:

julia
addCDSAPIkey("<your-api-key-here>")

See the Setup page for more details.

Downloading ERA5Datasets ​

Downloading ERA5 data is as simple as:

julia
e5ds = ERA5Dataset(args...)
evar = ERA5Variable(args...)
ereg = ERA5Region(args...)
download(e5ds, evar, ereg)

Let us download the ERA5Monthly Dataset for 2020 over Southeast Asia, for example:

julia
e5ds = ERA5Monthly(start=Date(2020),stop=Date(2020),path=pwd())
evar = SingleVariable("t2m")
geo  = GeoRegion("AR6_SEA")
ereg = ERA5Region(geo)
# download(e5ds, evar, ereg)  # Uncomment to actually download
nothing
[ Info: 2026-02-08T04:02:46.434 - ERA5Reanalysis.jl - Setting up data structure containing information on the ERA5 Monthly data to be downloaded
[ Info: 2026-02-08T04:02:47.141 - ERA5Reanalysis.jl - Creating an ERA5Region based on the GeoRegion "AR6_SEA"
[ Info: 2026-02-08T04:02:47.141 - ERA5Reanalysis.jl - No grid resolution specified, defaulting to the default of 0.25º

Reading Downloaded Data ​

After downloading, you can use the function read() to access the downloaded data as an NCDataset:

julia
# ds = read(e5ds, evar, ereg, Date(2020))
nothing

Downloading Single-Level Variables ​

The following is the most basic download example for a single-level variable:

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

Downloading Pressure-Level Variables ​

The following downloads pressure-level data between 500 hPa and 600 hPa. Note that we must specify the pressure range:

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

Where is the Data Saved? ​

You can check where the data is saved for a given dataset, variable, region and datetime. The data is organized in a systematic directory structure based on:

  • Dataset type (hourly, monthly, etc.)

  • Variable ID

  • Region ID

  • Year and month

TL;DR ​

The backend download functionality of ERA5Reanalysis.jl is based upon 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 ​

Missing docstring.

Missing docstring for addCDSAPIkey. Check Documenter's build log for details.

Base.download Method
julia
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
julia
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