ERA5 Download

Overview

This skill enables downloading ERA5 reanalysis data from the Copernicus Climate Data Store (CDS) using the cdsapi Python package. ERA5 is a global atmospheric reanalysis dataset providing hourly estimates of atmospheric, land, and ocean climate variables from 1940 to present.

Prerequisites

Before downloading ERA5 data, ensure:

cdsapi is installed: Add via uv add cdsapi or pip install cdsapi
CDS credentials configured: Either:
- Configuration file ~/.cdsapirc with:
```
url: https://cds.climate.copernicus.eu/api
key: <YOUR-PERSONAL-ACCESS-TOKEN>
```
- Or environment variable: COPERNICUS_API_KEY=<token>
License accepted: User must accept dataset Terms of Use at https://cds.climate.copernicus.eu/datasets/reanalysis-era5-single-levels

Quick Start

Simple Download

For straightforward downloads with known variables:

import cdsapi

client = cdsapi.Client()
result = client.retrieve(
    "reanalysis-era5-single-levels",
    {
        "product_type": "reanalysis",
        "variable": ["2m_temperature", "total_precipitation"],
        "year": "2023",
        "month": "01",
        "day": ["01", "02"],
        "time": ["00:00", "06:00", "12:00", "18:00"],
        "area": [46, -123, 44, -121],  # [N, W, S, E]
        "format": "netcdf",
    },
)
result.download("output.nc")

Using the Bundled Script

For more complex downloads or command-line usage, use scripts/download_era5.py:

# Download 2m temperature for January 2023
uv run python scripts/download_era5.py \
  -v 2m_temperature \
  -s 2023-01-01 -e 2023-01-31 \
  -o temperature_jan2023.nc

# Download multiple variables for a specific region
uv run python scripts/download_era5.py \
  -v 2m_temperature total_precipitation surface_pressure \
  -s 2023-01-01 -e 2023-01-02 \
  -a 46 -123 44 -121 \
  -o climate_data.nc

# Download 6-hourly data at pressure levels (3D atmosphere)
uv run python scripts/download_era5.py \
  -v temperature geopotential \
  -s 2023-01-01 -e 2023-01-01 \
  --hours 00:00 06:00 12:00 18:00 \
  --pressure-levels 1000 850 500 \
  -o upper_air.nc

Variable Selection

Finding Variables

When users request specific climate variables:

Search the reference: Use grep on references/era5_variables.md:

grep -i "temperature" references/era5_variables.md
grep -i "precipitation" references/era5_variables.md
grep "soil_moisture" references/era5_variables.md

Common categories: The reference organizes variables by:
- Atmospheric Variables (temperature, precipitation, wind, pressure, radiation)
- Land Surface Variables (soil temperature/moisture, vegetation, snow, runoff)
- Pressure Level Variables (3D atmospheric data)
Ecosystem modeling use case: For typical biogeochemical modeling (like EcoSIM), commonly needed variables are:
- 2m_temperature - Air temperature
- total_precipitation - Precipitation
- surface_pressure - Atmospheric pressure
- surface_solar_radiation_downwards - Solar radiation
- 10m_u_component_of_wind, 10m_v_component_of_wind - Wind
- 2m_relative_humidity or 2m_dewpoint_temperature - Humidity
- Soil layers: soil_temperature_level_1, volumetric_soil_water_layer_1, etc.

Variable Name Format

ERA5 uses underscored names (e.g., 2m_temperature, not t2m or 2m-temperature).

Spatial and Temporal Subsetting

Geographic Area

Subset downloads to specific regions using bounding box [north, west, south, east] in degrees:

Script: --area 46 -123 44 -121
Direct API: "area": [46, -123, 44, -121]
Omit for global data

Temporal Selection

Control time range and resolution:

Date range: Specify start/end dates (YYYY-MM-DD format)
Hours: Subset to specific times (e.g., 6-hourly: ["00:00", "06:00", "12:00", "18:00"])
Default: All 24 hours per day

Best Practices

