easysnowdata.stations.clients.SNIHClient#

class easysnowdata.stations.clients.SNIHClient(base_url: str = 'https://snih.hidricosargentina.gob.ar', timeout: int = 120, max_retries: int = 3, backoff: int = 4, session: Session | None = None)[source]#

Bases: object

Client for the SNIH snow stations of Argentina.

No credentials are needed. By using the data you accept the portal’s terms of use (TERMS_URL): cite SIPH and the contributing network, keep the original meaning and state the date of the last update.

Parameters:

  • base_url (str) – Portal root.

  • 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) → list[dict][source]#

Every SNIH station associated with a snow parameter (codes 70–74).

The first call reads the station list, the network names and the station–parameter associations (about 5 MB), then checks the last 30 days of raw telemetry at each pillow station for status (one request each, four in parallel). Both are cached on the client.

Parameters:

  • active_only (bool) – Keep stations whose pillow reported in the last 30 days.

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

Returns:

list[dict] – station_id (SNIH Codigo), name, latitude, longitude (negated from the published positive values), elevation_m (None where Cota is −999 or 0), status, last_raw_obs (newest raw pillow record in the last 30 days, ISO time, or None), network_id, network / operator (the network name), data_provider, country, province / province_code, basin_code, system_code, regional_code, river, place, station_type (Tipo letters) and its description, transmission / transmission_code, snow_codes, variables, variables_since (association start per variable), measurement_method, has_swe, has_snwd and station_url.

Raises:

SNIHError – On a portal failure.

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

Station metadata plus data_variables (with period of record).

Parameters:

station_id (str) – SNIH station code (e.g. "19145", Toscas).

Returns:

dict – The station dict plus data_variables: one entry per variable and interval with name, code, type, interval, units (emitted), description, notes, associated_since (the association start the service gives), and begin_date / end_date / n_obs. For "daily" and "periodic" those come from the full historical series (n_obs counts days for "daily"); for "sub_daily" end_date is the newest raw record of the last 30 days and begin_date / n_obs are None (counting would mean reading the whole raw record).

Raises:

SNIHError – If the station is not a SNIH snow station, or 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 = 'daily', include_flags: bool = False) → list[dict][source]#

Snow data as flat records.

Parameters:

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

  • variables (list[str] or str or None) – Native names (VARIABLES), parameter codes ("73"), abbreviations or types. None = the SWE and depth variables of interval: SWE_PILLOW for "daily" and "sub_daily", SWE_COURSE + SNWD for "periodic".

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

  • begin_date (str or date, optional) – Inclusive local (Argentina) dates. Default: the whole record (raw telemetry: from 2009) to today.

  • end_date (str or date, optional) – Inclusive local (Argentina) dates. Default: the whole record (raw telemetry: from 2009) to today.

  • interval (str) – "daily" (validated pillow SWE), "sub_daily" (raw pillow telemetry) or "periodic" (snow-course surveys).

  • include_flags (bool) – Add flag: the Calificador qualifier (see DATA_FLAGS; None when blank), "unvalidated" for a historical value served with Validado = false, and "raw" on every "sub_daily" record.

Returns:

list[dict] – {station_id, date, variable, type, value, units, interval} (+ datetime in Argentina time for "sub_daily", + flag). An id the portal does not know returns no records.

Raises:

  • ValueError – If neither station_ids nor bbox is given.

  • SNIHError – On an unsupported interval, an unknown variable, a variable the interval does not offer, a non-numeric station id or a portal failure.

Example

>>> client = SNIHClient()
>>> records = client.get_data(
...     station_ids="19145",  # Toscas
...     begin_date="2015-06-01",
...     end_date="2015-09-30",
... )
>>> records[0]["units"], records[0]["interval"]
('cm', 'daily')

Examples using easysnowdata.stations.clients.SNIHClient#

Argentine snow pillows (SNIH)

Argentine snow pillows (SNIH)