☷ return to Workflows

ERA5-Land#

🌍 Access data

Description#

ERA5-Land hourly data from 1950 to present are climatic reanalysis data covering all lands.

From source website

ERA5-Land is a reanalysis dataset providing a consistent view of the evolution of land variables over several decades at an enhanced resolution compared to ERA5. ERA5-Land has been produced by replaying the land component of the ECMWF ERA5 climate reanalysis.

Data are distributed by the C3S through the Copernicus Climate Data Store, which exposes a Python API (cdsapi) used internally by GEOP4TH. A free CDS account and an API key are required before any download.

Key characteristics:

  • Temporal coverage: 1950-01-01 to present

  • Temporal resolution: hourly

  • Spatial resolution: 0.1° × 0.1° (~9 km)

  • Spatial coverage: global (lands)

  • Native CRS: EPSG:4326 (WGS84)

  • Source: C3S / CDS

GEOP4TH workflows#

ERA5-Land data are accessed through the CDS API and can be:

The downloader supports flexible area specifications (bounding box, file path, or GeoDataFrame), partial dates ('2024', '2024-03', '2024-03-15'), variable categories (e.g. 'precipitation') and predefined profiles (e.g. 'hydrogeology_water_balance'). Existing files in the output directory are detected and reused to avoid redundant downloads.

The standardizer handles:

  • temporal aggregation (hourly → daily / monthly),

  • unit corrections (J/m² → W/m² for radiation, sign correction for evaporation fluxes),

  • optional bias correction (predefined or user-supplied factors, fixed or monthly),

  • computation of secondary variables (wind_speed, relative_humidity, ET0, EW0).

CDS API setup#

Before the first download you need a free CDS account and a personal API token. The official reference is the CDS how-to-api guide, the short version:

  1. Create (or log in to) an account at cds.climate.copernicus.eu.

  2. Open your profile page and copy your Personal Access Token (under the API Token section).

  3. Save the token in a credentials file (~/.cdsapirc on Linux/macOS, %USERPROFILE%\.cdsapirc on Windows) read by cdsapi. The recommended way is the bundled geop4th cds-setup CLI, which works identically across operating systems and sets the right file permissions.

    Interactive prompt (input hidden). Accepts either the bare token, a single key: <TOKEN> line, or the full url:/key: snippet copy-pasted from the profile page:

    geop4th cds-setup

    Non-interactive variants:

    # Pass the token directly
geop4th cds-setup --token <your-personal-access-token>

# Or pipe the snippet copied from the profile page
geop4th cds-setup < copernicus_snippet.txt

# Overwrite an existing file
geop4th cds-setup --token <your-personal-access-token> --force

    The same command is also reachable as python -m geop4th.cli cds-setup if the geop4th console script isn’t on your PATH. See geop4th cds-setup --help for all flags.

    If you’d rather edit the file by hand, create ~/.cdsapirc with the snippet displayed on the profile page (equivalent to):

    url: https://cds.climate.copernicus.eu/api
key: <your-personal-access-token>

    Then restrict its permissions: chmod 600 ~/.cdsapirc.

    Create %USERPROFILE%\.cdsapirc (e.g. C:\Users\<you>\.cdsapirc) with the same two lines as above.

    As an alternative to the file, export:

    export CDSAPI_URL=https://cds.climate.copernicus.eu/api
export CDSAPI_KEY=<your-personal-access-token>

  4. Accept the dataset Terms of Use (one-off, per dataset). Open the ERA5-Land dataset page, scroll to the bottom of the Download tab and click Accept. The first download will fail with a Required licences not accepted error otherwise.

  5. (Optional) Sanity-check the connection from a shell where geoenv is active:

    python -c "import cdsapi; cdsapi.Client(); print('CDS credentials OK')"

Basic example#

import geop4th as geo

# 1. Download (requires a configured CDS API key)
files = geo.download_era5_land(
    area=(50.0, -5.0, 47.0, 0.0),         # (North, West, South, East)
    variables='hydrogeology_water_balance',
    start_date='2020',
    end_date='2024',
    output_dir='./era5land_raw',
)

# 2. Standardize: hourly -> daily, unit and sign corrections,
#    secondary variables (wind speed, RH, ET0, EW0)
geo.standardize_era5_land(
    data='./era5land_raw',
    target_frequency='daily',
    compute_secondary=True,
    output_path='./era5land_std',
)

Available variables#

ERA5-Land exposes about 60 variables grouped by physical category, plus a set of time-invariant fields (vegetation cover, soil type, land–sea mask…). Each variable carries an aggregation hint (sum / mean / min / max) used by the standardizer when changing temporal frequency.

Temperature (8 variables)

Short

Variable

Units

Aggregation

2t

2m_temperature

K

mean

2d

2m_dewpoint_temperature

K

mean

skt

skin_temperature

K

mean

stl1

soil_temperature_level_1

