Download ERA5 climate reanalysis data from the Copernicus Climate Data Store using cdsapi. Use this skill when users request ERA5 data, climate forcing data, meteorological variables, or need to download atmospheric/land surface data for ecosystem modeling, climate analysis, or model validation.
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.
Before downloading ERA5 data, ensure:
uv add cdsapi or pip install cdsapi~/.cdsapirc with:
url: https://cds.climate.copernicus.eu/api
key: <YOUR-PERSONAL-ACCESS-TOKEN>
COPERNICUS_API_KEY=<token>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")
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
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:
Ecosystem modeling use case: For typical biogeochemical modeling (like EcoSIM), commonly needed variables are:
2m_temperature - Air temperaturetotal_precipitation - Precipitationsurface_pressure - Atmospheric pressuresurface_solar_radiation_downwards - Solar radiation10m_u_component_of_wind, 10m_v_component_of_wind - Wind2m_relative_humidity or 2m_dewpoint_temperature - Humiditysoil_temperature_level_1, volumetric_soil_water_layer_1, etc.ERA5 uses underscored names (e.g., 2m_temperature, not t2m or 2m-temperature).
Subset downloads to specific regions using bounding box [north, west, south, east] in degrees:
--area 46 -123 44 -121"area": [46, -123, 44, -121]Control time range and resolution:
["00:00", "06:00", "12:00", "18:00"])--area when possible to reduce download size--hours for sub-daily data if hourly resolution isn't neededDataset: reanalysis-era5-single-levels
Dataset: reanalysis-era5-pressure-levels
pressure_level parameter (e.g., [1000, 850, 500] hPa)--pressure-levels 1000 850 500format: "netcdf" or --format netcdfformat: "grib" or --format gribWhen users need climate data to drive ecosystem/biogeochemical models:
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",
)
When users have multiple experimental sites requiring climate data:
When users need ERA5 data for model validation:
Error: 403 Client Error: Forbidden ... required licences not accepted
Solution: Visit dataset page and accept Terms of Use:
If cdsapi can't authenticate:
~/.cdsapirc exists with correct URL and keyCOPERNICUS_API_KEY if using that methodFor multi-year global datasets:
--area--hoursIf variables aren't found:
2m_temperature not 2m-temperature)references/era5_variables.md for correct namesFlexible command-line tool for downloading ERA5 data with configurable parameters. Can be:
Comprehensive reference of common ERA5 variables organized by category:
Load this reference when users need help identifying which ERA5 variables to download for their specific application.