easysnowdata.stations.clients.SYKEClient#

class easysnowdata.stations.clients.SYKEClient(base_url: str = 'https://rajapinnat.ymparisto.fi/api/Hydrologiarajapinta/1.1/odata', timeout: int = 60, max_retries: int = 3, backoff: int = 4, session: Session | None = None, keep_modelled: bool = False)[source]#

Bases: object

Client for the Syke hydrology OData API (snow courses and areal SWE).

No credentials are needed.

Parameters:

  • base_url (str) – OData service root.

  • 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.

  • keep_modelled (bool) – If False (default), snow-course values flagged as snow-model output (Lippu_Id 110/117) are returned as None.

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

All Syke snow courses (Suure_Id 8).

Parameters:

  • active_only (bool) – Keep sites whose Tila is continuous or fixed-term.

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

Returns:

list[dict] – station_id (Paikka_Id), name, latitude, longitude, elevation_m (always None), status, status_native, site_number, municipality, basin, sub_basin, operator, measurement_method, ETRS-TM35FIN coordinates and station_url (None). The period of record is not in the site table; use get_metadata().

Raises:

SYKEError – On an API failure.

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

Areal-SWE units (Suure_Id 7).

Parameters:

  • active_only (bool) – Keep units whose Tila is continuous or fixed-term.

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

Returns:

list[dict] – Same schema as get_all_stations().

Raises:

SYKEError – On an API failure.

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

Site metadata plus data_variables (with period of record).

Works for snow courses and for areal-SWE units (variable “SA”, interval “semi_monthly”).

Parameters:

station_id (str) – Paikka_Id of a snow course or areal-SWE unit.

Returns:

dict – The station dict plus kind ("snow_course" / "areal") and data_variables: one entry with name, type, interval, units (emitted), description, notes, begin_date, end_date and n_obs (from the data table).

Raises:

SYKEError – If the id is neither a snow course nor an areal-SWE unit, or on an API failure.

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

Snow-course SWE as flat records.

Parameters:

  • station_ids (list[str] or str or None) – Paikka_Id(s). Required unless bbox is given.

  • variables (list[str] or str or None) – "S" or "swe"; None = ["S"].

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

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

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

  • interval (str) – Only "periodic".

  • include_flags (bool) – Add flag = the Lippu_Id (see DATA_FLAGS).

Returns:

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

Raises:

  • ValueError – If neither station_ids nor bbox is given.

  • SYKEError – On an unknown variable, unsupported interval, non-integer station id or API failure.

Example

>>> client = SYKEClient()
>>> stations = client.get_all_stations(active_only=True)
>>> records = client.get_data(
...     station_ids=stations[0]["station_id"],
...     begin_date="2024-01-01",
...     end_date="2024-05-31",
... )
>>> records[0]["units"]
'cm'
get_areal_swe(area_ids: 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, active_only: bool = False) → list[dict][source]#

Areal (catchment-average) SWE, interval="semi_monthly".

Parameters:

  • area_ids (list[str] or str or None) – Areal-unit Paikka_Id values (see get_areal_units()). With neither area_ids nor bbox every unit is fetched (≈116 000 rows for the full record — pass dates).

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

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

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

  • active_only (bool) – When resolving units from bbox / all units, keep active ones.

Returns:

list[dict] – {station_id, date, variable ("SA"), type, value (cm), units, interval ("semi_monthly")} records.

Raises:

SYKEError – On an API failure.

Examples using easysnowdata.stations.clients.SYKEClient#

Finnish snow courses (SYKE)

Finnish snow courses (SYKE)