API Reference

retrieve(dataset, params, output_path; credentials=nothing, max_wait=3600, poll_interval=10, verbose=true)

Download data from Copernicus Climate Data Store using CDS API v2.

Arguments

• dataset: CDS dataset name (e.g., "reanalysis-era5-single-levels")
• params: Dict with CDS API parameters (product_type, variable, year, month, day, time, etc.)
• output_path: Where to save the downloaded NetCDF file
• credentials: CDSCredentials object, or nothing to auto-detect
• max_wait: Maximum wait time for request (seconds)
• poll_interval: How often to check request status (seconds)
• verbose: Print progress messages

Example

params = Dict(
    "product_type" => "reanalysis",
    "variable" => ["2m_temperature"],
    "year" => ["2020"],
    "month" => ["01"],
    "day" => ["01"],
    "time" => ["00:00", "12:00"],
    "format" => "netcdf"
)

retrieve("reanalysis-era5-single-levels", params, "output.nc")

Returns

Path to downloaded file

read_cds_credentials(config_path=nothing)

Read CDS API credentials from:

1. Explicit config_path
2. Environment variables: CDSAPIURL, CDSAPIKEY
3. ~/.cdsapirc (standard location)
4. ~/.config/era5cli/cds_key.txt (era5cli location)

CDSCredentials

Stores Copernicus Climate Data Store API credentials (URL and API key).

Fields

• url::String: CDS API endpoint URL (e.g., "https://cds.climate.copernicus.eu/api")
• key::String: Your personal CDS API key

Example

creds = CDSCredentials("https://cds.climate.copernicus.eu/api", "your-api-key")

Typically obtained automatically via read_cds_credentials().

submit_cds_request(credentials, dataset, params)

Submit download request to CDS API v2. Returns status endpoint URL.

poll_request_status(credentials, status_endpoint; max_wait=3600, poll_interval=5, verbose=true)

Poll CDS request status until completion or timeout. Returns download URL when ready.

Polling starts fast (1 s) and backs off exponentially to poll_interval, so small requests that complete in seconds aren't held up to a full fixed interval, while long queue waits still poll gently.

download_cds_file(url, output_path; credentials)

Download file from CDS result URL.

request_with_retries(f; attempts=4, initial_delay=1.0, what="CDS request")

Call f(), retrying with exponential backoff on failure. The CDS gateway intermittently answers valid requests with transient errors (e.g. 502); without retries one blip kills a request that may be minutes into its queue wait — and takes every other request of a concurrent bundle down with it.

resolve_dataset(dataset, pressure_levels)

Resolve the dataset keyword (:era5 or :era5_land) and optional pressure levels to a CDS dataset id and product_type value. Returns (dataset_id, product_type), where product_type is nothing for datasets whose CDS requests take no product_type key (ERA5-Land).

hourly(; variables, startyear, months, days, hours, area=nothing,
       pressure_levels=nothing, levels=nothing, dataset=:era5, format="netcdf",
       outputprefix="era5", overwrite=false, threads=Threads.nthreads(),
       splitmonths=false, directory=".", additional_kw...)

Download ERA5 hourly data using the CDS API. This function provides compatibility with NumericalEarth's ERA5 download interface.

Arguments

• variables: Variable name(s) - String or Vector{String}. Each variable is its own CDS request; requests are submitted concurrently (up to threads at a time) so the whole bundle waits in the Copernicus queue together.
• pressure_levels: Optional pressure levels in hPa (e.g., [1000, 850, 500]). If provided, downloads from pressure-levels dataset instead of single-levels.
• levels: The v0.1 (era5cli) spelling of pressure_levels: a vector of levels in hPa selects the pressure-levels dataset; :surface and nothing mean single-levels.
• dataset: :era5 (default) or :era5_land (reanalysis-era5-land, 0.1° land-only reanalysis). ERA5-Land has no pressure levels.

Returns a vector of downloaded file paths, one per variable.

File naming

