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:x-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