Querying data using the wis2box API
Learning outcomes
By the end of this practical session, you will be able to:
- use the wis2box API to query and filter your stations
- use the wis2box API to query and filter your data
Introduction
The wis2box API provides discovery and query access in a machine readable manager, which includes the wis2box UI.
In this practical session you will learn how to use the data API to discovery, browse and query data that has been ingested in wis2box.
Preparation
Note
Navigate to the wis2box API landing page in your web browser:
http://<your-host>/oapi
Inspecting collections
From the landing page, click on the 'Collections' link.
Question
How many dataset collections do you see on the resulting page? What do you think each collection represents?
Click to reveal answer
There should be 4 collections displayed, including "Stations", "Discovery metadata", and "Data notifications"
Inspecting stations
From the landing page, click on the 'Collections' link, then click on the 'Stations' link.
Click on the 'Browse' link, then click on the 'json' link.
Question
How many stations are returned? Compare this number to the station list in http://<your-host>/wis2box-webapp/station
Click to reveal answer
The number of stations from the API should be equal to the number of stations you see in the wis2box webapp.
Question
How can we query for a single station (e.g. Balaka)?
Click to reveal answer
Query the API with http://<your-host>/oapi/collections/stations/items?q=Balaka.
Note
The above example is based on the Malawi test data. Try testing against the stations your have ingested as part of the previous exercises.
Inspecting observations
Note
The above example is based on the Malawi test data. Try testing against the observation your have ingested as part of the exercises.
From the landing page, click on the 'Collections' link, then click on the 'Surface weather observations from Malawi' link.
Click on the 'Queryables' link.
Question
Which queryable would be used to filter by station identifier?
Click to reveal answer
The wigos_station_identifer is the correct queryable.
Navigate to the previous page (i.e. http://<your-host>/oapi/collections/urn:wmo:md:mwi:mwi_met_centre:surface-weather-observations)
Click on the 'Browse' link.
Question
How can we visualize the JSON response?
Click to reveal answer
By clicking on the 'JSON' link at the top right of the page, of by adding f=json to the API request on the web browser.
Inspect the JSON response of the observations.
Question
How many records are returned?
Question
How can we limit the response to 3 observations?
Click to reveal answer
Add limit=3 to the API request.
Question
How can we sort the response by the latest observations?
Click to reveal answer
Add sortby=-resultTime to the API request (notice the - sign to denote descending sort order). For sorting by the earliest observations, update the request to include sortby=resultTime.
Question
How can we filter the observations by a single station?
Click to reveal answer
Add wigos_station_identifier=<WSI> to the API request.
Question
How can we receive the observations as a CSV?
Click to reveal answer
Add f=csv to the API request.
Question
How can we show a single observation (id)?
Click to reveal answer
Using the feature identifier from an API request against the observations, query the API for http://<your-host>/oapi/collections/{collectionId}/items/{featureId}, where {collectionId} is the name of your observations collection and {itemId} is the identifier of the single observation of interest.
Conclusion
Congratulations!
In this practical session, you learned how to:
- use the wis2box API to query and filter your stations
- use the wis2box API to query and filter your data