easysnowdata.stations.clients.YukonClient#

class easysnowdata.stations.clients.YukonClient(base_url: str = 'https://service.yukon.ca/water-data/api/v1', timeout: int = 120, max_retries: int = 3, backoff: int = 4, session: Session | None = None)[source]#

Bases: object

Client for the Yukon Water Data (AquaCache) API.

Parameters:

  • base_url (str) – API base URL. Defaults to BASE_URL.

  • timeout (int) – Per-request timeout in seconds.

  • max_retries (int) – Number of attempts for retryable failures.

  • backoff (int) – Linear backoff multiplier, in seconds, between attempts.

  • session (requests.Session, optional) – Session to reuse. A new one is created when omitted.

Examples

>>> client = YukonClient()
>>> stations = client.get_all_stations()
>>> records = client.get_data(
...     station_ids=["09AA-M1"], variables=["swe"], interval="daily",
...     begin_date="2024-01-01", end_date="2024-01-15",
... )
get_locations(location_types: list[str] | str | None = None, networks: list[str] | str | None = None, bbox: tuple[float, float, float, float] | None = None) → list[dict][source]#

Return monitoring locations from GET /locations.

Parameters:

  • location_types (list[str] or str, optional) – Keep only these location_type values, e.g. "snowpack" or "meteorological station".

  • networks (list[str] or str, optional) – Keep only locations belonging to at least one of these networks, e.g. SNOW_SURVEY_NETWORK.

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

Returns:

list[dict] – One dict per location with keys location_id, location_code, name, alias, location_type, latitude, longitude, elevation_m, datum, note, networks and projects.

Raises:

YukonError – On network / API failure.

get_timeseries(location_ids: list[str] | str | None = None, variables: list[str] | str | None = None, publicly_visible_only: bool = True) → list[dict][source]#

Return the continuous-series catalogue from GET /timeseries.

Only series whose parameter is exposed by this client (see VARIABLES) are returned — the endpoint also lists water flow, water level, groundwater and water-quality series that have no place in a snow archive.

Parameters:

  • location_ids (list[str] or str, optional) – Restrict to these AquaCache numeric location_id values.

  • variables (list[str] or str, optional) – Restrict to these VARIABLES keys or standardized types.

  • publicly_visible_only (bool) – Drop series flagged publicly_visible = FALSE (default True).

Returns:

list[dict] – One dict per series with keys timeseries_id, location_id, location_name, variable, type, parameter_name, aggregation, recording_rate, interval, units, output_units, start_datetime, end_datetime, active, publicly_visible, owner and networks.

Raises:

YukonError – On network / API failure.

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

Return Yukon snow courses (location_type = "snowpack").

The list comes from /locations, which is authoritative, and is enriched from /snow-survey/metadata where a course appears there — that endpoint adds the first and last survey dates, per-target-date survey counts and the sub-basin used in the Yukon Snow Bulletins. Not every course is present in it: composite records such as 09DC-SC01 (Mayo Airport, the unweighted average of 09DC-SC01A and 09DC-SC01B) are listed only in /locations, so building from the metadata endpoint alone would silently drop them. Courses missing metadata fall back to their first/last survey dates derived from /snow-survey/data.

Parameters:

  • active_only (bool) – Keep only courses surveyed within the last _COURSE_ACTIVE_WINDOW_YEARS years.

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

Returns:

list[dict] – Station dicts with station_type = "SC".

Raises:

YukonError – On network / API failure.

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

Return locations that carry a continuous snow series.

A location qualifies when /timeseries lists a publicly visible SWE or snow-depth series for it. Yukon Snow Survey sites are tagged station_type = "AWS" (automated snow-weather station, snow-pillow SWE) and ECCC climate stations "ECCC".

Parameters:

  • active_only (bool) – Keep only locations with at least one active snow series.

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

  • networks (list[str] or str, optional) – Restrict to these AquaCache network names. Defaults to the Yukon Snow Survey and ECCC Meteorology networks.

Returns:

list[dict] – Station dicts with a populated series list.

Raises:

YukonError – On network / API failure.

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

Return every snow station: courses, automated Yukon sites and ECCC.

Parameters:
Returns:

list[dict] – Combined station list, sorted by station_id.

Raises:

YukonError – On network / API failure.

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

Return full metadata for one station, including its series list.

Parameters:

station_id (str) – AquaCache location_code, e.g. "09AA-M1" or "08AA-SC01".

Returns:

dict – The station dict, or {} when the code is unknown.

Raises:

YukonError – On network / API failure.

get_station_image_url(station_id: str) → None[source]#

Return the station photo URL — always None for this source.

The AquaCache API exposes no station imagery, and the Water Data Explorer that would host it sits behind a Cloudflare JS challenge. The method exists so callers can treat every client alike.

get_snow_survey_data(station_ids: list[str] | str | None = None, begin_date: str | date | None = None, end_date: str | date | None = None, include_flags: bool = False) → list[dict][source]#

Return the manual snow course archive from GET /snow-survey/data.

