[Tutorial] SensorThings API 101 - How to upload observation data to SensorThings API

Created by Steve Liang
Last updated: Nov 10, 2015
4 min read

This is a step-by-step tutorial regarding creating a Thing instance, the related entities with SensorThings API, and eventually upload sensor readings.

You can also download the Postman script here (download). (Note: Postman is a great tool for sharing and sending RESTful requests.)

 

If you haven't seen the OGC SensorThings UML diagram, it might be a very good idea to look at it first (link to UML).

 

Step-by-step guide

Step 1: CREATE a Thing entity instance as well as the Thing's Location. 

In this case, a weather station is modelled as a Thing in the SensorThings API data model.  The Icelandic Weather Office (example station) provides excellent data description and we can easily convert the table into the following SensorThings API JSON.

POST: URL_to_the_Server   (You can use SensorUp's sandbox server: http://chashuhotpot.sensorup.com/OGCSensorThings/v1.0) 

Header: Content Type: application/json

CREATE a Thing 
{
  "description": "Akureyri Weather Station, Icelandic Met Office",
  "properties": {
    "name": "Akureyri",
    "type": "manned synoptic station",
    "station number": "422",
    "wmo number": "4063",
    "abbreviation": "ak",
    "forecast region": "North East(na)",
    "height above sea-level": "23.0 a.s.l.",
    "beignning of weather observations": "1881",
    "station owned by": "Veðurstofa Íslands"
  },
  "Locations": [
    {
      "encodingType": "application/vnd.geo+json",
      "description": "Akureyri Weather Station, Icelandic Met Office",
      "location": {"coordinates":[-18.1002,65.6856],"type":"Point"}
    }
  ]
}

Step 2.a: CREATE an ObservedProperty instance (when the observed property doesn't existing in the system)

If no existing ObservedProperty, create an ObservedProperty entity instance by POST the following JSON to the server. An ObservedProperty describes what is the phenomenon a datastream is measuring. And once an ObservedProperty is created, it SHALL be reused by other Datastreams that measuring the same phenomenon. In this example, we use the definition from DBPedia. Note that different domain application might have different definition though.

Create a ObservedProperty instance 
{
  "name": "Temperature",
  "description": "A temperature is a numerical measure of hot and cold. Its measurement is by detection of heat radiation or particle velocity or kinetic energy, or by the bulk behavior of a thermometric material.",
  "definition": "http://dbpedia.org/page/Temperature"
}

Step 2.b: When the observed property already exists in the system.

When the ObservedProperty already exists in the system, Go To Step 3.

 

Is the ObservedProperty already in the system?

You can simply issue a request to URL/ObervedProperties to list all the existing ObservedProperties in the system (e.g., click here), and find the one you can use. Only create new ones if you cannot find an existing one.

 

Step 3.a: If no existing Sensor, CREATE a new Sensor. 

Similar to the previous step, if the Sensor doesn't already exist in the system, create a new instance by POST the following JSON request.  However, if the Sensor already exists, it should be re-used.

Create a Sensor entity instance 
{
  "encodingType": "http://schema.org/description",
  "metadata": "a temperature sensor used by a weather station.",
  "description": "a temperature sensor used by a weather station."
}

Differences between Sensor and Thing?

How a Thing different from a Sensor??

A Sensor is "an entity capable of observing a phenomenon and returning an observed value. Type of observation procedure that provides the estimated value of an observed property at its output. [OGC 12-000] ". For example, a Campbell weather station (e.g., road weather information station) can be modelled as a Thing, and multiple Sensors (examples) can be mounted on the station.

Step 3.b: If the Sensor already exists.

Go to Step 4.

Step 4: CREATE a new Datastream by linking to the newly created (or existing) Sensor and ObservedProperty

Create a Sensor entity instance 
{
  "unitOfMeasurement": {
    "name": "degree Celsius",
    "symbol": "°C",
    "definition": "http://dbpedia.org/page/Celsius"
  },
  "Thing": {
    "id": <id_of_the_Thing_you_just_created>
  },
  "description": "This is a datastream for measuring the background radiation.",
  "Sensor": {
    "id": <id_of_the_Sensor_you_just_created>
  },
  "ObservedProperty": {
    "id": <id_of_the_ObservedProperty_you_just_created>
  },
  "observationType": "http://www.opengis.net/def/observationType/OGCOM/2.0/OM_Measurement"
}

Step 5: If the FeatureOfInterest is different from the Thing Location, then either CREATE a new FeatureOfInterest or LINK to an existing one.

In this example, the FoI and the Thing's Location are the same, so we don't need to do anything.  Server will create the FoI automatically.

Step 6: CREATE new Observations

Finally, we have established all the required "metadata" for the observations. Now we can upload many many observations to the system.

Create an Observation entity instance 
{
  "result": "25.2",
  "Datastream": {
    "id": <id_of_the_Datastream_you_just_created>
  }
}

Step 7: Retrieve the uploaded Observations 

Finally, you can retrieve the Observations you just created by issuing a GET request to the server URL, like this: http://chashuhotpot.sensorup.com/OGCSensorThings/v1.0/Datastreams(453609)/Observations

BTW, feel free to ask questions by leaving comments below.  (smile)