easysnowdata.stations.clients.HydroQuebecClient#

class easysnowdata.stations.clients.HydroQuebecClient(base_url: str = 'https://donnees.hydroquebec.com/api/explore/v2.1', timeout: int = 120, max_retries: int = 3, backoff: int = 4, session: Session | None = None)[source]#

Bases: object

Client for Hydro-Québec’s open hydrometeorological feed (Opendatasoft).

No credentials are needed. The feed is a rolling ~10-day window of hourly data; see the module docstring for why history must be accumulated by the caller (or taken from CanSWE). Data are licensed CC BY-NC 4.0 (non-commercial).

Parameters:

  • base_url (str) – Opendatasoft API root (.../api/explore/v2.1).

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

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

Stations listing any of variables in the current window.

Parameters:

  • variables (list[str] or str or None) – Native labels or standardized types; None = SWE or snow depth. Pass "all" for every station (incl. hydrometric).

  • active_only (bool) – Keep stations with at least one valid value in the window.

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

Returns:

list[dict] – station_id (e.g. "1-10613"), name, latitude, longitude, elevation_m, status, region, region_code, hq_code (code in the name, e.g. CM3V), operator, network, measurement_method, commissioned, decommissioned, has_swe, has_snwd, variables ({label: {n_obs, first, last}}), begin_date/end_date (the window held, not the period of record), latest_observation, license, station_url.

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

All stations listing SWE or snow depth.

status is "Active" when the station has at least one valid (non -999) value of any variable in the rolling window.

Parameters:

  • active_only (bool) – Keep stations with at least one valid value in the window.

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

Returns:

list[dict] – Same schema as get_stations() (which also lists non-snow stations).

Raises:

HydroQuebecError – On a portal failure.

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

Metadata and variable inventory for one station.

Parameters:

station_id (str) – Hydro-Québec identifiant, e.g. "1-10613".

Returns:

dict – The get_stations() dict plus data_variables: one entry per variable the station lists, with name, type, interval ("hourly"), units (emitted), description, notes, and begin_date/end_date/ n_obs describing the current rolling window only (valid hourly values).

Raises:

HydroQuebecError – If the station is not in the feed, or on a portal failure.

get_raw_records(station_ids: list[str], variables: list[str], begin_utc: datetime | None = None, end_utc: datetime | None = None) → list[dict][source]#

Raw portal rows (junk date = null rows excluded).

Parameters:

  • station_ids (list[str]) – Hydro-Québec identifiant values.

  • variables (list[str]) – Native French variable labels.

  • begin_utc (datetime, optional) – Half-open UTC bounds [begin_utc, end_utc).

  • end_utc (datetime, optional) – Half-open UTC bounds [begin_utc, end_utc).

Returns:

list[dict] – Portal rows with identifiant, the variable label, measure kind, unit, date (UTC ISO) and valeur (text), ordered by date.

Raises:

HydroQuebecError – On a portal 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 = 'hourly', include_flags: bool = False) → list[dict][source]#

Standardized data fetch — a flat list of observation records.

Only the last ~10 days exist; dates outside the window simply return nothing. Accumulate history yourself (or use CanSWE).

Parameters:

  • station_ids (list[str] or str or None) – Hydro-Québec identifiant values ("1-10613"). Required unless bbox is given.

  • variables (list[str] or str or None) – Native French labels or standardized types ("swe", "temp_max", …). None = SWE and snow depth.

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

  • begin_date (str or date, optional) – Inclusive YYYY-MM-DD bounds — on the UTC date for "hourly" and on the America/Toronto local date for "daily".

  • end_date (str or date, optional) – Inclusive YYYY-MM-DD bounds — on the UTC date for "hourly" and on the America/Toronto local date for "daily".

  • interval (str) – "hourly" (native; records carry datetime in UTC, YYYY-MM-DDTHH:MM:SSZ, and date is its UTC date) or "daily" (local-day aggregation; see module docstring: SWE/depth = last valid value of the local day, precip = sum, Tmax = max, Tmin = min, others = mean, wind direction = circular mean; sum/mean/max/min need >= MIN_HOURS_DAILY valid hours).

  • include_flags (bool) – Add flag: the native type_mesure for hourly records, None for daily ones. The feed has no QC flags.

Returns:

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

Raises:

  • ValueError – If neither station_ids nor bbox is provided.

  • HydroQuebecError – On an unknown variable, unsupported interval or portal error.

Example

>>> client = HydroQuebecClient()
>>> records = client.get_data(
...     bbox=(-80.0, 45.0, -57.0, 63.0), variables=["swe"], interval="daily"
... )
>>> records[0]["units"]
'cm'

Examples using easysnowdata.stations.clients.HydroQuebecClient#

Hydro-Québec gamma SWE sensors (live feed)

Hydro-Québec gamma SWE sensors (live feed)