easysnowdata.stations.clients.NVEClient#

class easysnowdata.stations.clients.NVEClient(base_url: str = 'https://hydapi.nve.no/api/v1', timeout: int = 60, max_retries: int = 3, backoff: int = 4, session: Session | None = None, api_key: str | None = None)[source]#

Bases: object

Client for the NVE HydAPI (Norwegian hydrological data service).

An API key is required for all endpoints — set the NVE_API_KEY environment variable or pass api_key. Register for a free key at https://hydapi.nve.no/.

Parameters:

base_url (str) – Base URL of the NVE HydAPI. Override for staging environments.
timeout (int) – HTTP request timeout in seconds.
max_retries (int) – Number of retry attempts on transient server errors (5xx).
backoff (int) – Base backoff delay in seconds. Actual delay = backoff × attempt_number.
session (requests.Session or None) – Optional pre-configured session (useful for proxies, etc.).

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

List NVE hydrological stations, optionally filtered by parameter.

Parameters:

parameter_ids (list[int] or int, optional) – NVE parameter ID(s) to filter stations by. - 2002 : Snow depth (Snødybde) - 2003 : Snow Water Equivalent (Snøens vannekvivalent) (2001 is soil water — NOT a snow parameter.) Defaults to no parameter filter (all stations).
active_only (bool) – If True, return only currently active stations.
bbox (tuple, optional) – (min_lon, min_lat, max_lon, max_lat) bounding box filter.

Returns:

list[dict] – One dict per station with keys: station_id, name, latitude, longitude, elevation_m, drainage_basin_key, status, station_url, parameters.

Example

>>> client = NVEClient()
>>> swe_stations = client.get_stations(parameter_ids=2002)
>>> len(swe_stations) > 20
True

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

Get all NVE stations with snow parameters (SWE and/or snow depth).

This is the recommended entry point for discovering snow monitoring stations. It fetches stations with parameter 2003 (SWE) and parameter 2002 (snow depth) and deduplicates.

Parameters:

active_only (bool) – If True, return only Active stations.
bbox (tuple, optional) – (min_lon, min_lat, max_lon, max_lat) bounding box filter.

Returns:

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

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

Retrieve full metadata for a single station.

Parameters:: station_id (str) – NVE station ID, e.g. "2.11.0".
Returns:: dict – Station metadata including keys: station_id, name, latitude, longitude, elevation_m, drainage_basin_key, status, station_url, parameters, series_list.
Raises:: NVEError – If the station is not found or the request fails.

get_series(parameter: int | None = None, station_id: str | None = None) → list[dict][source]#

List time series available in HydAPI (GET /Series).

A series is one (station, parameter, version) combination with a list of supported time resolutions and the data range covered at each resolution.

Parameters:

parameter (int, optional) – NVE parameter ID (e.g. 2003 for SWE, 2002 for snow depth). The endpoint accepts a single parameter per request.
station_id (str, optional) – NVE station ID, e.g. "2.11.0".

Returns:

list[dict] – One dict per series with keys: station_id, station_name, parameter, parameter_name, version_no, unit, serie_from, serie_to, resolutions. resolutions is the raw resolutionList — each entry has resTime (minutes: 0/60/1440), dataFromTime and dataToTime.

get_observations(station_id: str, parameter_id: int, begin_date: str | date | None = None, end_date: str | date | None = None, resolution: int = 1440) → list[dict][source]#

Fetch raw observations for a single station and parameter.

Parameters:

station_id (str) – NVE station ID, e.g. "2.11.0".
parameter_id (int) – NVE parameter ID (e.g. 2003 for SWE, 2002 for snow depth).
begin_date (str or date, optional) – Start of the observation window ("YYYY-MM-DD").
end_date (str or date, optional) – End of the observation window (inclusive).
resolution (int) – Temporal resolution in minutes. 1440 = daily; 60 = hourly.

Returns:

list[dict] – Observation records (one per timestamp), each with time, value, correction and quality fields.

Raises:

NVEError – On request failure.

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

Parameters:

station_ids (list[str] or str or None) – NVE station ID(s), e.g. "2.11.0". Required unless bbox is provided.
variables (list[str] or str or None) – NVE variable key(s) (e.g. "swe_m") or standardized types (e.g. "swe"). None returns all snow variables (SWE and snow depth).
bbox (tuple, optional) – (min_lon, min_lat, max_lon, max_lat). Alternative to station_ids; fetches data for all snow stations in the box.
begin_date (str or date, optional) – Start date ("YYYY-MM-DD").
end_date (str or date, optional) – End date (inclusive).
interval (str) – Temporal resolution: "daily" (default) or "hourly".
include_flags (bool) – If True, add a "flag" key with the NVE quality code to each record.

Returns:

list[dict] –

Flat list of observation records:

{
    "station_id": "2.11.0",
    "date": "2024-01-15",
    "variable": "swe_m",
    "type": "swe",
    "value": 12.5,   # cm (converted from m × 100)
    "units": "cm",
    "interval": "daily",
    # "flag": "0"  (only present when include_flags=True)
}

Notes

SWE values (parameter 2003) are stored by NVE in metres. This method converts them to cm (× 100) so that "units" is always "cm" for type "swe".

Snow depth values (parameter 2002) are stored by NVE in cm and are returned as-is.

Raises:

ValueError – If neither station_ids nor bbox is provided.
NVEError – On network / API failure.

Example

>>> client = NVEClient()
>>> records = client.get_data(
...     station_ids="2.11.0",
...     variables=["swe"],
...     begin_date="2024-01-01",
...     end_date="2024-01-15",
... )
>>> records[0].keys()
dict_keys(['station_id', 'date', 'variable', 'type', 'value', 'units', 'interval'])