The endpoint takes no query parameters and returns the whole archive (~22,000 rows, ~2 MB) in one response, so filtering happens client-side and the response is cached on the instance.

Parameters:

  • station_ids (list[str] or str, optional) – Restrict to these location_code values.

  • begin_date (str or date, optional) – Restrict by sample_date (inclusive).

  • end_date (str or date, optional) – Restrict by sample_date (inclusive).

  • include_flags (bool) – Add the source flag ("Actual" / "Estimated SWE").

Returns:

list[dict] – One dict per measurement with keys station_id, name, date (true sample date), target_date, survey_period, year, month, variable, type, value, units and interval (always "periodic"), plus flag when requested.

Raises:

YukonError – On network / API failure.

Examples

>>> client = YukonClient()
>>> rows = client.get_snow_survey_data(station_ids=["08AA-SC01"])
>>> apr1 = [r for r in rows if r["survey_period"] == "01-Apr"]
get_snow_survey_stats() → list[dict][source]#

Return per-course summary statistics from GET /snow-survey/stats.

Fields include total_record_yrs, start, end, missing_yrs, sample_months, max_SWE_mm, mean_max_SWE_mm, median_max_SWE_mm and the matching *_DEPTH_cm columns. Only complete years are considered.

Returns:

list[dict] – One dict per course, values left as source strings.

Raises:

YukonError – On network / API failure.

Return per-course trend analysis from GET /snow-survey/trends.

Fields include Mann-Kendall p.value_SWE_max / p.value_DEPTH_max, Sen’s slope estimates, the number of years used, and estimated annual percent change.

Returns:

list[dict] – One dict per course, values left as source strings.

Raises:

YukonError – On network / API failure.

get_daily_measurements(timeseries_ids: list[str] | str | int, begin_date: str | date | None = None, end_date: str | date | None = None, stats: bool = False) → list[dict][source]#

Fetch daily aggregates from GET /timeseries/measurementsDaily.

Parameters:

  • timeseries_ids (list[str] or str or int) – AquaCache timeseries_id value(s).

  • begin_date (str or date, optional) – Start date (inclusive). Defaults to _EPOCH.

  • end_date (str or date, optional) – End date (inclusive). Defaults to today.

  • stats (bool) – Include the historical range statistics columns (percentiles, 30-year normals, day-of-year counts).

Returns:

list[dict] – Raw rows: timeseries_id, date, day_timezone, value, imputed (plus statistics columns when stats=True).

Notes

value is the mean over the local day given by day_timezone (UTC-07 for Yukon Snow Survey sites), not an instantaneous reading.

Raises:

YukonError – On network / API failure.

get_measurements(timeseries_ids: list[str] | str | int, begin_date: str | date | None = None, end_date: str | date | None = None) → list[dict][source]#

Fetch instantaneous values from GET /timeseries/measurements.

Parameters:

  • timeseries_ids (list[str] or str or int) – AquaCache timeseries_id value(s).

  • begin_date (str or date, optional) – Start date/time (inclusive). Defaults to _EPOCH.

  • end_date (str or date, optional) – End date/time (inclusive). Defaults to now.

Returns:

list[dict] – Raw rows including datetime, value_raw, value_corrected, grade_type_description, approval_type_description and qualifier_type_descriptions.

Raises:

YukonError – On network / 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 = '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) – AquaCache location_code value(s), e.g. "09AA-M1" for an automated snow-weather station or "08AA-SC01" for a snow course. Required unless bbox is provided.

  • variables (list[str] or str or None) – VARIABLES key(s) (e.g. "swe_mm") or standardized types (e.g. "swe"). None returns all snow variables.

  • 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) – "daily" (default) reads the daily aggregates; "hourly" / "sub_daily" reads instantaneous values; "periodic" reads the manual snow course archive.

  • include_flags (bool) – If True, add a "flag" key to each record.

Returns:

list[dict] –

Flat list of observation records:

{
    "station_id": "09AA-M1",
    "date": "2024-01-15",
    "variable": "swe_mm",
    "type": "swe",
    "value": 12.5,     # cm (converted from mm ÷ 10)
    "units": "cm",
    "interval": "daily",
    "aggregation": "instantaneous",
    "timeseries_id": "20",
    # "flag": "" (only present when include_flags=True)
}

aggregation and timeseries_id are extra keys that disambiguate locations holding several series of the same parameter (ECCC daily air temperature exists as minimum, maximum and mean). Sub-daily records additionally carry datetime.

Notes

SWE is stored by AquaCache in mm and is converted to cm, so "units" is always "cm" for type "swe". Snow depth is natively cm and is returned as-is. Other met variables keep their native units, as in the DataBC client.

Raises:

  • ValueError – If neither station_ids nor bbox is provided.

  • YukonError – On network / API failure.

Examples

>>> client = YukonClient()
>>> records = client.get_data(
...     station_ids="09AA-M1",
...     variables=["swe"],
...     begin_date="2024-01-01",
...     end_date="2024-01-15",
... )
>>> sorted(records[0])[:4]
['aggregation', 'date', 'interval', 'station_id']