easysnowdata.stations.clients.CEAZAClient#

class easysnowdata.stations.clients.CEAZAClient(user: str | None = None, base_url: str = 'https://www.ceazamet.cl/ws/pop_ws.php', timeout: int = 120, max_retries: int = 3, backoff: int = 4, session: Session | None = None)[source]#

Bases: object

Client for the CEAZA-Met web service (Coquimbo region, Chile).

No credentials are needed; see the module docstring for the terms of use (registration by e-mail, attribution).

Parameters:

  • user (str, optional) – The e-mail address registered with CEAZA-Met, sent as user=. Without it the service applies its anonymous limits.

  • base_url (str) – Web-service URL.

  • 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, optional) – Pre-configured session.

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

CEAZA-Met stations; by default only those with a snow sensor.

Parameters:

  • active_only (bool) – Keep stations whose latest reading is at most 90 days old.

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

  • snow_only (bool) – Keep stations with a snow-depth, SWE or snow-weight sensor (default). False lists the whole network.

Returns:

list[dict] – station_id (e_cod), name, latitude, longitude, elevation_m, status, network ("CEAZA-Met"), owner (e_owner code), operator (from OWNERS, else the code), province_code, first_reading / last_reading (as served) and begin_date / end_date (their dates), measurement_method, has_swe, has_snwd, has_temp, has_precip, is_snow_station, snow_sensors (s_cod list), snow_variables (tm_cod list), n_sensors, served_sensors and station_url.

Raises:

CEAZAError – If the service cannot be reached or returns nothing.

get_sensors(station_id: str) → list[dict][source]#

Every sensor of a station, as the network-wide sensor list gives it.

Returns:

list[dict] – station_id, sensor (s_cod), variable (tm_cod), name (tf_nombre), units (um_notacion), height_m, begin_date, end_date.

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

Station metadata plus data_variables and sensors.

Parameters:

station_id (str) – e_cod (e.g. "TPF", "TASC"); any station, snow or not.

Returns:

dict – The station dict plus data_variables (one entry per sensor this client serves: name (tm_cod), sensor, native_name, type, units (native), output_units, height_m, begin_date, end_date, intervals) and sensors (every sensor, see get_sensors()).

Raises:

CEAZAError – If the station is not in the station list.

get_series(sensor: str, begin_date: str | date, end_date: str | date, interval: str = 'daily') → dict[source]#

Raw GetSerieSensor JSON for one sensor and one window.

Returns:

dict – The service’s payload (e_cod, s_cod, tf_nombre, um_notacion, serie, …).

Raises:

CEAZAError – On an unsupported interval, an unknown sensor or a service error.

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, sensors: list[str] | str | None = None) → list[dict][source]#

Station data as flat records, one per sensor and interval with data.

Parameters:

  • station_ids (list[str] or str or None) – e_cod code(s). Required unless bbox is given.

  • variables (list[str] or str or None) – tm_cod codes ("ani_cm", "ae_mm", "ae_cm", "pnkg", "ta_c", "pp_mm") or types ("snwd", "swe", "temp", "precip"). None = the snow variables (snwd + swe).

  • bbox (tuple, optional) – (min_lon, min_lat, max_lon, max_lat); selects snow stations.

  • begin_date (str or date, optional) – Inclusive YYYY-MM-DD bounds (UTC−4 days). Default: each sensor’s first reading to today.

  • end_date (str or date, optional) – Inclusive YYYY-MM-DD bounds (UTC−4 days). Default: each sensor’s first reading to today.

  • interval (str) – "daily" (default) or "hourly".

  • include_flags (bool) – Add flag (“complete” / “partial”, see DATA_FLAGS).

  • sensors (list[str] or str, optional) – Keep only these sensor codes (s_cod), e.g. "TPFSWE_K".

Returns:

list[dict] – {station_id, date, variable, type, value, units, interval, sensor, value_min, value_max, data_pct} (+ datetime for hourly, flag). value is the interval mean (precipitation: the total) and is None outside the plausibility bounds.

Raises:

  • ValueError – If neither station_ids nor bbox is given.

  • CEAZAError – On an unknown variable, station or sensor, an unsupported interval, or a service error.

Example

>>> client = CEAZAClient()
>>> recs = client.get_data(
...     "TASC", variables="snwd",
...     begin_date="2025-08-01", end_date="2025-08-31",
... )
>>> recs[0]["units"], recs[0]["sensor"]
('cm', 'TASCAN')

Examples using easysnowdata.stations.clients.CEAZAClient#

CEAZA-Met snow stations (Coquimbo, Chile)

CEAZA-Met snow stations (Coquimbo, Chile)