easysnowdata.stations.clients.DataBCClient#

class easysnowdata.stations.clients.DataBCClient(timeout: int = 120, max_retries: int = 3, backoff: int = 5, session: Session | None = None)[source]#

Bases: object

Client for BC snow survey data via BC Data Catalogue.

Provides access to both Automated Snow Weather Station (ASWS) data and Manual Snow Survey (MSS) data through publicly available BC government endpoints. Also provides access to ASWS station photos via the AQRT BCMOE portal.

Parameters:

  • timeout (int) – HTTP request timeout in seconds.

  • max_retries (int) – Retry attempts on transient server errors.

  • backoff (int) – Base backoff delay in seconds.

  • session (requests.Session or None) – Optional pre-configured session for data/WFS requests.

get_asws_stations(active_only: bool = False) → list[dict][source]#

Get Automated Snow Weather Station (ASWS) locations from WFS.

These are automated snow pillow stations that report daily SWE. Location IDs end in P (e.g. 1A01P).

Parameters:

active_only (bool) – If True, filter to Active stations only.

Returns:

list[dict] – One dict per station with keys: location_id, name, elevation_m, latitude, longitude, status, operator, camera_url, station_type, station_url.

get_mss_stations(active_only: bool = False) → list[dict][source]#

Get Manual Snow Survey (MSS) site locations from WFS.

These are periodic manual snow course measurement sites. Location IDs do NOT end in P (e.g. 1A06A, 1A10).

Parameters:

active_only (bool) – If True, filter to Active sites only.

Returns:

list[dict] – One dict per site with keys: location_id, name, elevation_m, latitude, longitude, status, station_type, station_url.

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

Get both ASWS and MSS stations.

Parameters:

  • active_only (bool) – If True, filter to Active stations/sites only.

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

Returns:

list[dict] – Combined list of ASWS and MSS stations.

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

Full metadata for a single station, including its variable inventory.

Combines the WFS station record with this client’s variable registry: ASWS stations share one CSV-file variable suite; MSS sites carry the periodic survey variables.

Parameters:

station_id (str) – BC location ID, e.g. "1A01P" (ASWS) or "1A06A" (MSS).

Returns:

dict – The station dict plus a variables mapping ({key: VARIABLES[key]}). Empty dict for unknown IDs.

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

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

For ASWS stations, daily SWE is sourced from SWDaily.csv (16:00 UTC reading). For MSS stations, all survey variables are returned with interval="periodic".

Parameters:

  • station_ids (list[str] or str or None) – Location ID(s), e.g. "1A01P" (ASWS) or "1A01" (MSS). Required unless bbox is provided.

  • variables (list[str] or str or None) – DataBC variable keys (e.g. "swe_mm") or standardized types (e.g. "swe"). None returns all variables in VARIABLES available for the given station type.

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

  • begin_date (str or None) – Date range ("YYYY-MM-DD").

  • end_date (str or None) – Date range ("YYYY-MM-DD").

  • interval (str) – "daily" fetches ASWS daily data (16:00 UTC canonical reading; SWE from the pre-aggregated SWDaily.csv); "hourly" / "sub_daily" fetch all hourly ASWS readings (records carry a datetime key); "periodic" fetches MSS survey data. Any other value raises DataBCError.

  • include_flags (bool) – If True, MSS survey codes are included as "flag" field.

Returns:

list[dict] –

Flat list of observation records:

{
    "station_id": "1A01P",
    "date": "2024-01-15",
    "variable": "swe_mm",
    "type": "swe",
    "value": 45.0,   # mm ÷ 10 → cm for swe_mm
    "units": "cm",
    "interval": "daily",
    # "flag": None  (only when include_flags=True)
}

Notes

swe_mm values are converted to cm (÷ 10) in this method so that the returned "units" is always "cm" for type "swe".

Raises:

  • ValueError – If neither station_ids nor bbox is provided.

  • DataBCError – On network / data-loading failure.

get_station_image_url(location_id: str) → str | None[source]#

Get the station photo URL for an ASWS station from the AQRT BCMOE portal.

Scrapes https://bcmoe-prod.aquaticinformatics.net (the public BC Ministry of Environment AQUARIUS Web Portal). The portal requires accepting a one-time disclaimer; this client does so lazily and reuses the session for subsequent calls.

The returned URL is a direct GetFileById link that can be embedded in an <img> tag. Returns None if the station has no photo or the portal is unreachable.

Parameters:

location_id (str) – ASWS station location ID, e.g. "1E08P".

Returns:

str or None – Direct image URL, e.g. "https://bcmoe-prod.aquaticinformatics.net/Data/GetFileById/12345", or None if no photo is available.