easysnowdata.stations.clients.SLFClient#

class easysnowdata.stations.clients.SLFClient(dataset: str = 'gcos', cache_dir: str | Path | None = None, cache_ttl_hours: float = 24.0, base_url: str = 'https://measurement-data.slf.ch', timeout: int = 120, max_retries: int = 3, backoff: int = 4, session: Session | None = None)[source]#

Bases: object

Client for open SLF snow-station datasets (GCOS SWE, new-snow SWE, manual study plots, IMIS).

No credentials are needed.

Parameters:

  • dataset (str) – "gcos" (default), "new_snow", "study_plot" or "imis"; see DATASETS and the module docstring.

  • cache_dir (str or Path or None) – Where downloads are cached. Defaults to easysnowdata.config.cache_dir("stations", "slf").

  • cache_ttl_hours (float) – Re-download a cached file of a non-static dataset older than this.

  • base_url (str) – Root of the SLF measurement-data file service (study_plot and imis). The EnviDat datasets are resolved through CKAN.

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

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

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

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

ckan_package(ckan_id: str | None = None) → dict[source]#

The EnviDat CKAN package_show record for a dataset.

Parameters:

ckan_id (str, optional) – CKAN package id; defaults to the selected dataset’s.

Returns:

dict – The result object of the CKAN response (cached).

Raises:

SLFError – On a failed request or an unsuccessful CKAN reply.

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

All stations of the selected dataset.

Parameters:

  • active_only (bool) – Keep only "Active" stations (see the module docstring for each dataset’s definition).

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

Returns:

list[dict] – station_id, name, latitude, longitude, elevation_m, status, operator, dataset, doi, license, measurement_method, period_of_record ("first/last" where known), has_swe, has_snwd, station_url; study_plot/imis add network and station_type; new_snow adds LV03 coordinates.

Raises:

SLFError – If the station list or data file cannot be fetched or parsed.

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 | None = None, include_flags: bool = False) → list[dict][source]#

Standardized data fetch — a flat list of observation records.

Parameters:

  • station_ids (list[str] or str or None) – Dataset station code(s), e.g. "5WJ" (gcos), "5WJ0" (study_plot), "WFJ2" (imis). Required unless bbox.

  • variables (list[str] or str or None) – Native names ("SWE", "HS", "HN_1D" …) or standardized types ("swe", "snwd"). None = snow only (SWE + snow depth where the dataset has them).

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

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

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

  • interval (str or None) – None = each variable at its native cadence ("periodic" for biweekly snow pits, "daily" otherwise). "periodic", "daily" or (imis) "sub_hourly" select explicitly; anything the dataset lacks raises SLFError.

  • include_flags (bool) – Adds flag (always None — SLF publishes no flags).

Returns:

list[dict] – {station_id, date, variable, type, value, units, interval} (+ datetime for sub-hourly, + flag).

Raises:

  • ValueError – If neither station_ids nor bbox is given.

  • SLFError – On an unknown variable / interval, or a source failure.

Example

>>> client = SLFClient("gcos")
>>> records = client.get_data(
...     station_ids="5WJ",
...     variables=["swe"],
...     begin_date="2024-01-01",
...     end_date="2024-05-31",
... )
>>> records[0]["units"], records[0]["interval"]
('cm', 'periodic')
get_metadata(station_id: str) → dict[source]#

Station dict plus data_variables for one station.

Parameters:

station_id (str) – Dataset station code, e.g. "5WJ" (gcos).

Returns:

dict – The get_all_stations() dict plus terms_url and data_variables: one entry per variable × interval with name, type, interval, units (emitted), description, notes, begin_date, end_date and n_obs. These are computed from the data file (non-missing values; variables without any are omitted) except for IMIS 30-minute variables, whose files are large; those report None.

Raises:

SLFError – If the station is not in the dataset.

Examples using easysnowdata.stations.clients.SLFClient#

Swiss long-term SWE (SLF)

Swiss long-term SWE (SLF)