easysnowdata.stations.clients.CDECClient#

class easysnowdata.stations.clients.CDECClient(timeout: int = 60, max_retries: int = 3, backoff: int = 4, session: Session | None = None)[source]#

Bases: object

Client for CDEC (California Data Exchange Center).

Parameters:

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

  • max_retries (int) – Retry attempts on transient server errors (5xx / connection errors).

  • backoff (int) – Base backoff delay in seconds (actual delay = backoff × attempt).

  • session (requests.Session or None) – Optional pre-configured session.

get_snow_courses() → list[dict][source]#

Fetch the CCSS manual snow course station list.

Source: CDEC SnowCourses report page (HTML table).

Returns:

list[dict] – One dict per snow course with keys: station_id, course_number, name, elevation_ft, latitude, longitude, april1_avg_swe_in, measuring_agency, is_snow_course, station_url.

get_snow_pillows() → list[dict][source]#

Fetch the CDEC automated snow pillow (CCSS sensor) station list.

Source: CDEC SnowSensors report page (HTML table).

Returns:

list[dict] – One dict per station with keys: station_id, name, elevation_ft, latitude, longitude, april1_avg_swe_in, operator, is_snow_pillow, has_daily_swe, station_url.

get_stations(sensors: tuple[int, ...] = (3, 18, 82), active_only: bool = False) → list[dict][source]#

Get all CDEC stations that have any of the specified snow sensors.

Queries the CDEC station search for each sensor number and merges the results. Supplements with the official SnowCourses and SnowSensors report pages to flag CCSS membership.

Parameters:

  • sensors (tuple[int, ]) – CDEC sensor numbers to include. Defaults to (3, 18, 82).

  • active_only (bool) – If True, request only currently active stations.

Returns:

list[dict] – One dict per unique station with keys from staSearch plus: sensors (sorted list of found sensor numbers), has_daily_swe, has_daily_snwd, is_snow_course, is_snow_pillow, station_url.

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

Fetch full station metadata by scraping the CDEC staMeta page.

Returns all metadata available on the station page including the sensor inventory (sensor number, description, duration, date range).

Parameters:

station_id (str) – CDEC station ID (e.g. "QUA").

Returns:

dict – Keys: station_id, name, elevation_ft, river_basin, county, hydrologic_area, nearby_city, latitude, longitude, operator, maintenance, sensor_inventory (list of sensor inventory dicts), station_url.

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

Standardized station list (automated pillows + manual courses).

Parameters:

  • active_only (bool) – If True, filter to currently active stations.

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

Returns:

list[dict] – Combined list of all CDEC snow stations.

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) – CDEC station ID(s), e.g. "QUA". Required unless bbox is provided.

  • variables (list[str] or str or None) – Sensor short names (e.g. "SNO ADJ") or standardized types (e.g. "swe"). None fetches all sensors in SENSORS. For type "swe", sensor 82 (SNO ADJ) is preferred over sensor 3 (SNOW WC).

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

  • begin_date (str or date, optional)

  • end_date (str or date, optional)

  • interval (str) – "daily", "hourly", "monthly", "sub_daily".

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

Returns:

list[dict] –

Flat list of observation records:

{
    "station_id": "QUA",
    "date": "2024-01-15",
    "variable": "SNO ADJ",
    "type": "swe",
    "value": 24.7,
    "units": "cm",
    "interval": "daily",
    # "flag": "r"  (only when include_flags=True)
}

Notes

When multiple SWE sensors are present for the same station and date, sensor 82 (SNO ADJ) takes priority over sensor 3 (SNOW WC).

Raises:

  • ValueError – If neither station_ids nor bbox is provided.

  • CDECError – On network / API failure.