easysnowdata.stations.clients.DWDClient#

class easysnowdata.stations.clients.DWDClient(base_url: str = 'https://opendata.dwd.de/climate_environment/CDC/observations_germany/climate/daily', timeout: int = 120, max_retries: int = 3, backoff: int = 4, session: Session | None = None, cache: bool = True, cache_path: str | Path | None = None)[source]#

Bases: object

Client for DWD CDC daily snow water equivalent and snow depth.

No credentials are needed.

Parameters:

  • base_url (str) – Root of the CDC observations_germany/climate/daily tree.

  • timeout (int) – HTTP settings for the shared retry loop.

  • max_retries (int) – HTTP settings for the shared retry loop.

  • backoff (int) – HTTP settings for the shared retry loop.

  • session (requests.Session or None) – Optional pre-configured session.

  • cache (bool) – Cache historical station zips on disk (they never change for a given file name). Recent zips are never cached.

  • cache_path (str or Path or None) – Override the cache directory (default easysnowdata.config.cache_dir("stations", "dwd")).

get_stations(products: list[str] | tuple[str, ...] | str = ('water_equiv', 'more_precip'), active_only: bool = False, bbox: tuple[float, float, float, float] | None = None) → list[dict][source]#

Stations in the given product station lists, merged by id.

Parameters:

  • products (list[str] or str) – Any of "water_equiv" (SWE stations) and "more_precip" (precipitation stations reporting snow depth / new snow).

  • active_only (bool) – Keep stations whose latest bis_datum is within ~400 days.

  • bbox (tuple, optional) – (min_lon, min_lat, max_lon, max_lat).

Returns:

list[dict] – station_id (5-digit), name, latitude, longitude, elevation_m, status, state (Bundesland), operator, measurement_method, release, has_swe, has_snwd, products ({product: {begin_date, end_date}}), begin_date, end_date, swe_begin_date, swe_end_date and station_url (None — DWD has no per-station page).

Raises:

DWDError – On an unknown product or a failed station-list download.

get_all_stations(active_only: bool = False, bbox: tuple[float, float, float, float] | None = None) → list[dict][source]#

All SWE (water_equiv) and snow-depth (more_precip) stations.

Parameters:

  • active_only (bool) – Keep stations whose latest bis_datum is within ~400 days.

  • bbox (tuple, optional) – (min_lon, min_lat, max_lon, max_lat).

Returns:

list[dict] – Same schema as get_stations() (which can also select one product).

Raises:

DWDError – If a station list cannot be downloaded.

get_metadata(station_id: str | int) → dict[source]#

Metadata and variable inventory for one station.

Parameters:

station_id (str or int) – DWD station id, with or without zero padding ("00020", 20).

Returns:

dict – The get_stations() dict plus data_variables: one entry per variable available from the station’s products, with name, type, interval, units (emitted), description, notes, begin_date/end_date (from the product station list: the period of record of the product, not of the individual column) and n_obs (None).

Raises:

DWDError – If the id is not numeric or the station is in neither station list.

get_station_rows(station_id: str | int, product: str, begin_date: str | date | None = None, end_date: str | date | None = None) → dict[str, dict[str, Any]][source]#

Merged historical + recent rows for one station and product.

Historical rows win on overlapping dates. Files that cannot hold the window (by historical file name / recent span) are not downloaded.

Parameters:

  • station_id (str or int) – DWD station id.

  • product (str) – "water_equiv" or "more_precip".

  • begin_date (str or date, optional) – Inclusive YYYY-MM-DD bounds.

  • end_date (str or date, optional) – Inclusive YYYY-MM-DD bounds.

Returns:

dict – {YYYY-MM-DD: {column: stored value or None, "QN_6": str}} in native units; {} when the station has no file.

Raises:

DWDError – On an unknown product, a bad station id, a failed download or a malformed zip.

get_data(station_ids: list[str] | str | None = None, variables: list[str] | str | None = None, bbox: tuple[float, float, float, float] | None = None, begin_date: str | date | None = None, end_date: str | date | None = None, interval: str = 'daily', include_flags: bool = False) → list[dict][source]#

Standardized data fetch — returns a flat list of observation records.

Parameters:

  • station_ids (list[str] or str or None) – DWD station id(s), with or without zero padding ("00020", "20", 20). Required unless bbox is provided.

  • variables (list[str] or str or None) – Native columns ("WASH_6") or standardized types ("swe", "snwd", "snowfall", "precip"). None means snow only: WASH_6 and SH_TAG.

  • bbox (tuple, optional) – (min_lon, min_lat, max_lon, max_lat).

  • begin_date (str or date, optional) – Inclusive YYYY-MM-DD bounds.

  • end_date (str or date, optional) – Inclusive YYYY-MM-DD bounds.

  • interval (str) – Only "daily" is supported.

  • include_flags (bool) – Add flag = the row’s QN_6 quality level.

Returns:

list[dict] – {station_id, date, variable, type, value, units, interval} records (plus flag), only for dates with a non-missing value. Stations whose files cannot be fetched are logged and skipped.

Raises:

  • ValueError – If neither station_ids nor bbox is provided.

  • DWDError – On an unknown variable or interval.

Example

>>> client = DWDClient()
>>> records = client.get_data(
...     station_ids="00020",
...     variables=["snwd"],
...     begin_date="2024-01-01",
...     end_date="2024-01-15",
... )
>>> records[0]["units"]
'cm'

Examples using easysnowdata.stations.clients.DWDClient#

German snow depth and SWE (DWD)

German snow depth and SWE (DWD)