Start small: Test with 1-2 days before downloading years of data
Geographic subsetting: Always use --area when possible to reduce download size
Temporal subsetting: Use --hours for sub-daily data if hourly resolution isn't needed
Batch large requests: Break multi-year downloads into yearly or monthly chunks

Datasets

Single-Level (2D) Data

Dataset: reanalysis-era5-single-levels

Surface and near-surface variables
Integrated atmospheric columns
Land surface conditions
Use when variables don't require pressure levels

Pressure-Level (3D) Data

Dataset: reanalysis-era5-pressure-levels

Upper air meteorology (temperature, geopotential, winds)
Requires pressure_level parameter (e.g., [1000, 850, 500] hPa)
Use script flag: --pressure-levels 1000 850 500

Output Formats

NetCDF (Recommended)

format: "netcdf" or --format netcdf
Easier to work with in Python (xarray, netCDF4)
Compatible with most modeling frameworks
Self-describing with metadata

GRIB

format: "grib" or --format grib
Standard meteorological format
Requires specialized libraries (cfgrib, pygrib)

Workflow Patterns

Pattern 1: Climate Forcing for Models

When users need climate data to drive ecosystem/biogeochemical models:

Identify experimental site coordinates from metadata
Determine required variables for model forcing
Download ERA5 data for site location and time period
Convert to model-specific NetCDF format if needed

Example:

# For EcoSIM forcing at experimental site
download_era5(
    variables=[
        "2m_temperature",
        "total_precipitation",
        "surface_pressure",
        "surface_solar_radiation_downwards",
        "10m_u_component_of_wind",
        "10m_v_component_of_wind",
        "2m_dewpoint_temperature",
    ],
    start_date="2012-01-01",
    end_date="2022-12-31",
    area=[46.5, -122.5, 46.0, -122.0],  # Blodget site region
    output_file="ecosim_forcing_blodget.nc",
)

Pattern 2: Multi-Site Meta-Analysis

When users have multiple experimental sites requiring climate data:

Read site metadata (e.g., from TSV/CSV with lat/lon)
Loop through sites, downloading data for each location
Use consistent temporal resolution and variables across sites
Save with systematic naming convention

Pattern 3: Validation Data

When users need ERA5 data for model validation:

Download ERA5 estimates for validation variables (e.g., evaporation, runoff)
Match temporal and spatial resolution to model output
Ensure variables are comparable (same units, definitions)

Troubleshooting

License Not Accepted

Error: 403 Client Error: Forbidden ... required licences not accepted

Solution: Visit dataset page and accept Terms of Use:

Single-levels: https://cds.climate.copernicus.eu/datasets/reanalysis-era5-single-levels
Pressure-levels: https://cds.climate.copernicus.eu/datasets/reanalysis-era5-pressure-levels

Authentication Issues

If cdsapi can't authenticate:

Check ~/.cdsapirc exists with correct URL and key
Verify Personal Access Token from CDS profile
Check environment variable COPERNICUS_API_KEY if using that method

Large Downloads Timing Out

For multi-year global datasets:

Break into smaller chunks (monthly/yearly)
Use geographic subsetting with --area
Reduce temporal resolution with --hours
Consider using ERA5-Land for land-only variables (higher resolution, smaller files)

Wrong Variable Names

If variables aren't found:

Check spelling and underscores (e.g., 2m_temperature not 2m-temperature)
Verify variable exists in the chosen dataset (single-levels vs pressure-levels)
Consult references/era5_variables.md for correct names

Resources

scripts/download_era5.py

Flexible command-line tool for downloading ERA5 data with configurable parameters. Can be:

Executed directly via command line
Imported and used programmatically in Python
Modified for project-specific needs

references/era5_variables.md

Comprehensive reference of common ERA5 variables organized by category:

Atmospheric variables (temperature, precipitation, wind, radiation)
Land surface variables (soil, vegetation, snow, runoff)
Pressure level variables (3D atmosphere)
Common use cases for ecosystem modeling
Variable naming conventions and tips

Load this reference when users need help identifying which ERA5 variables to download for their specific application.

era5-download