whosclient 0.1.2

WHOS data retrieval functionality for HydroSOS

Purpose

To facilitate interoperable timeseries data retrieval from the WHOS (WMO Hydrological Observations System).

How to use

1. Install this module (see Installation)

2. Register into WHOS and save your access token

3. Explore WHOS portals and search engines to select the timeseries of interest

• https://community.wmo.int/en/whos-portals
• https://whos.geodab.eu/gs-service/om-api
• https://alerta.ina.gob.ar/wmlclient/wml/
• http://whos.geodab.eu/gs-service/search?view=whos-plata

4. Take note of the feature id (site) plus observedProperty, or the observationIdentifier

5. Use either a python script or notebook (see get_test.ipynb) or the command line interface to get the data (see get_test.sh) for a given time period

Installation

setup environment

python3 -m pip install venv
python3 -m venv .venv
source .venv/bin/activate

using git

git clone https://github.com/jbianchi81/whosclient.git
cd whosclient
pip install -e .

using pip

pip install whosclient

Basic Use

from whosclient.whosclient import OmOgcTimeseriesClient
client = OmOgcTimeseriesClient({"token":"my_token"}) # put your token here
metadata = client.getTimeseriesWithPagination(
  observedProperty = "Discharge",
  limit = 50
)
data = client.getData(
    "1990-01-01", 
    "2025-05-01",
    observationIdentifier = "id_of_interest" # put the id of the observation here
)

Output

Output format is either:

• a JSON-serializable list of dicts:

  [
    {
      "date": "ISO format date string",
      "value": float
    },
    ...
  ]
  

• or CSV:

  date,value
  string,float
  ...
  

Command line interface

data

Usage: whosclient data [OPTIONS] BEGIN_POSITION END_POSITION

Options:
  -t, --token TEXT                WHOS access token
  -u, --url TEXT                  WHOS OM OGC timeseries API url
  -o, --output TEXT               Save result into this file (instead of print
                                  on stdout)
  -c, --csv                       Use CSV format for output (instead of JSON)
  -m, --monitoring_point TEXT     site identifier. It must be user together
                                  with --variable_name
  -v, --variable_name TEXT        variable identifier. It must be used
                                  together with --monitoring_point
  -s, --timeseries_identifier TEXT
                                  timeseries identifier. If set,
                                  --monitoring_point and --variable_name are
                                  ignored
  --help                          Show this message and exit.

metadata

Usage: whosclient metadata [OPTIONS]

Options:
  -t, --token TEXT                WHOS access token
  -u, --url TEXT                  WHOS OM OGC timeseries API url
  -o, --output TEXT               Save result into this file (instead of print
                                  on stdout)
  -m, --monitoring_point TEXT     site (feature) identifier. It must be user
                                  together with --variable_name
  -v, --variable_name TEXT        variable identifier (=observedProperty). It
                                  must be used together with
                                  --monitoring_point
  -s, --timeseries_identifier TEXT
                                  timeseries identifier. If set,
                                  --monitoring_point and --variable_name are
                                  ignored
  -l, --limit INTEGER             pagination page size
  -h, --has_data                  return only observations with data
  -W, --west FLOAT                west longitude of bounding box
  -S, --south FLOAT               south latitude of bounding box
  -E, --east FLOAT                east longitude of bounding box
  -N, --north FLOAT               north latitude of bounding box
  -O, --ontology TEXT             The ontology to be used to expand the
                                  observed property search term (or URI) with
                                  additional terms from the ontology that are
                                  synonyms and associated to narrower
                                  concepts. Two ontologies are available: whos
                                  or his-central
  -V, --view TEXT                 Identifier of the data subset interesting
                                  for the user
  -T, --time_interpolation TEXT   The interpolation used on the time axis (for
                                  example, MAX, MIN, TOTAL, AVERAGE, MAX_PREC,
                                  MAX_SUCC, CONTINUOUS, ...)
  -i, --intended_observation_spacing TEXT
                                  The expected duration between individual
                                  observations, expressed as ISO8601 duration
                                  (e.g., P1D)
  -a, --aggregation_duration TEXT
                                  Time aggregation that has occurred to the
                                  value in the timeseries, expressed as
                                  ISO8601 duration (e.g., P1D)
  -f, --format TEXT               Response format (e.g. JSON or CSV)
  --help                          Show this message and exit.

Credits

Programa de Sistemas de Información y Alerta Hidrológico de la Cuenca del Plata

Laboratorio de Hidrología

Instituto Nacional del Agua

Argentina

2025-05-21