K

mean

stl2

soil_temperature_level_2

K

mean

stl3

soil_temperature_level_3

K

mean

stl4

soil_temperature_level_4

K

mean

tsn

temperature_of_snow_layer

K

mean
Wind & pressure (3 variables)

Short

Variable

Units

Aggregation

u10

10m_u_component_of_wind

m s-1

mean

v10

10m_v_component_of_wind

m s-1

mean

sp

surface_pressure

Pa

mean
Precipitation (2 variables)

Short

Variable

Units

Aggregation

tp

total_precipitation

m

sum

sf

snowfall

m of water equivalent

sum
Snow (7 variables)

Short

Variable

Units

Aggregation

snowc

snow_cover

%

mean

sde

snow_depth

m

mean

sd

snow_depth_water_equivalent

m of water equivalent

mean

asn

snow_albedo

(0-1)

mean

rsn

snow_density

kg m-3

mean

smlt

snowmelt

m of water equivalent

sum

es

snow_evaporation

m of water equivalent

sum
Soil water (5 variables)

Short

Variable

Units

Aggregation

swvl1

volumetric_soil_water_layer_1

m3 m-3

mean

swvl2

volumetric_soil_water_layer_2

m3 m-3

mean

swvl3

volumetric_soil_water_layer_3

m3 m-3

mean

swvl4

volumetric_soil_water_layer_4

m3 m-3

mean

src

skin_reservoir_content

m of water equivalent

mean
Evaporation & runoff (9 variables)

Short

Variable

Units

Aggregation

e

total_evaporation

m of water equivalent

sum

pev

potential_evaporation

m

sum

evabs

evaporation_from_bare_soil

m of water equivalent

sum

evatc

evaporation_from_the_top_of_canopy

m of water equivalent

sum

evavt

evaporation_from_vegetation_transpiration

m of water equivalent

sum

evaow

evaporation_from_open_water_surfaces_excluding_oceans

m of water equivalent

sum

ro

runoff

m

sum

sro

surface_runoff

m

sum

ssro

sub_surface_runoff

m

sum
Radiation & energy fluxes (7 variables)

Short

Variable

Units

Aggregation

ssrd

surface_solar_radiation_downwards

J m-2

sum

ssr

surface_net_solar_radiation

J m-2

sum

strd

surface_thermal_radiation_downwards

J m-2

sum

str

surface_net_thermal_radiation

J m-2

sum

sshf

surface_sensible_heat_flux

J m-2

sum

slhf

surface_latent_heat_flux

J m-2

sum

fal

forecast_albedo

(0-1)

mean
Vegetation (2 variables)

Short

Variable

Units

Aggregation

lai_lv

leaf_area_index_low_vegetation

m2 m-2

mean

lai_hv

leaf_area_index_high_vegetation

m2 m-2

mean
Lakes (7 variables)

Short

Variable

Units

Aggregation

lmlt

lake_mix_layer_temperature

K

mean

lmld

lake_mix_layer_depth

m

mean

lblt

lake_bottom_temperature

K

mean

ltlt

lake_total_layer_temperature

K

mean

lshf

lake_shape_factor

dimensionless

mean

lict

lake_ice_temperature

K

mean

licd

lake_ice_depth

m

mean
Time-invariant fields (10 variables)

These fields have no time dimension. They are downloaded only once and reused across all subsequent requests.

Short

Variable

Units

z

geopotential

m2 s-2

lsm

land_sea_mask

(0-1)

cl

lake_cover

(0-1)

dl

lake_total_depth

m

cvl

low_vegetation_cover

(0-1)

cvh

high_vegetation_cover

(0-1)

tvl

type_of_low_vegetation

~

tvh

type_of_high_vegetation

~

slt

soil_type

~

glm

glacier_mask

Proportion
Secondary (derived) variables (4 variables)

These variables are not downloaded as such but recomputed by the standardizer from primary variables when compute_secondary=True is passed.

Variable

Computed from

Units

Notes

wind_speed

10m_u_component_of_wind, 10m_v_component_of_wind

m s-1

vector magnitude

relative_humidity

2m_temperature, 2m_dewpoint_temperature, surface_pressure

%

Magnus formula

ET0

potential_evaporation

m

reference crop evapotranspiration

EW0

potential_evaporation

m

reference open water evaporation

Variable profiles#

Predefined bundles can be passed directly as variables= to skip having to list every variable name:

  • 'hydrogeology_water_balance' (25 variables): essential set for water balance and hydrogeological studies (precipitation, snow, evaporation, runoff, soil water, temperature, wind, radiation, dewpoint, pressure + secondary variables wind_speed, relative_humidity, ET0).

  • 'complete': every primary variable plus all invariants.

A category name (e.g. 'precipitation', 'soil_water') can also be passed and is expanded to every variable of that category.

Examples#

Coming soon…

Illustrative figures and notebook outputs.