Introduction

Welcome to API documentation for the Open Geospatial Consortium (OGC) SensorThings international standard. This API provides an open and unified way to interconnect Internet of Things (IoT) devices over the Web as well as interfaces to interact with and analyze their observations. Part 1:Sensing was released in 2016 and allowed management and reception of observations or measurements made by IoT sensors. Part 2: Tasking Core provides a mechanism to tell the sensor/actuator what to do.

The foundation of the SensorThings API are the relational connections between entities in the system and the way they are used to model systems in the real world. The entities have a natural relationship which enables any IoT sensing device from any vertical industry to be modelled in the system. An IoT device or system is modelled as a Thing. A Thing has a Location with one or more Datastreams. Each Datastream observes one ObservedProperty with one Sensor and has many Observations from the Sensor. Each Observation read by the Sensor observes one particular FeatureOfInterest. Together, these relationships provide a flexible standard way to describe and model any sensing system. It allows SensorThings to be a single data exchange system for heterogeneous devices within any organization.

This document provides guidance for a developer to perform basic Create-Read-Update-Delete (CRUD) operations as well as some sophisticated queries to retrieve data from the system. Some template examples for request bodies are provided for making requests to a SensorThings server.

OGC SensorThings API Part 1: Sensing OGC SensorThings API Part 2: Tasking (Draft)

SensorThings API - Sensing

The following diagram is the UML Data Model for OGC SensorThings API and defining different entities and their properties, together with the relationship between entities.

Sensor ObservedProperty Datastream Observation Thing Location HistoricalLocation FeatureOfInterest

SensorThings Base Resource Path

Access to all resources begins at the base resource path.

Navigating to the base resource path will return a JSON array of the available SensorThings resource endpoints.

[formpanel type=GET] [formtitle] /v1.0/ [/formtitle] [formbody]

[/formbody] [/formpanel]

Things

A Thing is an object of the physical world (physical Things) or the information world (virtual Things) that is capable of being identified and integrated into communication networks [ITU-T Y.2060].

Thing is a good starting point to start creating the SensorThings model structure. A Thing has Locations and one or more Datastreams to collect Observations. A minimal Thing can be created without a Location and Datastream and there are options to create a Things with a nested linked Location and Datastream.

POST

Property Required Type
name mandatory String
description mandatory String
properties optional JSON Object

Related entities that are required when creating a Thing:

Entity Required
Locations optional
HistoricalLocations optional
Datastreams optional

Example 1: POST

Create a Thing.

[tabpanel] [tabpage header=HTTP id=thingspost-example1-1]

{
  "name": "Temperature Monitoring System",
  "description": "Sensor system monitoring area temperature",
  "properties": {
    "Deployment Condition": "Deployed in a third floor balcony",
    "Case Used": "Radiation shield"
  }
}

[/tabpage] [tabpage header=JavaScript/jQuery id=thingspost-example1-2]

var json = JSON.stringify({
  "name": "Temperature Monitoring System",
  "description": "Sensor system monitoring area temperature",
  "properties": {
    "Deployment Condition": "Deployed in a third floor balcony",
    "Case Used": "Radiation shield"
  }
}
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things",
    type: "POST",
    data: json,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);  
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=thingspost-example1-3]

curl -XPOST -H "Content-type: application/json" -d '{
  "name": "Temperature Monitoring System",
  "description": "Sensor system monitoring area temperature",
  "properties": {
    "Deployment Condition": "Deployed in a third floor balcony",
    "Case Used": "Radiation shield"
  }
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things"

[/tabpage] [/tabpanel]

