The query module#

Querying OSCAR/Surface#

In order to extract information about stations registered on the OSCAR/Surface database, one can use the function:

query_oscar_surface(extract_prms: list | None = None, **search_prms: str) → DataFrame[source]

Utility function to query OSCAR/Surface and extract relevant station information and return them as a polars DataFrame.

This function acts as a simple wrapper around the OSCAR/Surface API: it merely forwards the keyword arguments it receives to the API, and extracts a few relevant parameters from the reply into a polars DataFrame.

Warning

This function does not check the validity of the keywords arguments. It is up to the user to ensure the keyword arguments are valid and supported by the OSCAR/Surface API.

Note

See the OSCAR/Surface API Reference for the full range of supported keyword arguments.

Parameters:

  • extract_prms (list, optional) – list of additional parameters to extract from the API reply,

  • in addition to ``[‘wigosId’, ‘name’, ‘longitude’, ‘latitude’]``.

  • **search_prms – search keyword-arguments-and-value-pairs, to be fed directly to the params keyword of the API requests.get() function.

Returns:

DataFrame containing the API response data.

Return type:

pl.DataFrame

Raises:

WmoutilsError – if the API request fails, or if the extract_prms argument is not a list of strings.

Examples

To query a station with a specific wigosId:

from wmoutils.query import query_oscar_surface

out = query_oscar_surface(wigosId='0-20000-0-06610')

To query all fixed surface stations in Switzerland:

out = query_oscar_surface(territoryName='CHE', facilityType='LandFixed')

Querying WDQMS#

In order to extract information from the WIGOS Data Quality Monitoring System (WDQMS), one can use the function:

query_wdqms(module: str, station_type: str, interval: str, category: str, var_name: str, date: str, period: str = '00', baseline: str = 'OSCAR') → DataFrame[source]

Utility function to query WDQMS via its API, and format the reply as a polars.DataFrame.

Warning

This function currently does not allow to query all possible combinations of parameters supported by the WDQMS API. While coverage might grow overtime, it may never cover all options.

Parameters:

  • module (str) – one of ['gbon', 'nwp'].

  • station_type (str) – one of ['surface', 'upper-air', 'marine'].

  • interval (str) – assessment interval, i.e. one of ['monthly', 'daily', 'six_hour'].

  • category (str) – one of ['availability', 'quality', 'timeliness'].

  • var_name (str) – one of ['temperature', 'pressure', 'humidity', 'zonal_wind', 'meridional_wind'].

  • date (str) – date of the availability assessment, e.g. '2023-11'.

  • period (str, optional) – one of ['00', '06', '12', '18']. Defaults to '00'. No effect unless if interval is 'six_hour'.

  • baseline (str, optional) – one of ['OSCAR', 'hourly']. Defaults to 'OSCAR'. No effect unless if module is 'nwp'.

Returns:

the reply from the API request formatted as a polars DataFrame.

Return type:

polars.DataFrame

Raises:

WmoutilsError – if the API request fails, or if the combination of input parameters is invalid.

Examples

Querying the availability of temperature observations for surface stations in GBON for January 2026:

from wmoutils.query import query_wdqms

out = query_wdqms(module='gbon', station_type='surface', var_name='temperature',
                  interval='monthly', category='availability', date='2026-01')

Todo

  • Allow to query individual NWP centers.

  • Add support for GCOS and Transition Monitoring.