A single variable keeps the v0.2 names (outputprefix.nc for a single date/hour, outputprefix_year_month_day.nc otherwise); with multiple variables the variable name is appended to outputprefix so each request gets its own file.

monthly(; variables, year, month, area=nothing, pressure_levels=nothing,
        format="netcdf", outputprefix="era5_monthly", directory=pwd(),
        overwrite=false, threads=Threads.nthreads(), additional_kw...)

Download full month(s) of ERA5 data in single files per variable.

Downloads all days (1-31) and all hours (0-23) for each month in one CDS API request per variable per month. This is 720× faster than downloading hourly files individually.

Arguments

• variables: Variable name(s) - String or Vector{String}
• year: Year to download - Integer or Vector{Integer}
• month: Month(s) to download - Integer (1-12) or Vector{Integer}
• area: [south, west, north, east] bounding box (optional)
• pressure_levels: Optional pressure levels in hPa (e.g., [1000, 850, 500])
• dataset: :era5 (default) or :era5_land (reanalysis-era5-land, 0.1° land-only reanalysis). ERA5-Land has no pressure levels.
• format: Output format (default: "netcdf")
• outputprefix: Base filename prefix (default: "era5_monthly")
• directory: Output directory (default: pwd())
• overwrite: Overwrite existing files (default: false)
• threads: Number of download threads (default: 1)

Returns

Vector of paths to downloaded files

Example

# Download January 2020 temperature for Bouvet region
files = monthly(;
    variables = "2m_temperature",
    year = 2020,
    month = 1,
    area = [-51, -6, -58, 11],  # [south, west, north, east]
    directory = "/data/ERA5_monthly"
)

# Download multiple months
files = monthly(;
    variables = "2m_temperature",
    year = 2020,
    month = 1:3,  # Jan, Feb, Mar
    directory = "/data/ERA5_monthly"
)

File naming

Creates files: variable_YYYY_MM_bbox.nc or variable_YYYY_MM.nc (global) Example: 2m_temperature_2020_01_-51_-6_-58_11.nc

Performance

One month contains ~720-744 hourly timesteps (28-31 days * 24 hours). Download time depends on region size and CDS queue load. Smaller regions download faster; global datasets take longer.

yearly(; variables, years, area=nothing, pressure_levels=nothing,
       format="netcdf", outputprefix="era5_yearly", directory=pwd(),
       overwrite=false, threads=Threads.nthreads(), additional_kw...)

Download full year(s) of ERA5 data in single files per variable.

Downloads all months (1-12), all days (1-31), and all hours (0-23) for each year in one CDS API request per variable per year. This is 8760× faster than downloading hourly files individually.

Arguments

• variables: Variable name(s) - String or Vector{String}
• years: Year(s) to download - Integer or range (e.g., 2000 or 2000:2010)
• area: [north, west, south, east] bounding box (optional)
• pressure_levels: Optional pressure levels in hPa (e.g., [1000, 850, 500])
• dataset: :era5 (default) or :era5_land (reanalysis-era5-land, 0.1° land-only reanalysis). ERA5-Land has no pressure levels.
• format: Output format (default: "netcdf")
• outputprefix: Base filename prefix (default: "era5_yearly")
• directory: Output directory (default: pwd())
• overwrite: Overwrite existing files (default: false)
• threads: Number of download threads (default: 1)

Returns

Vector of paths to downloaded files

Example

# Download 2000-2010 temperature for Bouvet region
files = yearly(;
    variables = "2m_temperature",
    years = 2000:2010,
    area = [-51, -6, -58, 11],  # [south, west, north, east]
    directory = "/data/ERA5_yearly"
)

File naming

Creates files: variable_YYYY_bbox.nc or variable_YYYY.nc (global) Example: 2m_temperature_2000_-51_-6_-58_11.nc

Performance

One year contains 8760-8784 hourly timesteps (regular/leap year). Download time depends on region size and CDS queue load. Smaller regions download faster; global datasets take longer.