Add demo for retrieving data from Australian Bureau of Meteorology (BOM)

It will use "kiwis-pie", a Python library for querying WISKI via KiWIS.

While this is querying the BOM's Water Data Online service, apparently
there is also meteorology data available from this API, not only
hydrology related information. Check the list of available parameters
and parameter types.

wetterdienst/bom/demo.py

@@ -0,0 +1,143 @@
+"""
+About
+=====
+Demo for querying Australian Bureau of Meteorology's Water Data Online service
+using `kiwis-pie`, a Python library for querying WISKI via KiWIS
+(KISTERS Web Interoperability Solution).
+
+Setup
+=====
+::
+
+    pip install kiwis-pie
+
+Synopsis
+========
+::
+
+    python wetterdienst/bom/demo.py
+
+Resources
+=========
+- http://www.bom.gov.au/waterdata/
+- http://www.bom.gov.au/waterdata/services
+- https://github.com/amacd31/kiwis_pie
+
+"""
+from datetime import date
+from pprint import pprint
+
+from kiwis_pie import KIWIS
+
+
+class BomApi:
+    def __init__(self):
+        # Introduction.
+        print_header("About")
+        print(__doc__)
+        self.kiwis = KIWIS("http://www.bom.gov.au/waterdata/services")
+
+    def display_index(self):
+
+        # Retrieve list of sites.
+        print_header("List of all sites")
+        sites = self.kiwis.get_site_list()
+        print(sites)
+        print()
+
+        # Retrieve list of stations.
+        print_header("List of all stations")
+        stations = self.kiwis.get_station_list()
+        print(stations)
+        print()
+
+        # Retrieve list of parameters.
+        print_header("List of all parameters")
+        parameters = self.kiwis.get_parameter_list()
+        print(parameters)
+        print()
+
+        # Retrieve list of parameter types.
+        print_header("List of all parameter types")
+        parameter_types = self.kiwis.get_parameter_type_list()
+        print(parameter_types)
+        print()
+
+    def display_details(
+        self, station_name, timeseries_name, parameter_type, date_from, date_to
+    ):
+
+        # Get station information by station name.
+        station = self.kiwis.get_station_list(station_name=station_name)
+
+        # Display station information.
+        print_header(f'Station information for "{station_name}"')
+        pprint(station.to_dict(orient="list"))
+        print()
+
+        # Resolve station name to station identifier.
+        station_id = station.station_id.values[0]
+
+        # Retrieve list of timeseries.
+        print_header(f'List of all timeseries for station "{station_name}"')
+        timeseries = self.kiwis.get_timeseries_list(station_id=station_id)
+        print(timeseries)
+        print()
+
+        # Acquire some data.
+        print_header(
+            f'One month worth of "{parameter_type}" data from "{station_name}"'
+        )
+        print()
+
+        # Get timeseries ID for daily mean streamflow (Q) at "Cotter River at Gingera".
+        timeseries_id = self.kiwis.get_timeseries_list(
+            station_id=station_id,
+            ts_name=timeseries_name,
+            parametertype_name=parameter_type,
+        ).ts_id.values[0]
+
+        # Read 31 days of daily water course discharge data for "Cotter River at Gingera".
+        data = self.kiwis.get_timeseries_values(
+            ts_id=timeseries_id, to=date_to, **{"from": date_from}
+        )
+
+        # Display dataset information.
+        print_header(f"Dataset information")
+        print(f"Station name:    {station_name}")
+        print(f"Station ID:      {station_id}")
+        print(f"Timeseries name: {timeseries_name}")
+        print(f"Timeseries ID:   {timeseries_id}")
+        print(f"Parameter Type:  {parameter_type}")
+        print()
+
+        # Display data.
+        print_header(f"Data")
+        print(data)
+        print()
+
+        # Optionally use the `keep_tz` option to return in local timezone instead of UTC.
+        # k.get_timeseries_values(ts_id=ts_id, to=date(2016, 1, 31), **{"from": date(2016, 1, 1)}, keep_tz=True)
+
+
+def print_header(label):
+    length = max(len(label), 42)
+    print("-" * length)
+    print(label.center(length))
+    print("-" * length)
+
+
+def main():
+    bom = BomApi()
+    bom.display_index()
+    bom.display_details(
+        station_name="Cotter R. at Gingera",
+        timeseries_name="DMQaQc.Merged.DailyMean.24HR",
+        parameter_type="Water Course Discharge",
+        date_from=date(2016, 1, 1),
+        date_to=date(2016, 1, 31),
+    )
+
+
+if __name__ == "__main__":
+    main()