Sensorthings API Queries

How to Build SensorThings API Queries for WySEaSON

The common building blocks for Sensorthings Odata APIs

REST Information

GET requests

The OGC SensorThings API is a RESTful API that is based on the Odata protocol. For the public facing service, only GETs are supported. Major functions and endpoint of the API:

GET	Description
wyseason.uwyo.edu/sta/v1.1	Get index - provides an overview of the SensorThings response.
wyseason.uwyo.edu/sta/v1.1/Type	Get all of type - includes Locations, Things, Datastreams, ObservedProperties, or Observations.
wyseason.uwyo.edu/sta/v1.1/Type(id)	Get one of a type - requests information related to a specific entity type.
wyseason.uwyo.edu/sta/v1.1/Type(id)/Entity	Get linked entity- requests a list of information associated with a specific entity type.
wyseason.uwyo.edu/sta/v1.1/Type(id)/EntitySet	Get all linked - provides data associations between object types.

End Points

The table below explains the entities referenced throughout the API documentation.

Core Classes	Description
Things	A monitoring location.
Locations	The physical location of a Thing. It is possible for a Thing to move to a different location.
Datastreams	Connects an observation or set of observations to their Sensor, Observed Property, and Thing.
Sensors	A description of a sensor that provides values.
ObservedProperties	A description of what is being measured by a Sensor at a specific Location.
Observations	A single measurement value.
FeatureOfInterest	The object on which the measurement was performed. Autogenerated.
HistoricalLocation	The historical location of a Thing if it was moved.

Example Queries

GET Recent Water Temperature Observations

GETs all Datastreams that have water temp at 1 meter depth and return past two days of Observations:

Query :

        $expand=
            Observations($select=phenomenonTime,result,parameters;
                $filter=phenomenonTime gt now() sub duration'P2D';
                $orderby=phenomenonTime asc;
                $top=1000)

GET Me Everything

All Thing`, with their Location and Datastreams. For each Datastream, the Sensor, ObservedProperties, and two most recent Observations:

Query :

https://wyseason.uwyo.edu/sta/v1.1/Things?
    $expand=
        Locations($select=name,description,properties,location,@iot.id),
        Datastreams($select=name,description,@iot.id;
            $expand=
                Observations($select=result,phenomenonTime,parameters,resultQuality,@iot.id;
                    $orderby=phenomenonTime desc;
                    $top=2))

GET Me Everything on Jackson Lake

All Things, with their Location and Datastreams. For each Datastrea`, the sensor, ObservedProperty, and two most recent Observations, filtered by Locations that are tied to the Thing name LB00001 Jackson Lake:

Query :

https://wyseason.uwyo.edu/sta/v1.1/Things(3)?
    $expand=
        Locations($select=name,description,properties,location,@iot.id),
        Datastreams($select=name,description,@iot.id;
            $expand=
                Observations($select=result,phenomenonTime,parameters,resultQuality,@iot.id;
                    $orderby=phenomenonTime desc;
                     $top=2))

Overlapping Time Frames

The PhenomenonTime and result of the first 100 Observations of a Datastream, ordered by PhenomenonTime that overlap with the time frame from 2023-01-02 07:00:00 UTC to 2023-01-04 07:00:00 UTC (2 days):

Query :

https://wyseason.uwyo.edu/sta/v1.1/Datastreams(1)/Observations?
    $orderby=
        phenomenonTime asc
        &$top=100
        &$select=phenomenonTime, result
        &$filter=overlaps(phenomenonTime, 2023-10-01T01:00:00Z/2023-10-31T01:00:00Z)

The Previous Day

The Observations of a Datastream, for the last day:

Query :

https://wyseason.uwyo.edu/sta/v1.1/Datastreams(1)/Observations?
    $orderby=
        phenomenonTime asc
        &$filter=phenomenonTime gt now() sub duration'P1D'

Filters on Related Entities

Datastream` that have data for the ObservedProperty with id ‘4’ (Wind):

Query :

https://wyseason.uwyo.edu/sta/v1.1/Datastreams?
    $filter=ObservedProperty/@iot.id eq '4'

Additionally

ObservedProperties that are measured at the same station as the ObservedProperty with name Temperature:

Query :

https://wyseason.uwyo.edu/sta/v1.1/ObservedProperties?
    $filter=Datastreams/Thing/Datastreams/ObservedProperty/name

Ordering By Function

This function orders the Datastreams by the length of their name in descending order:

Query :

https://wyseason.uwyo.edu/sta/v1.1/Datastreams?
    $orderby=length(name) desc

Query Design Overview

The SensorThings API provides 8 entity types (12 with all extensions). All data can be reached from each entity type. To get Observations one could start:

directly from Observations
from Datastreams and expand Observations
from FeaturesOfInterest and expand Observations
from Things and expand Datastreams & Observations
from ObservedProperties and expand Datastreams & Observations
from Sensors and expand Datastreams & Observations
from Locations and expand Things, Datastreams & Observations

The following options can provide the same data but with different structures. All these options can provide same data but with a different structure.

Starting From Observations

The data is least structured when starting directly from /Observations. In this case each item in the resulting list is one Observation, but Observations for all Datastreams (Things/ObservedProperties) or FeaturesOfInterest are mixed together.

Individual timeseries for Datastreams are lost and it is up to the client to sort the data again. When expanding Datastreams and from there ObservedProperties or Things, the data for the Datastreams is repeated for each Observation. This result is very much like a CSV file, and quite inefficient.

The resulting data structure looks like this:

Observation + Datastream + ObservedProperty + Thing
Observation + Datastream + ObservedProperty + Thing
Observation + Datastream + ObservedProperty + Thing

It is not possible to get “the latest Observation for each …” since there is only one list, thus only one “latest Observation.”

Starting From Things

On the other side of the spectrum is starting from /Things. Each item in the resulting list will be a Thing, and for each Thing the Datastreams can be expanded, and for each of those the Observations.

Thing 1
- Datastream 1 + ObservedProperty 1
  - Observation 1
  - Observation 2
- Datastream 2 + ObservedProperty 2
  - Observation 3
  - Observation 4
Thing 2
- Datastream 3 + ObservedProperty 1
  - Observation 5
  - Observation 6
- Datastream 4 + ObservedProperty 2
  - Observation 7
  - Observation 8

There is some duplication in the ObservedProperties when fetching data in this way, but the structure is easy to put on a map. Because of the way that queries are structured, starting with a narrow data format will often lead to better performance.