add tool to query OSCAR to support station management (#469) (#504)

* add tool to query OSCAR to support station management (#469)

* add click hook

* update docstring

* update docs

* update docs

docs/source/reference/running/station-metadata.rst

@@ -20,8 +20,30 @@ processing.
 
 .. seealso:: :ref:`api-publishing`
 
+OSCAR/Surface
+-------------
+
+wis2box can derive station information from `OSCAR/Surface`_.  To verify station metadata from OSCAR/Surface:
+
+.. code-block:: bash
+
+   wis2box metadata station get WSI
+
+
+where ``WSI`` is the WIGOS Station Identifier.  This command will return the information required in the
+station list for wis2box data processing and publication.  To add the station information to the station list,
+copy and paste the output of the above command, or rerun the above command, writing to the station list
+automatically:
+
+
+.. code-block:: bash
+
+   wis2box metadata station get WSI >> ~/wis2box-data/metadata/station/station_list.csv
+
 
 Summary
 -------
 
 At this point, you have cached the required station metadata for your given dataset(s).
+
+.. _`OSCAR/Surface`: https://oscar.wmo.int/surface

docs/source/user/setup.rst

@@ -162,7 +162,7 @@ wis2box requires information about the stations for which you will be sharing da
 
 An example of the configuration file for the stations is provided in ``station_list.csv``. 
 
-You can copy this file to ``metadata/station/station_list.csv`` in your $WIS2BOX_HOST_DATADIR :
+You can copy this file to ``metadata/station/station_list.csv`` in your $WIS2BOX_HOST_DATADIR:
 
 .. code-block:: bash
 
@@ -176,6 +176,18 @@ And edit ``~/wis2box-data/metadata/station/station_list.csv`` to include the dat
    The ``station_list.csv`` requires column names ``station_name`` and the ``wigos_station_identifier`` (WSI) with which the station is registered in `OSCAR`_.  Optionally, you can provide a ``traditional_station_identifier (TSI)`` column.
    The TSI can be left empty if your data contains a WSI. If your data contains a TSI but no WSI, the ``station_list.csv`` will be used to derive the corresponding WSI for that station.
 
+To verify station metadata from OSCAR/Surface, run the following command:
+
+.. code-block:: bash
+
+   wis2box metadata station get <WSI>
+
+Then to add to the station list:
+
+.. code-block:: bash
+
+   wis2box metadata station get <WSI> >> ~/wis2box-data/metadata/station/station_list.csv
+
 Discovery metadata
 ------------------
 

wis2box-management/Dockerfile

@@ -43,6 +43,7 @@ RUN apt-get update -y && apt-get install -y ${DEBIAN_PACKAGES} \
     https://github.com/wmo-im/bufr2geojson/archive/refs/tags/v0.5.0.zip \
     https://github.com/wmo-im/pymetdecoder/archive/refs/tags/v0.1.7.zip \
     https://github.com/wmo-im/synop2bufr/archive/refs/tags/v0.4.1.zip \
+    https://github.com/wmo-cop/pyoscar/archive/refs/tags/0.5.0.zip \
     https://github.com/geopython/pygeometa/archive/refs/tags/0.14.0.zip \
     https://github.com/wmo-im/pywcmp/archive/refs/tags/0.4.0.zip \
     # install shapely

wis2box-management/wis2box/metadata/station.py

@@ -20,13 +20,15 @@
 ###############################################################################
 
 import click
+from collections import OrderedDict
 import csv
 import json
 import logging
 from typing import Iterator, Union
 
 from owslib.ogcapi.features import Features
 from pygeometa.schemas.wmo_wigos import WMOWIGOSOutputSchema
+from pyoscar import OSCARClient
 
 from wis2box import cli_helpers
 from wis2box.api import (
@@ -310,6 +312,42 @@ def get_geometry(wsi: str = '') -> Union[dict, None]:
     return None
 
 
+@click.command()
+@click.pass_context
+@click.option('--wigos-station-identifier', '-wsi',
+              help='WIGOS station identifier')
+@cli_helpers.OPTION_VERBOSITY
+def get(ctx, wigos_station_identifier, verbosity):
+    """Queries OSCAR/Surface for station information"""
+
+    client = OSCARClient(env='prod')
+
+    station = client.get_station_report(wigos_station_identifier)
+
+    results = OrderedDict({
+        'station_name': station['name'],
+        'wigos_station_identifier': wigos_station_identifier,
+        'traditional_station_identifier': None,
+        'facility_type': station['typeName'],
+        'latitude': station['locations'][0]['latitude'],
+        'longitude': station['locations'][0]['longitude'],
+        'elevation': station['locations'][0].get('elevation'),
+        'territory_name': station['territories'][0]['territoryName'],
+        'wmo_region': WMO_RAS[station['wmoRaId']]
+    })
+
+    if '0-2000' in station['wigosIds'][0]['wid']:
+        results['traditional_station_identifier'] = station['wigosIds'][0]['wid'].split('-')[-1]  # noqa
+
+    for v in ['station_name', 'territory_name']:
+        if ',' in results[v]:
+            results[v] = f'"{results[v]}"'
+
+    line = ','.join([(str(results[k]) if results[k] is not None else '') for k, v in results.items()])  # noqa
+
+    click.echo(line)
+
+
 @click.command()
 @click.pass_context
 @cli_helpers.OPTION_VERBOSITY
@@ -320,4 +358,5 @@ def publish_collection(ctx, verbosity):
     click.echo('Done')
 
 
+station.add_command(get)
 station.add_command(publish_collection)