[formpanel type=POST] [formtitle] /v1.0/Things [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 2: POST with new Location

A Location entity can be linked to a Thing at its creation time. The Location provided will be a new Location in the system.

[tabpanel] [tabpage header=HTTP id=thingspost-example2-1]

{
  "name": "Temperature Monitoring System",
  "description": "Sensor system monitoring area temperature",
  "properties": {
    "Deployment Condition": "Deployed in a third floor balcony",
    "Case Used": "Radiation shield"
  },
  "Locations": [{
    "name": "UofC CCIT",
    "description": "University of Calgary, CCIT building",
    "encodingType": "application/vnd.geo+json",
    "location": {
      "type": "Point",
      "coordinates": [-114.133, 51.08]
    }
  }]
}

[/tabpage] [tabpage header=JavaScript/jQuery id=thingspost-example2-2]

var json = JSON.stringify({
  "name": "Temperature Monitoring System",
  "description": "Sensor system monitoring area temperature",
  "properties": {
    "Deployment Condition": "Deployed in a third floor balcony",
    "Case Used": "Radiation shield"
  },
  "Locations": [{
    "name": "UofC CCIT",
    "description": "University of Calgary, CCIT building",
    "encodingType": "application/vnd.geo+json",
    "location": {
      "type": "Point",
      "coordinates": [-114.133, 51.08]
    }
  }]
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things",
    type: "POST",
    data: json,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=thingspost-example2-3]

curl -X POST -H "Content-Type: application/json" -d '{
  "name": "Temperature Monitoring System",
  "description": "Sensor system monitoring area temperature",
  "properties": {
    "Deployment Condition": "Deployed in a third floor balcony",
    "Case Used": "Radiation shield"
  },
  "Locations": [{
    "name": "UofC CCIT",
    "description": "University of Calgary, CCIT building",
    "encodingType": "application/vnd.geo+json",
    "location": {
      "type": "Point",
      "coordinates": [-114.133, 51.08]
    }
  }]
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things"

[/tabpage] [/tabpanel]

[formpanel type=POST] [formtitle] /v1.0/Things [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 3: POST with existing Location

Create a Thing linked to the existing Location id.

When creating a new Thing, an existing Location entity can be linked at its creation time by providing the id of the Location.

[tabpanel] [tabpage header=HTTP id=thingspost-example3-1]

{
  "name": "Temperature Monitoring System",
  "description": "Sensor system monitoring area temperature",
  "properties": {
    "Deployment Condition": "Deployed in a third floor balcony",
    "Case Used": "Radiation shield"
  },
  "Locations": [
    {"@iot.id":1}
  ]
}

[/tabpage] [tabpage header=JavaScript/jQuery id=thingspost-example3-2]

var json = JSON.stringify({
  "name": "Temperature Monitoring System",
  "description": "Sensor system monitoring area temperature",
  "properties": {
    "Deployment Condition": "Deployed in a third floor balcony",
    "Case Used": "Radiation shield"
  },
  "Locations": [
    {"@iot.id":1}
  ]
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things",
    type: "POST",
    data: json,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=thingspost-example3-3]

curl -XPOST -H "Content-type: application/json" -d '{
  "name": "Temperature Monitoring System",
  "description": "Sensor system monitoring area temperature",
  "properties": {
    "Deployment Condition": "Deployed in a third floor balcony",
    "Case Used": "Radiation shield"
  },
  "Locations": [
    {"@iot.id":1}
  ]
}' 'https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things'

[/tabpage] [/tabpanel]

[formpanel type=POST] [formtitle] /v1.0/Things [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 4: POST with Location and Datastream

Create a Thing with an embedded Location and Datastream. A Thing can be created with linked entities when the complete JSON entity representation is in the request body.

[tabpanel] [tabpage header=HTTP id=thingspost-example4-1]

{
  "name": "Temperature Monitoring System",
  "description": "Sensor system monitoring area temperature",
  "properties": {
    "Deployment Condition": "Deployed in a third floor balcony",
    "Case Used": "Radiation shield"
  },
  "Locations": [{
    "name": "UofC CCIT",
    "description": "University of Calgary, CCIT building",
    "encodingType": "application/vnd.geo+json",
    "location": {
      "type": "Point",
      "coordinates": [-114.133, 51.08]
    }
  }],
  "Datastreams": [{
    "name": "Air Temperature DS",
    "description": "Datastream for recording temperature",
    "observationType": "http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement",
    "unitOfMeasurement": {
      "name": "Degree Celsius",
      "symbol": "degC",
      "definition": "http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#DegreeCelsius"
    },
    "ObservedProperty": {
      "name": "Area Temperature",
      "description": "The degree or intensity of heat present in the area",
      "definition": "http://www.qudt.org/qudt/owl/1.0.0/quantity/Instances.html#AreaTemperature"
    },
    "Sensor": {
      "name": "DHT22",
      "description": "DHT22 temperature sensor",
      "encodingType": "application/pdf",
      "metadata": "https://cdn-shop.adafruit.com/datasheets/DHT22.pdf"
    }
  }]
}

[/tabpage] [tabpage header=JavaScript/jQuery id=thingspost-example4-2]

var json = JSON.stringify({
  "name": "Temperature Monitoring System",
  "description": "Sensor system monitoring area temperature",
  "properties": {
    "Deployment Condition": "Deployed in a third floor balcony",
    "Case Used": "Radiation shield"
  },
  "Locations": [{
    "name": "UofC CCIT",
    "description": "University of Calgary, CCIT building",
    "encodingType": "application/vnd.geo+json",
    "location": {
      "type": "Point",
      "coordinates": [-114.133, 51.08]
    }
  }],
  "Datastreams": [{
    "name": "Air Temperature DS",
    "description": "Datastream for recording temperature",
    "observationType": "http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement",
    "unitOfMeasurement": {
      "name": "Degree Celsius",
      "symbol": "degC",
      "definition": "http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#DegreeCelsius"
    },
    "ObservedProperty": {
      "name": "Area Temperature",
      "description": "The degree or intensity of heat present in the area",
      "definition": "http://www.qudt.org/qudt/owl/1.0.0/quantity/Instances.html#AreaTemperature"
    },
    "Sensor": {
      "name": "DHT22",
      "description": "DHT22 temperature sensor",
      "encodingType": "application/pdf",
      "metadata": "https://cdn-shop.adafruit.com/datasheets/DHT22.pdf"
    }
  }]
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things",
    type: "POST",
    data: json,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=thingspost-example4-3]

curl -XPOST -H "Content-type: application/json" -d '{
  "name": "Temperature Monitoring System",
  "description": "Sensor system monitoring area temperature",
  "properties": {
    "Deployment Condition": "Deployed in a third floor balcony",
    "Case Used": "Radiation shield"
  },
  "Locations": [{
    "name": "UofC CCIT",
    "description": "University of Calgary, CCIT building",
    "encodingType": "application/vnd.geo+json",
    "location": {
      "type": "Point",
      "coordinates": [-114.133, 51.08]
    }
  }],
  "Datastreams": [{
    "name": "Air Temperature DS",
    "description": "Datastream for recording temperature",
    "observationType": "http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement",
    "unitOfMeasurement": {
      "name": "Degree Celsius",
      "symbol": "degC",
      "definition": "http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#DegreeCelsius"
    },
    "ObservedProperty": {
      "name": "Area Temperature",
      "description": "The degree or intensity of heat present in the area",
      "definition": "http://www.qudt.org/qudt/owl/1.0.0/quantity/Instances.html#AreaTemperature"
    },
    "Sensor": {
      "name": "DHT22",
      "description": "DHT22 temperature sensor",
      "encodingType": "application/pdf",
      "metadata": "https://cdn-shop.adafruit.com/datasheets/DHT22.pdf"
    }
  }]
}' 'https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things'

[/tabpage] [/tabpanel]

[formpanel type=POST] [formtitle] /v1.0/Things [/formtitle] [formbody]

[/formbody] [/formpanel]

GET

Example 1: GET

Retrieve all Things.

[tabpanel] [tabpage header=HTTP id=Things-get-1]

https://toronto-bike-snapshot.sensorup.com/v1.0/Things

[/tabpage] [tabpage header=JavaScript/jQuery id=Things-get-2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/Things",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=Things-get-3]

curl -X GET -H "Content-Type: application/json" "https://toronto-bike-snapshot.sensorup.com/v1.0/Things"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/Things [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 2: GET by id

Retrieve a specific Thing.

[formpanel type=GET] [formtitle] /v1.0/Things(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 3: GET with expand

Retrieve a Thing with inline related enities using $expand query option. Query options can be used on the entire collection of entities or on individual ones.

Related Entities for $expand Description
Locations Display inline details of Location for Things
Datastreams Display inline details of Datastreams for Things
HistoricalLocations Display inline details of HistoricalLocation for Things

[formpanel type=GET] [formtitle] /v1.0/Things(id)?$expand=Datastreams [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 4: GET with select

Retrieve specified properties for a specific Thing.

Properties for $select Description
name A property provides a label for Thing entity, commonly a descriptive name.
description The description of the Thing
properties The properties Object of the Thing
Locations The navigationLink to the Locations of this Thing.
Datastreams The navigationLink to the Datastreams of this Thing.
HistoricalLocations The navigationLink to the HistoricalLocations of this Thing.

[formpanel type=GET] [formtitle] /v1.0/Things(id)?$select=description [/formtitle] [formbody]

[/formbody] [/formpanel]

PATCH

Update a specific Thing with new property values.

[tabpanel] [tabpage header=HTTP id=things-patch-1]

{
  "description": "WiFi Water Temperature System",
  "properties": {
    "detail": "3 ft water sealed, external temperature probe.",
    "WiFi-range": "Up to 250 ft.* (Typical to standard WiFi devices)"
  },
  "Locations": [
    {"@iot.id":1}
  ]
}

[/tabpage] [tabpage header=JavaScript/jQuery id=things-patch-2]

var patchJson = JSON.stringify({
  "description": "WiFi Water Temperature System",
  "properties": {
    "detail": "3 ft water sealed, external temperature probe.",
    "WiFi-range": "Up to 250 ft.* (Typical to standard WiFi devices)"
  },
  "Locations": [
    {"@iot.id":1}
  ]
});

$.ajax({
  url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things(2)",
  type: "PATCH",
  data: patchJson,
  contentType: "application/json; charset=utf-8",
  success: function(data){
    console.log(data);

  },
  error: function(response, status){
    console.log(response);
    console.log(status);
  }
});

[/tabpage] [tabpage header=cURL id=things-patch-3]

curl -X PATCH -H "Content-Type: application/json" -d '{
  "description": "WiFi Water Temperature System",
  "properties": {
    "detail": "3 ft water sealed, external temperature probe.",
    "WiFi-range": "Up to 250 ft.* (Typical to standard WiFi devices)"
  },
  "Locations": [
    {"@iot.id":1}
  ]
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things(2)"

[/tabpage] [/tabpanel]

[formpanel type=PATCH] [formtitle] /v1.0/Things(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

DELETE

To delete a Thing. [tabpanel] [tabpage header=HTTP id=Things-delete-1]

https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things(id)

[/tabpage] [tabpage header=JavaScript/jQuery id=Things-delete-2]

$.ajax({
  url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things(id)",
  type: "DELETE",
  contentType: "application/json; charset=utf-8",
  success: function(data){
    console.log(data);
  },
  error: function(response, status){
    console.log(response);
    console.log(status);
  }
});

[/tabpage] [tabpage header=cURL id=Things-delete-3]

curl -X DELETE -H "Content-Type: application/json" -H -d '' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things(id)"

[/tabpage] [/tabpanel]

[formpanel type=DELETE] [formtitle] /v1.0/Things(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

Locations

The Location entity locates the Thing(s) it associated with. A Thing’s Location entity is defined as the last known location of the Thing. A Thing can have multiple Locations if all Locations are different representations of same Location with different encodingType.

POST

Property Required Type
name mandatory String
description mandatory String
encodingType mandatory ValueCode
location mandatory Any (Depends on encodingType)

Related entities that are required when creating a Location:

Entity Required
Things optional
HistoricalLocations optional

Example 1: POST

Create a Location.

[tabpanel] [tabpage header=HTTP id=Locaitons-post-1]

{
  "name": "UofC CCIT",
  "description": "University of Calgary, CCIT building",
  "encodingType": "application/vnd.geo+json",
  "location": {
    "type": "Point",
    "coordinates": [-114.133, 51.08]
  }
}

[/tabpage] [tabpage header=JavaScript/jQuery id=Locaitons-post-2]

var location = JSON.stringify({
  "name": "UofC CCIT",
  "description": "University of Calgary, CCIT building",
  "encodingType": "application/vnd.geo+json",
  "location": {
    "type": "Point",
    "coordinates": [-114.133, 51.08]
  }
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Locations",
    type: "POST",
    data: location,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=Locaitons-post-3]

curl -XPOST -H "Content-type: application/json" -d '{
  "name": "UofC CCIT",
  "description": "University of Calgary, CCIT building",
  "encodingType": "application/vnd.geo+json",
  "location": {
    "type": "Point",
    "coordinates": [-114.133, 51.08]
  }
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Locations"

[/tabpage] [/tabpanel]

[formpanel type=POST] [formtitle] /v1.0/Locations [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 2: POST with existing Thing

Create a Location linked to an existing Thing.

[tabpanel] [tabpage header=HTTP id=Locaitons-post2-1]

{
  "name": "UofC CCIT",
  "description": "University of Calgary, CCIT building",
  "encodingType": "application/vnd.geo+json",
  "location": {
    "type": "Point",
    "coordinates": [-114.133, 51.08]
  }
}

[/tabpage] [tabpage header=JavaScript/jQuery id=Locaitons-post2-2]

var location = JSON.stringify({
  "name": "UofC CCIT",
  "description": "University of Calgary, CCIT building",
  "encodingType": "application/vnd.geo+json",
  "location": {
    "type": "Point",
    "coordinates": [-114.133, 51.08]
  }
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things(705831)/Locations",
    type: "POST",
    data: location,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=Locaitons-post2-3]

curl -XPOST -H "Content-type: application/json" -d '{
  "name": "UofC CCIT",
  "description": "University of Calgary, CCIT building",
  "encodingType": "application/vnd.geo+json",
  "location": {
    "type": "Point",
    "coordinates": [-114.133, 51.08]
  }
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things(705831)/Locations"

[/tabpage] [/tabpanel]

[formpanel type=POST] [formtitle] /v1.0/Things(id)/Locations [/formtitle] [formbody]

[/formbody] [/formpanel]

GET

Example 1: GET

Retrieve all Locations.

[tabpanel] [tabpage header=HTTP id=Locaitons-get-tab1-1]

https://toronto-bike-snapshot.sensorup.com/v1.0/Locations

[/tabpage] [tabpage header=JavaScript/jQuery id=Locaitons-get-tab1-2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/Locations",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=Locaitons-get-tab1-3]

curl -X GET -H "Content-Type: application/json" "https://toronto-bike-snapshot.sensorup.com/v1.0/Locations"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/Locations [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 2: GET by id

Retrieve a specific Location.

[formpanel type=GET] [formtitle] /v1.0/Locations(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 3: GET by Thing id

Retrieve Locations of a specific Thing

[formpanel type=GET] [formtitle] /v1.0/Things(id)/Locations [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 4: GET with expand

Retrieve a specific Location with inline related entities information using $expand query option.

Related Entities for $expand Description
Things Display inline details of Things for Locations
HistoricalLocations Display inline details of HistoricalLocations for Locations

[formpanel type=GET] [formtitle] /v1.0/Locations(id)?$expand=Things [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 5: GET with filter - spatial query

Retrieve all Locations within a provided Polygon and expand the Thing entities to retrieve their metadata.

[formpanel type=GET] [formtitle] /v1.0/Locations?$expand=Things&$filter=st_within(location, geography’POLYGON ((-79.39 43.651,-79.371 43.651,-79.371 43.641,-79.39 43.641,-79.39 43.651))’) [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 6: GET with select

Retrieve specified properties for a specific Location.

Properties for $select Description
name A property provides a label for Location entity, commonly a descriptive name.
description A description about this Location.
encodingType The encoding type of this Location. This is a value code enumeration.
location A location as defined by the encodingType.
Thing The navigationLink to the Thing related to this Location.
HistoricalLocations The navigationLink to the HistoricalLocations related to this Location.

[formpanel type=GET] [formtitle] /v1.0/Locations(id)?$select=description [/formtitle] [formbody]

[/formbody] [/formpanel]

PATCH

Update a Location with new values for its properties.

[tabpanel] [tabpage header=HTTP id=Location-patch-1]

{
  "name": "Edworthy Park Area",
  "location": {
    "type": "Point",
    "coordinates": [-114.154,51.064]
  }
}

[/tabpage] [tabpage header=JavaScript/jQuery id=Location-patch-2]

var patchJson = JSON.stringify({
  "name": "Edworthy Park Area",
  "location": {
    "type": "Point",
    "coordinates": [-114.154,51.064]
  }
});

$.ajax({
  url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Location(1)",
  type: "PATCH",
  data: patchJson,
  contentType: "application/json; charset=utf-8",
  success: function(data){
    console.log(data);

  },
  error: function(response, status){
    console.log(response);
    console.log(status);
  }
});

[/tabpage] [tabpage header=cURL id=Location-patch-3]

curl -X PATCH -H "Content-Type: application/json" -d '{
  "name": "Edworthy Park Area",
  "location": {
    "type": "Point",
    "coordinates": [-114.154,51.064]
  }
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Location(2)"

[/tabpage] [/tabpanel]

[formpanel type=PATCH] [formtitle] /v1.0/Locations(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

DELETE

Delete a Location.

[tabpanel] [tabpage header=HTTP id=Locations-delete-1]

https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Locations(id)

[/tabpage] [tabpage header=JavaScript/jQuery id=Locations-delete-2]

$.ajax({
  url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Locations(id)",
  type: "DELETE",
  contentType: "application/json; charset=utf-8",
  success: function(data){
    console.log(data);
  },
  error: function(response, status){
    console.log(response);
    console.log(status);
  }
});

[/tabpage] [tabpage header=cURL id=Locations-delete-3]

curl -X DELETE -H "Content-Type: application/json" -H -d '' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Locations(id)"

[/tabpage] [/tabpanel]

[formpanel type=DELETE] [formtitle] /v1.0/Locations(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

HistoricalLocations

A Thing’s HistoricalLocation entity set provides the times of the current (i.e., last known) and previous locations of the Thing.

GET

Exmaple 1: GET

Retrieve all HistoricalLocations.

[tabpanel] [tabpage header=HTTP id=HistoricalLocations-get-tab-1]

https://toronto-bike-snapshot.sensorup.com/v1.0/HistoricalLocations

[/tabpage] [tabpage header=JavaScript/jQuery id=HistoricalLocations-get-tab-2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/HistoricalLocations",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=HistoricalLocations-get-tab-3]

curl -X GET -H "Content-Type: application/json" "https://toronto-bike-snapshot.sensorup.com/v1.0/HistoricalLocations"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/HistoricalLocations [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 2: GET by id

Retrieve a specific historical location.

[formpanel type=GET] [formtitle] /v1.0/HistoricalLocations(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 3: GET with expand

Retrieve a specific HistoricalLocation with inline related entities information using $expand query option.

Related Entities for $expand Description
Locations Display inline details of Location for HistoricalLocations
Thing Display inline details of Thing for HistoricalLocations

[formpanel type=GET] [formtitle] /v1.0/HistoricalLocations(id)?$expand=Locations [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 4: GET with select

Retrieve specified properties for a specific HistoricalLocation.

Properties for $select Description
time The time of the HistoricalLocation
Locations The navigationLink to the Locations of this HistoricalLocation
Thing The navigationLink to the Thing of this HistoricalLocation

[formpanel type=GET] [formtitle] /v1.0/HistoricalLocations(id)?$select=time [/formtitle] [formbody]

[/formbody] [/formpanel]

PATCH

Update a HistoricalLocation entity with new values for its properties.

[tabpanel] [tabpage header=HTTP id=HistoricalLocation-patch-tab-1]

{
  "time": "2015-02-07T19:22:11.297Z"
}

[/tabpage] [tabpage header=JavaScript/jQuery id=HistoricalLocation-patch-tab-2]

var patchJson = JSON.stringify({
  "time": "2015-02-07T19:22:11.297Z"
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/HistoricalLocations(id)",
    type: "PATCH",
    data: patchJson,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);

    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=HistoricalLocation-patch-tab-3]

curl -X PATCH -H "Content-Type: application/json" -d '{
  "time": "2015-02-07T19:22:11.297Z"
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/HistoricalLocations(id)"

[/tabpage] [/tabpanel]

[formpanel type=PATCH] [formtitle] /v1.0/HistoricalLocations(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

DELETE

Delete a HistoricalLocation.

[tabpanel] [tabpage header=HTTP id=HistoricalLocation-delete-tab-1]

https://scratchpad.sensorup.com/OGCSensorThings/v1.0/HistoricalLocation(id)

[/tabpage] [tabpage header=JavaScript/jQuery id=HistoricalLocation-delete-tab-2]

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/HistoricalLocations(id)",
    type: "DELETE",
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=HistoricalLocation-delete-tab-3]

curl -X DELETE -H "Content-Type: application/json" -H -d '' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/HistoricalLocations(id)"

[/tabpage] [/tabpanel]

[formpanel type=DELETE] [formtitle] /v1.0/HistoricalLocations(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

Datastreams

A Datastream groups a collection of Observations measuring the same ObservedProperty and produced by the same Sensor.

POST

Property Required Type
name mandatory String
description mandatory String
unitOfMeasurement mandatory JSON Object
observationType mandatory ValueCode
observedArea optional GeoJSON Polygon Object
phenomenonTime optional Time Interval (ISO 8601)
resultTime optional Time Interval (ISO 8601)

Related entities that are required when creating an Datastream:

Entity Required
Thing mandatory
ObservedProperty mandatory
Sensor mandatory
Observations optional

Example 1: POST

Create a Datastream.

[tabpanel] [tabpage header=HTTP id=datastream-post-tab-1]

{
  "name": "Air Temperature DS",
  "description": "Datastream for recording temperature",
  "observationType": "http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement",
  "unitOfMeasurement": {
    "name": "Degree Celsius",
    "symbol": "degC",
    "definition": "http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#DegreeCelsius"
  },
  "Thing":{"@iot.id":2},
  "ObservedProperty":{"@iot.id":7},
  "Sensor":{"@iot.id":6}
}

[/tabpage] [tabpage header=JavaScript/jQuery id=datastream-post-tab-2]

var json = JSON.stringify({
  "name": "Air Temperature DS",
  "description": "Datastream for recording temperature",
  "observationType": "http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement",
  "unitOfMeasurement": {
    "name": "Degree Celsius",
    "symbol": "degC",
    "definition": "http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#DegreeCelsius"
  },
  "Thing":{"@iot.id":2},
  "ObservedProperty":{"@iot.id":7},
  "Sensor":{"@iot.id":6}
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Datastreams",
    type: "POST",
    data: json,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=datastream-post-tab-3]

curl -X POST -H "Content-Type: application/json" -d '{
  "name": "Air Temperature DS",
  "description": "Datastream for recording temperature",
  "observationType": "http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement",
  "unitOfMeasurement": {
    "name": "Degree Celsius",
    "symbol": "degC",
    "definition": "http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#DegreeCelsius"
  },
  "Thing":{"@iot.id":2},
  "ObservedProperty":{"@iot.id":7},
  "Sensor":{"@iot.id":6}
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Datastreams"

[/tabpage] [/tabpanel]

[formpanel type=POST] [formtitle] /v1.0/Datastreams [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 2: POST with a Thing

Create a Datastream and link it to a Thing.

[tabpanel] [tabpage header=HTTP id=datastream-post-2-tab-1]

{
  "name": "Air Temperature DS",
  "description": "Datastream for recording temperature",
  "observationType": "http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement",
  "unitOfMeasurement": {
    "name": "Degree Celsius",
    "symbol": "degC",
    "definition": "http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#DegreeCelsius"
  },
  "ObservedProperty": {
    "name": "Area Temperature",
    "description": "The degree or intensity of heat present in the area",
    "definition": "http://www.qudt.org/qudt/owl/1.0.0/quantity/Instances.html#AreaTemperature"
  },
  "Sensor": {
    "name": "DHT22",
    "description": "DHT22 temperature sensor",
    "encodingType": "application/pdf",
    "metadata": "https://cdn-shop.adafruit.com/datasheets/DHT22.pdf"
  }
}

[/tabpage] [tabpage header=JavaScript/jQuery id=datastream-post-2-tab-2]

var json = JSON.stringify({
  "name": "Air Temperature DS",
  "description": "Datastream for recording temperature",
  "observationType": "http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement",
  "unitOfMeasurement": {
    "name": "Degree Celsius",
    "symbol": "degC",
    "definition": "http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#DegreeCelsius"
  },
  "ObservedProperty": {
    "name": "Area Temperature",
    "description": "The degree or intensity of heat present in the area",
    "definition": "http://www.qudt.org/qudt/owl/1.0.0/quantity/Instances.html#AreaTemperature"
  },
  "Sensor": {
    "name": "DHT22",
    "description": "DHT22 temperature sensor",
    "encodingType": "application/pdf",
    "metadata": "https://cdn-shop.adafruit.com/datasheets/DHT22.pdf"
  }
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Datastreams",
    type: "POST",
    data: json,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=datastream-post-2-tab-3]

curl -X POST -H "Content-Type: application/json" -d '{
  "name": "Air Temperature DS",
  "description": "Datastream for recording temperature",
  "observationType": "http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement",
  "unitOfMeasurement": {
    "name": "Degree Celsius",
    "symbol": "degC",
    "definition": "http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#DegreeCelsius"
  },
  "ObservedProperty": {
    "name": "Area Temperature",
    "description": "The degree or intensity of heat present in the area",
    "definition": "http://www.qudt.org/qudt/owl/1.0.0/quantity/Instances.html#AreaTemperature"
  },
  "Sensor": {
    "name": "DHT22",
    "description": "DHT22 temperature sensor",
    "encodingType": "application/pdf",
    "metadata": "https://cdn-shop.adafruit.com/datasheets/DHT22.pdf"
  }
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Datastreams"

[/tabpage] [/tabpanel]

[formpanel type=POST] [formtitle] /v1.0/Things(id)/Datastreams [/formtitle] [formbody]

[/formbody] [/formpanel]

GET

Example 1: GET

Retrieve all the Datastreams.

[tabpanel] [tabpage header=HTTP id=Datastreams-get-tab-1-1]

https://toronto-bike-snapshot.sensorup.com/v1.0/Datastreams

[/tabpage] [tabpage header=JavaScript/jQuery id=Datastreams-get-tab-1-2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/Datastreams",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=Datastreams-get-tab-1-3]

curl -X GET -H "Content-Type: application/json" "https://toronto-bike-snapshot.sensorup.com/v1.0/Datastreams"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/Datastreams [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 2: GET by id

Retrieve a specific Datastream.

[formpanel type=GET] [formtitle] /v1.0/Datastreams(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 3: GET by Things id

Retrieve Datastreams of a specific Thing.

[formpanel type=GET] [formtitle] /v1.0/Things(id)/Datastreams [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 4: GET with expand

Retrieve a specific Datastream with inline related entities information using $expand query option.

Related Entities for $expand Description
Thing Display inline details of the Thing for Datastreams
Sensor Display inline details of The Sensor for Datastreams
ObservedProperty Display inline details of the ObservedProperty for Datastreams
Observations Display inline details of Observations for Datastreams

[formpanel type=GET] [formtitle] /v1.0/Datastreams(id)?$expand=Observations,ObservedProperty [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 5: GET with select

Retrieve specified properties for a specific Datastream.

Properties for $select Description
name A property provides a label for Datastream entity, commonly a descriptive name.
description A description about this Datastream.
unitOfMeasurement The JSON Object representing the Unit Of Measurement of the readings from the Sensor.
observationType The type of Observation (with unique result type), which is used by the service to encode observations.
observedArea The spatial bounding box of the spatial extent of all FeaturesOfInterest that belong to the Observations associated with this Datastream.
phenomenonTime The temporal interval of the phenomenon times of all observations belonging to this Datastream.
resultTime The temporal interval of the result times of all observations belonging to this Datastream.
Thing The navigationLink to the Thing of this Datastream.
Sensor The navigationLink to the Sensor of this Datastream.
ObservedProperty The navigationLink to the ObservedProperty of this Datastream.
Observations The navigationLink to the Observations of this Datastream.

[formpanel type=GET] [formtitle] /v1.0/Datastreams(id)?$select=description,unitOfMeasurement [/formtitle] [formbody]

[/formbody] [/formpanel]

PATCH

Patch a Datastream with new values.

[tabpanel] [tabpage header=HTTP id=datastream-patch-tab-1]

{
  "unitOfMeasurement": {
    "name": "Degrees Fahrenheit",
    "symbol": "degF",
    "definition": "http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#DegreeFahrenheit"
  },
  "description": "Water Temperature of Bow river"
}

[/tabpage] [tabpage header=JavaScript/jQuery id=datastream-patch-tab-2]

var patchJson = JSON.stringify({
  "unitOfMeasurement": {
    "name": "Degrees Fahrenheit",
    "symbol": "degF",
    "definition": "http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#DegreeFahrenheit"
  },
  "description": "Water Temperature of Bow river"
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Datastreams(id)",
    type: "PATCH",
    data: patchJson,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);

    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=datastream-patch-tab-3]

curl -X PATCH -H "Content-Type: application/json" -d '{
  "unitOfMeasurement": {
    "name": "Degrees Fahrenheit",
    "symbol": "degF",
    "definition": "http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#DegreeFahrenheit"
  },
  "description": "Water Temperature of Bow river"
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Datastreams(id)"

[/tabpage] [/tabpanel]

[formpanel type=PATCH] [formtitle] /v1.0/Datastreams(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

DELETE

Delete a Datastream.

[tabpanel] [tabpage header=HTTP id=datastream-delete-tab-1]

https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Datastream(id)

[/tabpage] [tabpage header=JavaScript/jQuery id=datastream-delete-tab-2]

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Datastreams(id)",
    type: "DELETE",
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=datastream-delete-tab-3]

curl -X DELETE -H "Content-Type: application/json" -H -d '' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Datastreams(id)"

[/tabpage] [/tabpanel]

[formpanel type=DELETE] [formtitle] /v1.0/Datastreams(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

Sensors

A Sensor in SensorThings API is an instrument that observes a property or phenomenon with the goal of producing an estimate of the value of the property.

POST

Property Required Type
name mandatory String
description mandatory String
encodingType mandatory ValueCode
metadata mandatory Any (depending on the value of the encodingType)

Example 1: POST

Create a Sensor.

[tabpanel] [tabpage header=HTTP id=sensor-post-tab-1]

{
  "name": "DHT22",
  "description": "DHT22 temperature sensor",
  "encodingType": "application/pdf",
  "metadata": "https://cdn-shop.adafruit.com/datasheets/DHT22.pdf"
}

[/tabpage] [tabpage header=JavaScript/jQuery id=sensor-post-tab-2]

var json = JSON.stringify({
  "name": "DHT22",
  "description": "DHT22 temperature sensor",
  "encodingType": "application/pdf",
  "metadata": "https://cdn-shop.adafruit.com/datasheets/DHT22.pdf"
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Sensors",
    type: "POST",
    data: json,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        //To access a data field
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=sensor-post-tab-3]

curl -X POST -H "Content-Type: application/json" -d '{
  "name": "DHT22",
  "description": "DHT22 temperature sensor",
  "encodingType": "application/pdf",
  "metadata": "https://cdn-shop.adafruit.com/datasheets/DHT22.pdf"
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Sensors"

[/tabpage] [/tabpanel]

[formpanel type=POST] [formtitle] /v1.0/Sensors [/formtitle] [formbody]

[/formbody] [/formpanel]

GET

Example 1: GET

Retrieve all Sensors.

[tabpanel] [tabpage header=HTTP id=Sensors-get-tab-1-1]

https://toronto-bike-snapshot.sensorup.com/v1.0/Sensors

[/tabpage] [tabpage header=JavaScript/jQuery id=Sensors-get-tab-1-2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/Sensors",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=Sensors-get-tab-1-3]

curl -X GET -H "Content-Type: application/json" "https://toronto-bike-snapshot.sensorup.com/v1.0/Sensors"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/Sensors [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 2: Get by id

Retrieve a specific Sensor.

[formpanel type=GET] [formtitle] /v1.0/Sensors(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 3: GET with expand

Retrieve a Sensor with inline related enities using $expand query option. Query options can be used on the entire collection of entities or on individual ones.

Related Entities for $expand Description
Datastreams Display inline details of Datastreams for Sensors

[formpanel type=GET] [formtitle] /v1.0/Sensors(id)?$expand=Datastreams [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 4: GET with select

Retrieve specified properties for a specific Sensor.

Properties for $select Description
name A property provides a label for Sensor entity, commonly a descriptive name.
description The description of the Sensor entity.
encodingType The encoding type of the metadata property.
metadata The detailed description of the Sensor or system. The metadata type is defined by encodingType.
Datastreams The navigationLink to the Datastreams of this Sensor.

[formpanel type=GET] [formtitle] /v1.0/Sensors(id)?$select=description [/formtitle] [formbody]

[/formbody] [/formpanel]

PATCH

Update a Sensor with new values for its properties.

[tabpanel] [tabpage header=HTTP id=Sensors-patch-tab-1]

{
  "description": "DHT22 Temperature and Humidity sensor"
}

[/tabpage] [tabpage header=JavaScript/jQuery id=Sensors-patch-tab-2]

var patchJson = JSON.stringify({
  "description": "DHT22 Temperature and Humidity sensor"
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Sensors(id)",
    type: "PATCH",
    data: patchJson,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);

    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=Sensors-patch-tab-3]

curl -X PATCH -H "Content-Type: application/json" -d '{
  "description": "DHT22 Temperature and Humidity sensor"
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Sensors(id)"

[/tabpage] [/tabpanel]

[formpanel type=PATCH] [formtitle] /v1.0/Sensors(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

DELETE

Delete a Sensor.

[tabpanel] [tabpage header=HTTP id=Sensors-delete-tab-1]

https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Sensors(id)

[/tabpage] [tabpage header=JavaScript/jQuery id=Sensors-delete-tab-2]

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Sensors(id)",
    type: "DELETE",
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=Sensors-delete-tab-3]

curl -X DELETE -H "Content-Type: application/json" -H -d '' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Sensors(id)"

[/tabpage] [/tabpanel]

[formpanel type=DELETE] [formtitle] /v1.0/Sensors(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

ObservedProperties

An ObservedProperty specifies the phenomenon of an Observation.

POST

Property Required Type
name mandatory String
definition mandatory URI
description mandatory String

Example 1: POST

Create an ObservedProperty.

[tabpanel] [tabpage header=HTTP id=ObservedProperties-post-tab-1]

{
  "name": "Area Temperature",
  "description": "The degree or intensity of heat present in the area",
  "definition": "http://www.qudt.org/qudt/owl/1.0.0/quantity/Instances.html#AreaTemperature"
}

[/tabpage] [tabpage header=JavaScript/jQuery id=ObservedProperties-post-tab-2]

var json = JSON.stringify({
  "name": "Area Temperature",
  "description": "The degree or intensity of heat present in the area",
  "definition": "http://www.qudt.org/qudt/owl/1.0.0/quantity/Instances.html#AreaTemperature"
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/ObservedProperties",
    type: "POST",
    data: json,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=ObservedProperties-post-tab-3]

curl -X POST -H "Content-Type: application/json" -d '{
  "name": "Area Temperature",
  "description": "The degree or intensity of heat present in the area",
  "definition": "http://www.qudt.org/qudt/owl/1.0.0/quantity/Instances.html#AreaTemperature"
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/ObservedProperties"

[/tabpage] [/tabpanel]

[formpanel type=POST] [formtitle] /v1.0/ObservedProperties [/formtitle] [formbody]

[/formbody] [/formpanel]

GET

Example 1: GET

Retrieve all ObservedProperties.

[tabpanel] [tabpage header=HTTP id=ObservedProperties-get-tab-1-1]

https://toronto-bike-snapshot.sensorup.com/v1.0/ObservedProperties

[/tabpage] [tabpage header=JavaScript/jQuery id=ObservedProperties-get-tab-1-2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/ObservedProperties",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=ObservedProperties-get-tab-1-3]

curl -X GET -H "Content-Type: application/json" "https://toronto-bike-snapshot.sensorup.com/v1.0/ObservedProperties"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/ObservedProperties [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 2: GET by id

Retrieve a specific ObservedProperty.

[formpanel type=GET] [formtitle] /v1.0/ObservedProperties(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 3: GET by Datastream id

Retrieve the ObservedProperty of a specific Datastream. [formpanel type=GET] [formtitle] /v1.0/Datastream(id)/ObservedProperty [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 4: GET with expand

Retrieve an ObservedProperty with inline related enities using $expand query option.

Related Entities for $expand Description
Datastreams Display inline details of Datastreams for ObservedProperties.

[formpanel type=GET] [formtitle] /v1.0/ObservedProperties(id)?$expand=Datastreams [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 5: GET with select

Retrieve specified properties for a specific ObservedProperty.

Properties for $select Description
name A property provides a label for ObservedProperty entity, commonly a descriptive name.
definition The URI of the ObservedProperty definition. Dereferencing this URI results in a representation of the definition of the ObservedProperty.
description A description about the ObservedProperty.
Datastreams The navigationLink to the Datastreams of this ObservedProperty.

[formpanel type=GET] [formtitle] /ObservedProperties(id)?$select=description [/formtitle] [formbody]

[/formbody] [/formpanel]

PATCH

Update an ObservedProperty with new values for its properties.

[tabpanel] [tabpage header=HTTP id=ObservedProperties-patch-tab-1]

{
  "name": "Water Temperature"
}

[/tabpage] [tabpage header=JavaScript/jQuery id=ObservedProperties-patch-tab-2]

var patchJson = JSON.stringify({
  "name": "Water Temperature"
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/ObservedProperties(id)",
    type: "PATCH",
    data: patchJson,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);

    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=ObservedProperties-patch-tab-3]

curl -X PATCH -H "Content-Type: application/json" -d '{
  "name": "Water Temperature"
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/ObservedProperties(id)"

[/tabpage] [/tabpanel]

[formpanel type=PATCH] [formtitle] /v1.0/ObservedProperties(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

DELETE

Delete an ObservedProperty.

[tabpanel] [tabpage header=HTTP id=ObservedProperties-delete-tab-1]

https://scratchpad.sensorup.com/OGCSensorThings/v1.0/ObservedProperties(id)

[/tabpage] [tabpage header=JavaScript/jQuery id=ObservedProperties-delete-tab-2]

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/ObservedProperties(id)",
    type: "DELETE",
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=ObservedProperties-delete-tab-3]

curl -X DELETE -H "Content-Type: application/json" -H -d '' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/ObservedProperties(id)"

[/tabpage] [/tabpanel]

[formpanel type=DELETE] [formtitle] /v1.0/ObservedProperties(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

Observations

An Observation is the act of measuring or otherwise determining the value of a property. An Observation in SensorThings represents a single Sensor reading of an ObservedProperty. A physical device, a Sensor, sends Observations to a specified Datastream. An Observation requires a FeatureOfInterest entity, if none is provided in the request, the Location of the Thing associated with the Datastream, will be assigned to the new Observation as the FeatureOfInterest.

POST

Property Required Type
phenomenonTime mandatory Time(Interval) String (ISO 8601)
result mandatory Any (depends on the observationType defined in the associated Datastream)
resultTime mandatory Time(Interval) String (ISO 8601)
resultQuality optional DQ_Element
validTime optional Time Interval String (ISO 8601)
parameters optional JSON Object

Related entities that are required when creating a Observation:

Entity Required
Datastream mandatory
FeatureOfInterest mandatory (If it is not provided it will be automatically created based on the Location of associated Thing)

Example 1: POST

Create an Observation. [tabpanel] [tabpage header=HTTP id=Observations-post-tab-1]

{
  "phenomenonTime": "2017-02-07T18:02:00.000Z",
  "resultTime" : "2017-02-07T18:02:05.000Z",
  "result" : 21.6,
  "Datastream":{"@iot.id":8}
}

[/tabpage] [tabpage header=JavaScript/jQuery id=Observations-post-tab-2]

var json = JSON.stringify({
  "phenomenonTime": "2017-02-07T18:02:00.000Z",
  "resultTime" : "2017-02-07T18:02:05.000Z",
  "result" : 21.6,
  "Datastream":{"@iot.id":8}
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Observations",
    type: "POST",
    data: json,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=Observations-post-tab-3]

curl -X POST -H "Content-Type: application/json" -d '{
  "phenomenonTime": "2017-02-07T18:02:00.000Z",
  "resultTime" : "2017-02-07T18:02:05.000Z",
  "result" : 21.6,
  "Datastream":{"@iot.id":8}
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Observations"

[/tabpage] [/tabpanel]

[formpanel type=POST] [formtitle] /v1.0/Observations [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 2: POST with FeatureOfInterest

Create an Observation with inline FeatureOfInterest.

[formpanel type=POST] [formtitle] /v1.0/Observations [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 3: POST with Datastream

Create an Observation and link it to an existing Datastream.

[formpanel type=POST] [formtitle] /v1.0/Datastreams(id)/Observations [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 4: POST with Datastream and FeatureOfInterest

Create an Observation and link it to an existing Datastream and FeatureOfInterest.

[formpanel type=POST] [formtitle] /v1.0/Datastreams(id)/Observations [/formtitle] [formbody]

[/formbody] [/formpanel]

GET

Example 1: GET

Retrieve all Observations.

[tabpanel] [tabpage header=HTTP id=Observations-get-tab-1-1]

https://toronto-bike-snapshot.sensorup.com/v1.0/Observations

[/tabpage] [tabpage header=JavaScript/jQuery id=Observations-get-tab-1-2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/Observations",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=Observations-get-tab-1-3]

curl -X GET -H "Content-Type: application/json" "https://toronto-bike-snapshot.sensorup.com/v1.0/Observations"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/Observations [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 2: GET by Observation id

Retrieve a specific Observation.

[formpanel type=GET] [formtitle] /v1.0/Observations(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 3: GET by Datastream id

Retrieve Observations for a specific Datastream.

[formpanel type=GET] [formtitle] /v1.0/Datastreams(id)/Observations [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 4: GET with expand

Retrieve an Observation with inline related enities using $expand query option.

Related Entities for $expand Description
Datastream Display inline details of Datastream for Observations
FeatureOfInterest Display inline details of FeatureOfInterest for Observations

[formpanel type=GET] [formtitle] /v1.0/Observations(id)?$expand=Datastream [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 5: GET with select

Retrieve specified properties for a specific Observation.

Properties for $select Description
phenomenonTime The Time when the observation happens
result The Estimated value of Sensor reading for the ObservedProperty
resultTime The Time when the observations result was generated
resultQuality Describes the quality of the result
validTime The time period during which the result may be used.
parameters Key-Value pairs describing the environmental conditions during measurement
Datastream The navigationLink to the Datastream of this Observation.
FeatureOfInterest The navigationLink to the FeatureOfInterest of this Observation.

[formpanel type=GET] [formtitle] /v1.0/Observations(id)?$select=phenomenonTime,result [/formtitle] [formbody]

[/formbody] [/formpanel]

PATCH

Update an Observation with new values for its properties.

[tabpanel] [tabpage header=HTTP id=Observations-patch-tab-1]

{
  "phenomenonTime": "2017-02-09T18:02:00.000Z",
  "resultTime" : "2017-02-09T18:02:05.000Z"
}

[/tabpage] [tabpage header=JavaScript/jQuery id=Observations-patch-tab-2]

var patchJson = JSON.stringify({
  "phenomenonTime": "2017-02-09T18:02:00.000Z",
  "resultTime" : "2017-02-09T18:02:05.000Z"
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Observations(id)",
    type: "PATCH",
    data: patchJson,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);

    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=Observations-patch-tab-3]

curl -X PATCH -H "Content-Type: application/json" -d '{
  "phenomenonTime": "2017-02-09T18:02:00.000Z",
  "resultTime" : "2017-02-09T18:02:05.000Z"
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Observations(id)"

[/tabpage] [/tabpanel]

[formpanel type=PATCH] [formtitle] /v1.0/Observations(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

DELETE

Delete an Observation.

[tabpanel] [tabpage header=HTTP id=Observations-delete-tab-1]

https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Observations(id)

[/tabpage] [tabpage header=JavaScript/jQuery id=Observations-delete-tab-2]

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Observations(id)",
    type: "DELETE",
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=Observations-delete-tab-3]

curl -X DELETE -H "Content-Type: application/json" -H -d '' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Observations(id)"

[/tabpage] [/tabpanel]

[formpanel type=DELETE] [formtitle] /v1.0/Observations(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

FeaturesOfInterest

An Observation results is a value being assigned to a phenomenon. The phenomenon is a property of a feature, the latter being the FeatureOfInterest of the Observation [OGC and ISO 19156:2011]. In the context of the Internet of Things, many Observations’ FeatureOfInterest can be the Location of the Thing. For example, the FeatureOfInterest of a wifi-connect thermostat can be the Location of the thermostat (i.e., the living room where the thermostat is located in). In the case of remote sensing, the FeatureOfInterest can be the geographical area or volume that is being sensed.

POST

Property Required Type
name mandatory String
description mandatory String
encodingType mandatory ValueCode
feature mandatory Any (depending on the value of the encodingType)

Example 1: POST

Create a FeatureOfInterest.

[tabpanel] [tabpage header=HTTP id=FeaturesOfInterest-post-tab-1]

{
  "name": "UofC CCIT",
  "description": "University of Calgary, CCIT building",
  "encodingType": "application/vnd.geo+json",
  "feature": {
    "type": "Point",
    "coordinates": [-114.133, 51.08]
  }
}

[/tabpage] [tabpage header=JavaScript/jQuery id=FeaturesOfInterest-post-tab-2]

var json = JSON.stringify({
  "name": "UofC CCIT",
  "description": "University of Calgary, CCIT building",
  "encodingType": "application/vnd.geo+json",
  "feature": {
    "type": "Point",
    "coordinates": [-114.133, 51.08]
  }
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/FeaturesOfInterest",
    type: "POST",
    data: json,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=FeaturesOfInterest-post-tab-3]

curl -X POST -H "Content-Type: application/json" -d '{
  "name": "UofC CCIT",
  "description": "University of Calgary, CCIT building",
  "encodingType": "application/vnd.geo+json",
  "feature": {
    "type": "Point",
    "coordinates": [-114.133, 51.08]
  }
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/FeaturesOfInterest"

[/tabpage] [/tabpanel]

[formpanel type=POST] [formtitle] /v1.0/FeaturesOfInterest [/formtitle] [formbody]

[/formbody] [/formpanel]

GET

Example 1: GET

Retrieve all FeaturesOfInterest.

[tabpanel] [tabpage header=HTTP id=FeaturesOfInterest-get-tab-1-1]

https://toronto-bike-snapshot.sensorup.com/v1.0/FeaturesOfInterest

[/tabpage] [tabpage header=JavaScript/jQuery id=FeaturesOfInterest-get-tab-1-2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/FeaturesOfInterest",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=FeaturesOfInterest-get-tab-1-3]

curl -X GET -H "Content-Type: application/json" "https://toronto-bike-snapshot.sensorup.com/v1.0/FeaturesOfInterest"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/FeaturesOfInterest [/formtitle] [formbody]

[/formbody] [/formpanel]

Exmaple 2: GET by id

Retrieve a specific FeatureOfInterest.

[formpanel type=GET] [formtitle] /v1.0/FeaturesOfInterest(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 3: GET with expand

Retrieve a FeatureOfInterest with inline related enities using $expand query option.

Related Entities for $expand Description
Observations Display inline details of Observations for FeaturesOfInterest

[formpanel type=GET] [formtitle] /v1.0/FeaturesOfInterest(id)?$expand=Observations [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 4: GET with select

Retrieve specified properties for a specific FeatureOfInterest.

Properties for $select Description
name A property provides a label for FeatureOfInterest entity, commonly a descriptive name.
description The description about the FeatureOfInterest.
encodingType The encoding type of the feature property.
feature The detailed description of the feature. The data type is defined by encodingType.
Observations The navigationLink to the Observations of this FeatureOfInterest.

[formpanel type=GET] [formtitle] /v1.0/FeaturesOfInterest(id)?$select=description [/formtitle] [formbody]

[/formbody] [/formpanel]

PATCH

Update a FeatureOfInterest with new values for its properties.

[tabpanel] [tabpage header=HTTP id=FeaturesOfInterest-patch-tab-1]

{
  "feature": {
    "coordinates": [
      -114.154,
      51.064
    ],
    "type": "Point"
  }
}

[/tabpage] [tabpage header=JavaScript/jQuery id=FeaturesOfInterest-patch-tab-2]

var patchJson = JSON.stringify({
  "feature": {
    "coordinates": [
      -114.154,
      51.064
    ],
    "type": "Point"
  }
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Observations(id)",
    type: "PATCH",
    data: patchJson,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);

    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=FeaturesOfInterest-patch-tab-3]

curl -X PATCH -H "Content-Type: application/json" -d '{
  "feature": {
    "coordinates": [
      -114.154,
      51.064
    ],
    "type": "Point"
  }
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Observations(id)"

[/tabpage] [/tabpanel]

[formpanel type=PATCH] [formtitle] /v1.0/FeaturesOfInterest(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

DELETE

Delete a FeatureOfInterest.

[tabpanel] [tabpage header=HTTP id=FeaturesOfInterest-delete-tab-1]

https://scratchpad.sensorup.com/OGCSensorThings/v1.0/FeaturesOfInterest(id)

[/tabpage] [tabpage header=JavaScript/jQuery id=FeaturesOfInterest-delete-tab-2]

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/FeaturesOfInterest(id)",
    type: "DELETE",
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=FeaturesOfInterest-delete-tab-3]

curl -X DELETE -H "Content-Type: application/json" -H -d '' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/FeaturesOfInterest(id)"

[/tabpage] [/tabpanel]

[formpanel type=DELETE] [formtitle] /v1.0/FeaturesOfInterest(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

Query Options

The use of query options allows refining the requests to help get the required information about the SensorThings entities in an easy and efficient manner. Each of the listed query options are available for each SensorThings entity, however the options for each may differ.

SensorThings query options can be categorized to two different groups. The first group specifies the properties to be returned by the request. $expand and $select are query options of this group. The second group is limiting, filtering, or re-ordering the request results. This group contains $orderby, $top, $skip, $count, and $filter.

expand

Use $expand query option to request inline information for related entities of the requested entity collection.

Query Options Description
$expand comma separated list of sub-entity names or sub-entity names separated by forward slash Retrieves the specified related entities and represents it inline to the base entity.

Example 1: Returns the entity set of Things as well as each of the Datastreams associated with each Thing entity.

[tabpanel] [tabpage header=HTTP id=expand1]

https://toronto-bike-snapshot.sensorup.com/v1.0/Things?$expand=Datastreams

[/tabpage] [tabpage header=JavaScript/jQuery id=expand2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/Things?$expand=Datastreams",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=expand3]

curl -X GET -H "Content-Type: application/json" "https://toronto-bike-snapshot.sensorup.com/v1.0/Things?%24expand=Datastreams"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/Things?$expand=Datastreams [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 2: Returns the collection of Things, the Datastreams associated with each Thing, and the ObservedProperty associated with each Datastream.

[formpanel type=GET] [formtitle] /v1.0/Thing?$expand=Datastreams/ObservedProperty [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 3: Returns the Datastream with specific id with inline Observations and ObservedProperty associated with it.

[formpanel type=GET] [formtitle] /v1.0/Datastreams(id)?$expand=Observations,ObservedProperty [/formtitle] [formbody]

[/formbody] [/formpanel]

select

The $select query option requests specific properties of an entity from the SensorThings service. This query option is used to help reduce the amount of information returned from the server.

Query Options Description
$select comma separated list of property names (including navigation property names) If set, the result will include the specified properties of the SensorThing entity.

Example 1: Returns only the result and phenomenonTime properties for each Observation entity.

[tabpanel] [tabpage header=HTTP id=select1]

https://toronto-bike-snapshot.sensorup.com/v1.0/Observations?$select=result,phenomenonTime

[/tabpage] [tabpage header=JavaScript/jQuery id=select2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/Observations?$select=result,phenomenonTime",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=select3]

curl -X GET -H "Content-Type: application/json" "https://toronto-bike-snapshot.sensorup.com/v1.0/Observations?%24select=result%2CphenomenonTime"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/Observations?$select=result,phenomenonTime [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 2: Returns the name property of the Datastream entity, and all the properties of the entity identified by the Observations and FeatureOfInterest navigation properties.

[formpanel type=GET] [formtitle] /v1.0/Datastreams(id)?$select=name,Observations&$expand=Observations/FeatureOfInterest [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 3: Returns a specific Datastreams together with the result and phenomenonTime properties of the entity identified by the Observations navigation property.

[formpanel type=GET] [formtitle] /v1.0/Datastreams(id)?$expand=Observations($select=result,phenomenonTime) [/formtitle] [formbody]

[/formbody] [/formpanel]

orderby

Use $orderby query option to sort the response based on properties of requested entity in accending (asc) or decending (desc) order.

Query Options Description
$orderby comma separated list of property names with suffix asc for ascending or desc for descending Is used to specify which properties are used to order the collection of entities identified by the resource path.

Example: Returns all Observations ordered by the phenomenonTime property in descending order.

[tabpanel] [tabpage header=HTTP id=orderby1]

https://toronto-bike-snapshot.sensorup.com/v1.0/Observations?$orderby=phenomenonTime

[/tabpage] [tabpage header=JavaScript/jQuery id=orderby2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/Observations?$orderby=phenomenonTime",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=orderby3]

curl -X GET -H "Content-Type: application/json" "https://toronto-bike-snapshot.sensorup.com/v1.0/Observations?%24orderby=phenomenonTime"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/Observations?$orderby=phenomenonTime desc [/formtitle] [formbody]

[/formbody] [/formpanel]

top

Use $top query option to limit the number of requested entities.

Query Options Description
$top non-negative integer value Specifies a non-negative integer that limits the number of entities returned within a collection. The service must return the number of available entities up to, but not exceeding, the specified value.

Example 1: Returns only the first five entities in the Observations collection.

[tabpanel] [tabpage header=HTTP id=top1]

https://toronto-bike-snapshot.sensorup.com/v1.0/Observations?$top=5

[/tabpage] [tabpage header=JavaScript/jQuery id=top2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/Observations?$top=5",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=top3]

curl -X GET -H "Content-Type: application/json"  "https://toronto-bike-snapshot.sensorup.com/v1.0/Observations?%24top=5"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/Observations?$top=5 [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 2: Returns the first three Observation entries after sorted by the phenomenonTime property in descending order.

[formpanel type=GET] [formtitle] /v1.0/Observations?$top=3&$orderby=phenomenonTime desc [/formtitle] [formbody]

[/formbody] [/formpanel]

skip

Use $skip to specify the number of entities that should be skipped before returning the requested entities.

Query Options Description
$skip non-negative integer value Specifies the number for the entities of the queried collection that must be excluded from the result.

Example 1: Returns Thing entities starting with the sixth Thing entity in the Things collection.

[tabpanel] [tabpage header=HTTP id=skip1]

https://toronto-bike-snapshot.sensorup.com/v1.0/Things?$skip=5

[/tabpage] [tabpage header=JavaScript/jQuery id=skip2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/Things?$skip=5",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=skip3]

curl -X GET -H "Content-Type: application/json" "https://toronto-bike-snapshot.sensorup.com/v1.0/Things?%24skip=5"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/Things?$skip=5 [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 2: Returns the third and fourth Observation entities from the collection of all Observation entities when the collection is sorted by the phenomenonTime property in ascending order.

[formpanel type=GET] [formtitle] /v1.0/Observations?$skip=2&$top=2&$orderby=phenomenonTime [/formtitle] [formbody]

[/formbody] [/formpanel]

count

Use $count query option to get the total number of result entities for the request.

Query Options Description
$count true or false Is used to retrieve the total number of items in a collection matching the requested entity.

Example: Return, along with the results, the total number of Things in the collection.

[tabpanel] [tabpage header=HTTP id=count1]

https://toronto-bike-snapshot.sensorup.com/v1.0/Things?$count=true

[/tabpage] [tabpage header=JavaScript/jQuery id=count2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/Things?$count=true",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=count3]

curl -X GET -H "Content-Type: application/json" "https://toronto-bike-snapshot.sensorup.com/v1.0/Things?%24count=true"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/Things?$count=true [/formtitle] [formbody]

[/formbody] [/formpanel]

filter

Use $filter query option to perform conditional operations on the property values and filter request result.

  • By default, $filter operations treat the result as a string.
  • If Observations are retrieved as children of a Datastream (e.g., Datastreams(id)/Observations), and that Datastream has an observationType of OM_Measurement, then $filter operations will treat the result as a number.
Query Options Description
$filter 'Property/Function Operator Literal' or Functions Specify the expression for filtering the result of a request

Example 1: Returns all Observations of a specified Datastream, which result is less than 10.

[tabpanel] [tabpage header=JSON class=active id=filter1]

https://toronto-bike-snapshot.sensorup.com/v1.0/Datastreams(206051)/Observations?$filter=result lt 10

[/tabpage] [tabpage header=JavaScript/jQuery id=filter2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/Datastreams(206051)/Observations?$filter=result lt 10",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=filter3]

curl -X GET -H "Content-Type: application/json" "https://toronto-bike-snapshot.sensorup.com/v1.0/Datastreams(206051)/Observations?%24filter=result%20lt%2010"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/Datastreams(id)/Observations?$filter=result lt 10 [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 2: Returns all Observations before the specified time.

[formpanel type=GET] [formtitle] /v1.0/Observations?$filter=phenomenonTime lt ‘2016-11-24T14:37:01.000Z’ [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 3: Returns all Locations that have the location Central Tech [-79.407,43.661].

[formpanel type=GET] [formtitle] /v1.0/Locations?$filter=st_equals(location,geography’POINT(-79.407 43.661)’) [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 4: Returns Things that have any observations of a feature of interest with a specified name and from January to March 2017.

[formpanel type=GET] [formtitle] /Things?$expand=Datastreams/Observations/FeatureOfInterest&$filter=Datastreams/Observations/FeatureOfInterest/name eq ‘7000:Ft. York / Capreol Crt.’ and Datastreams/Observations/phenomenonTime ge 2017-01-01T00:00:00.000Z and Datastreams/Observations/phenomenonTime le 2017-03-01T00:00:00.000Z [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 5: Returns a specific Datastream with inline Observations that have result equal to 2.

[formpanel type=GET] [formtitle] /v1.0/Datastreams(id)?$expand=Observations($filter=result eq 2) [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 6: Returns a specific Datastream with inline result and phenomenonTime properties of its Observations that have result equal to 2.

[formpanel type=GET] [formtitle] /v1.0/Datastreams(id)?$expand=Observations($filter=result eq 2;$select=result,phenomenonTime) [/formtitle] [formbody]

[/formbody] [/formpanel]

Built-in Filter Operators

Operator Description Example
Comparison Operators    
eq Equal /ObservedProperties?$filter=name eq 'Area Temperature'
ne Not equal /ObservedProperties?$filter=name ne 'Area Temperature'
gt Greaterthan /Datastreams(id)/Observations?$filter=result gt 20.0
ge Greater than or equal /Datastreams(id)/Observations?$filter=result ge 20.0
lt Less than /Datastreams(id)/Observations?$filter=result lt 100
le Less than or equal /Datastreams(id)/Observations?$filter=result le 100
Logical Operators    
and Logical and /Datastreams(id)/Observations?$filter=result le 3.5 and FeatureOfInterest/id eq '1'
or Logical or /Datastreams(id)/Observations?$filter=result gt 20 or result le 3.5
not Logical negation /Things?$filter=not startswith(description,'test')
Grouping Operators    
( ) Precedence grouping /Datastreams(id)/Observations?$filter=(result sub 5) gt 10

Built-in Query Functions

Function Example
String Functions  
bool substringof(string searchString,string baseString) substringof('Sensor Things',description)
bool endswith(string baseString, string suffix) endswith(description,'Things')
bool startswith(string baseString, string prefix) startswith(description,'Sensor')
int length(string p0) length(description) eq 13
string tolower(string p0) tolower(description) eq 'sensor things'
string toupper(string p0) toupper(description) eq 'SENSOR THINGS'
Date Functions  
int year year(resultTime) eq 2015
int month month(resultTime) eq 12
int day day(resultTime) eq 8
int hour hour(resultTime) eq 1
int minute minute(resultTime) eq 0
int second second(resultTime) eq 0
Math Functions  
round round(result) eq 32
floor floor(result) eq 32
ceiling ceiling(result) eq 33
Geospatial Functions  
double geo.distance(Point p0, Point p1) geo.distance(location, geography'POINT (30 10)')
double geo.length(LineString p0) geo.length(geography'LINESTRING (30 10, 10 30, 40 40)')
bool geo.intersects(Point p0, Polygon p1) geo.intersects(location,geography'POLYGON ((30 10, 10 20, 20 40, 40 40, 30 10))')
Spatial Relationship Functions  
bool st_equals st_equals(location, geography'POINT (30 10)')
bool st_disjoint st_disjoint(location, geography'POLYGON ((30 10, 10 20, 20 40, 40 40, 30 10))')
bool st_touches st_touches(location, geography'LINESTRING (30 10, 10 30, 40 40)')
bool st_within st_within(location, geography'POLYGON ((30 10, 10 20, 20 40, 40 40, 30 10))')
bool st_overlaps st_overlaps(location, geography'POLYGON ((30 10, 10 20, 20 40, 40 40, 30 10))')
bool st_crosses st_crosses(location, geography'LINESTRING (30 10, 10 30, 40 40)')
bool st_intersects st_intersects(location, geography'LINESTRING (30 10, 10 30, 40 40)')
bool st_contains st_contains(location, geography'POINT (30 10)')
bool st_relate st_relate(location, geography'POLYGON ((30 10, 10 20, 20 40, 40 40, 30 10))', 'T****')

resultFormat

Use $resultFormat query option to return Observations in a data array format.

Property Options Description
$resultFormat dataArray Enables returning Observations in data arrays.

Example 1: Returns all Observations of a specific Datastream in a data array to minimize metadata being returned from the server.

[formpanel type=GET] [formtitle] /v1.0/Datastreams(id)/Observations?$resultFormat=dataArray [/formtitle] [formbody]

[/formbody] [/formpanel]

SensorThings API - Tasking

The following diagram is the UML Data Model for OGC SensorThings API and defining different entities and their properties, together with the relationship between entities.

TaskingCapability

Properties of a TaskingCapability

Name Definition Data type Multiplicity and use
name A property provides a label for the entity, commonly a descriptive name CharacterString One (mandatory)
description A short description of the corresponding entity CharacterString One (mandatory)
taskingParameters Describes optional and mandatory tasking parameters. SWE Common JSON Object One (mandatory)
properties A JSON Object containing user-annotated properties as key-value pairs JSON Object Zero-to-one

Direct relation between a TaskCapability and other entity types:

Entity Type Description
Task A TaskingCapability has zero-to-many Tasks. A Task has one-and-only-one TaskingCapability.
Thing A TaskingCapability has one-and-only-one Thing. A Thing has zero-to-many TaskingCapabilities.
Actuator A TaskingCapability has one-and-only-one Actuator. An Actuator has zero-to-many TaskingCapabilities.

Example 1: Get

Retrieve all TaskingCapabilities

[formpanel type=GET] [formtitle] /v1.0/TaskingCapabilities [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 2: Get by id

Retrieve a specific TaskingCapability.

[formpanel type=GET] [formtitle] /v1.0/TaskingCapabilities(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

Task

Properties of a Task

Name Definition Data type Multiplicity and use
taskingParameters Describes values for optional and mandatory tasking parameters. SWE Common JSON Object One (mandatory)
creationTime The time when the Task is created. Added automatically by the service. TM_Instant (ISO-8601 Time String) One (mandatory)

Direct relation between a Task and other entity types

Entity Type Description
TaskingCapability A Task has one-and-only-one TaskingCapability. A TaskingCapability has zero-to-many Tasks.

Example 1: Get

Retrieve all Tasks

[formpanel type=GET] [formtitle] /v1.0/Tasks [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 2: Get by id

Retrieve a specific Task.

[formpanel type=GET] [formtitle] /v1.0/Tasks(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

Actuator

Properties of an Actuator

Name Definition Data type Multiplicity and use
name The label for the entity CharacterString One (mandatory)
description The description of the Actuator entity CharacterString One (mandatory)
encodingType The encoding type of the metadata property. Its value is one of the ValueCode enumeration Any (depending on the value of the encodingType) One (mandatory)
metadata The detailed description of the Actuator. The metadata type is defined by encodingType Any (depending on the value of the encodingType) One (mandatory)

Direct relation between an Actuator and other entity types

Entity Type Description
TaskingCapabilities An Actuator has zero-to-many TaskingCapabilities. A TaskingCapability has one-and-only-one Actuator

List of some code values used for identifying types for the encodingType of the Actuator entity

Actuator encodingType ValueCode Value
PDF application/pdf
SensorML http://www.opengis.net/doc/IS/SensorML/2.0

The Actuator encodingType allows you to know how to interpret metadata’s value. Currently SensorThings API defines two common Actuator metadata encodingTypes. Most sensor manufacturers provide their sensor datasheets in a PDF format. As a result, PDF is a Sensor encodingType supported by SensorThings API. The second Sensor encodingType is SensorML.

Example 1: GET

Retrieve all Actuators.

[formpanel type=GET] [formtitle] /v1.0/Actuators [/formtitle] [formbody]

[/formbody] [/formpanel]

Example 2: GET by id

Retrieve a specific Actuator.

[formpanel type=GET] [formtitle] /v1.0/Actuators(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

Tasking Create

When a SensorThings service receives a create Task request, it will set the createdTime property of the entity to current server time. SensorThings API services support linking new Task entities to existing entities upon creation. To create a new Task with links to existing entities, user have to include the unique identifiers of the related entities associated with the corresponding navigation properties in the request body.

Example 1: Link to existing entities when creating a Task entity

[tabpanel] [tabpage header=HTTP id=taskcreate-example-1]

{
  "taskingParameters": {
    "color": "#ffb800",
    "status": "off"
  },
    "TaskingCapability": {
      "@iot.id": 3963
  }
}

[/tabpage] [/tabpanel]

[formpanel type=POST] [formtitle] /v1.0/Tasks [/formtitle] [formbody]

Choose the colour you like and check the changes on the LED lamp

Please note that the live streaming would have a 3~5 seconds delay.

      [/formbody] [/formpanel]

      Errors

      The SensorThings API uses the following error codes:

      Error Code Meaning
      400 Bad Request – Something in your request is not correct. It could be the content of the JSON or it could be the server endpoint is not expecting this content.
      401 Unauthorized – Bad API key
      404 Not Found – The resource you are looking for does not exist on the system.
      405 Method not allowed – You requested a method that has not been implemented on the server.
      406 Not Acceptable – You requested a format that isn’t JSON.
      409 Conflict – A resource constraint has been violated.
      410 Gone – The resource requested has been removed.
      429 Too Many Requests – Too much load right now. Try again later.
      500 Internal Server Error – We had a problem with our server. Try again later.
      503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.