API Reference

hourly(; variables, startyear, kwargs...) -> Vector{String}

Download ERA5 hourly data using era5cli.

Required Arguments

• variables: Variable name(s) to download. Can be a string or vector of strings. Examples: "2m_temperature", ["2m_temperature", "total_precipitation"]
• startyear: First year to download (integer).

Optional Arguments

• endyear: Last year to download (default: same as startyear).
• months: Month(s) to download (1-12). Default: all months.
• days: Day(s) to download (1-31). Default: all days.
• hours: Hour(s) to download (0-23). Default: all hours.
• area: Bounding box for spatial subsetting. Can be:
  • A tuple (lat_max, lon_min, lat_min, lon_max) in era5cli order
  • A NamedTuple (lat=(south, north), lon=(west, east))
• format: Output format, "netcdf" (default) or "grib".
• outputprefix: Prefix for output filenames (default: "era5").
• overwrite: Overwrite existing files without prompting (default: true).
• threads: Number of parallel download threads (default: 1).
• splitmonths: Split output by months (default: true).
• merge: Merge all output into a single file (default: false).
• dryrun: Print the request without downloading (default: false).
• land: Download from ERA5-Land dataset (default: false).
• ensemble: Download ensemble data instead of HRES (default: false).
• levels: Pressure level(s) for 3D variables, or :surface for surface geopotential.
• statistics: Download ensemble statistics (default: false).
• directory: Directory to download files into (default: current directory).

Returns

• If dryrun=true: the Cmd object that would be executed.
• Otherwise: a Vector{String} of paths to the downloaded file(s).

Output Files

By default, era5cli creates one file per month (splitmonths=true). If you request multiple months, you will receive multiple files. Use merge=true to combine all data into a single file, or splitmonths=false to get one file per variable.

Example

using CopernicusClimateDataStore

# Download 2m temperature for a single day
files = hourly(variables="2m_temperature",
               startyear=2020,
               months=1,
               days=1,
               hours=12,
               area=(lat=(40, 50), lon=(-10, 10)),
               format="netcdf")

# files[1] contains the path to the downloaded NetCDF file

CDS Setup Required

Before downloading, you must:

1. Create an account at https://cds.climate.copernicus.eu/
2. Accept the Terms of Use for the ERA5 dataset on the dataset page
3. Configure your API key with era5cli config --key YOUR_KEY

See https://cds.climate.copernicus.eu/how-to-api for details.

info(; what=:variables, land=false, levels=false)

Display information about available ERA5 variables or pressure levels.

Arguments

• what: What to show - :variables (default), :levels, or a specific variable name.
• land: Show ERA5-Land variables instead of ERA5 (default: false).
• levels: Show available pressure levels (default: false).

install_era5cli()

Install the era5cli command-line tool (version ≥ 2.0.1) using CondaPkg. Returns the path to the installed CLI executable.

Note: The old Climate Data Store (CDS) was shut down on 3 September 2024. All era5cli versions up to v1.4.2 no longer work. This function installs a compatible version.

era5cli_cmd()

Return the absolute path to the era5cli executable. If not found, attempts to install it first.

build_hourly_cmd(; kwargs...)

Build the command-line arguments for era5cli hourly. Returns a Cmd object ready to be executed.

The cli keyword can be used to override the path to the era5cli executable (useful for testing command construction without installing era5cli).

format_area(area)

Convert a bounding box specification to the format required by era5cli: LAT_MAX LON_MIN LAT_MIN LON_MAX (counterclockwise starting at top).

Accepts:

• nothing → returns nothing (no area constraint)
• A tuple/vector of 4 numbers in era5cli order: (lat_max, lon_min, lat_min, lon_max)
• A NamedTuple with keys lat and lon, each a tuple of (min, max): (lat=(lat_min, lat_max), lon=(lon_min, lon_max))

monthly(; variables, startyear, kwargs...)

Download ERA5 monthly-averaged data using era5cli.

Arguments are similar to hourly, but downloads monthly means instead of hourly data. See era5cli monthly --help for full details.