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, which was released in 2019, 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

OGC SensorThings API Part 2 - Tasking Core Discussion Paper

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.

GET 

/v1.0/

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.

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

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);
    }
});
Copy

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"
Copy

POST 

/v1.0/Things

​x
 
1
2
3
4
5
6
7
8
9

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.

{
  "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]
    }
  }]
}
Copy

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);
    }
});
Copy

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"
Copy

POST 

/v1.0/Things

18
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

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.

{
  "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}
  ]
}
Copy

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);
    }
});
Copy

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'
Copy

POST 

/v1.0/Things

12
 
1
2
3
4
5
6
7
8
9
10
11
12

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.

{
  "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"
    }
  }]
}
Copy

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);
    }
});
Copy

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'
Copy

POST 

/v1.0/Things

39
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

GET

Example 1: GET

Retrieve all Things.

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

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

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

GET 

/v1.0/Things

Example 2: GET by id

Retrieve a specific Thing.

GET 

/v1.0/Things(id)

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

GET 

/v1.0/Things(id)?$expand=Datastreams

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.

GET 

/v1.0/Things(id)?$select=description

PATCH

Update a specific Thing with new property values.

{
  "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}
  ]
}
Copy

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);
  }
});
Copy

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)"
Copy

PATCH 

/v1.0/Things(id)

11
 
1
2
3
4
5
6
7
8
9
10
11

DELETE

To delete a Thing. 

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

$.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);
  }
});
Copy

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

DELETE 

/v1.0/Things(id)

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.

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

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);
    }
});
Copy

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"
Copy

POST 

/v1.0/Locations

10
 
1
2
3
4
5
6
7
8
9
10

Example 2: POST with existing Thing

Create a Location linked to an existing Thing.

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

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);
    }
});
Copy

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"
Copy

POST 

/v1.0/Things(id)/Locations

10
 
1
2
3
4
5
6
7
8
9
10

GET

Example 1: GET

Retrieve all Locations.

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

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

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

GET 

/v1.0/Locations

Example 2: GET by id

Retrieve a specific Location.

GET 

/v1.0/Locations(id)

Example 3: GET by Thing id

Retrieve Locations of a specific Thing

GET 

/v1.0/Things(id)/Locations

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

GET 

/v1.0/Locations(id)?$expand=Things

Example 5: GET with filter - spatial query

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

GET 

/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))')

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.

GET 

/v1.0/Locations(id)?$select=description

PATCH

Update a Location with new values for its properties.

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

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);
  }
});
Copy

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)"
Copy

PATCH 

/v1.0/Locations(id)

8
 
1
2
3
4
5
6
7
8

DELETE

Delete a Location.

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

$.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);
  }
});
Copy

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

DELETE 

/v1.0/Locations(id)

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.

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

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

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

GET 

/v1.0/HistoricalLocations

Example 2: GET by id

Retrieve a specific historical location.

GET 

/v1.0/HistoricalLocations(id)

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

GET 

/v1.0/HistoricalLocations(id)?$expand=Locations

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

GET 

/v1.0/HistoricalLocations(id)?$select=time

PATCH

Update a HistoricalLocation entity with new values for its properties.

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

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);
    }
});
Copy

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)"
Copy

PATCH 

/v1.0/HistoricalLocations(id)

4
 
1
2
3
4

DELETE

Delete a HistoricalLocation.

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

$.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);
    }
});
Copy

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

DELETE 

/v1.0/HistoricalLocations(id)

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.

{
  "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}
}
Copy

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);
    }
});
Copy

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"
Copy

POST 

/v1.0/Datastreams

14
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14

Example 2: POST with a Thing

Create a Datastream and link it to a Thing.

{
  "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"
  }
}
Copy

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);
    }
});
Copy

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"
Copy

POST 

/v1.0/Things(id)/Datastreams

22
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

GET

Example 1: GET

Retrieve all the Datastreams.

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

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

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

GET 

/v1.0/Datastreams

Example 2: GET by id

Retrieve a specific Datastream.

GET 

/v1.0/Datastreams(id)

Example 3: GET by Things id

Retrieve Datastreams of a specific Thing.

GET 

/v1.0/Things(id)/Datastreams

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

GET 

/v1.0/Datastreams(id)?$expand=Observations,ObservedProperty

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.

GET 

/v1.0/Datastreams(id)?$select=description,unitOfMeasurement

PATCH

Patch a Datastream with new values.

{
  "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"
}
Copy

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);
    }
});
Copy

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)"
Copy

PATCH 

/v1.0/Datastreams(id)

9
 
1
2
3
4
5
6
7
8
9

DELETE

Delete a Datastream.

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

$.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);
    }
});
Copy

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

DELETE 

/v1.0/Datastreams(id)

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.

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

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);
    }
});
Copy

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"
Copy

POST 

/v1.0/Sensors

7
 
1
2
3
4
5
6
7

GET

Example 1: GET

Retrieve all Sensors.

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

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

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

GET 

/v1.0/Sensors

Example 2: Get by id

Retrieve a specific Sensor.

GET 

/v1.0/Sensors(id)

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

GET 

/v1.0/Sensors(id)?$expand=Datastreams

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.

GET 

/v1.0/Sensors(id)?$select=description

PATCH

Update a Sensor with new values for its properties.

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

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);
    }
});
Copy

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

PATCH 

/v1.0/Sensors(id)

4
 
1
2
3
4

DELETE

Delete a Sensor.

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

$.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);
    }
});
Copy

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

DELETE 

/v1.0/Sensors(id)

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.

{
  "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"
}
Copy

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);
    }
});
Copy

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"
Copy

POST 

/v1.0/ObservedProperties

6
 
1
2
3
4
5
6

GET

Example 1: GET

Retrieve all ObservedProperties.

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

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

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

GET 

/v1.0/ObservedProperties

Example 2: GET by id

Retrieve a specific ObservedProperty.

GET 

/v1.0/ObservedProperties(id)

Example 3: GET by Datastream id

Retrieve the ObservedProperty of a specific Datastream.

GET 

/v1.0/Datastream(id)/ObservedProperty

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.

GET 

/v1.0/ObservedProperties(id)?$expand=Datastreams

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.

GET 

/ObservedProperties(id)?$select=description

PATCH

Update an ObservedProperty with new values for its properties.

{
  "name": "Water Temperature"
}
Copy

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);
    }
});
Copy

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

PATCH 

/v1.0/ObservedProperties(id)

4
 
1
2
3
4

DELETE

Delete an ObservedProperty.

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

$.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);
    }
});
Copy

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

DELETE 

/v1.0/ObservedProperties(id)

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. 

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

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);
    }
});
Copy

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"
Copy

POST 

/v1.0/Observations

7
 
1
2
3
4
5
6
7

Example 2: POST with FeatureOfInterest

Create an Observation with inline FeatureOfInterest.

POST 

/v1.0/Observations

16
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Example 3: POST with Datastream

Create an Observation and link it to an existing Datastream.

POST 

/v1.0/Datastreams(id)/Observations

6
 
1
2
3
4
5
6

Example 4: POST with Datastream and FeatureOfInterest

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

POST 

/v1.0/Datastreams(id)/Observations

7
 
1
2
3
4
5
6
7

GET

Example 1: GET

Retrieve all Observations.

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

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

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

GET 

/v1.0/Observations

Example 2: GET by Observation id

Retrieve a specific Observation.

GET 

/v1.0/Observations(id)

Example 3: GET by Datastream id

Retrieve Observations for a specific Datastream.

GET 

/v1.0/Datastreams(id)/Observations

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

GET 

/v1.0/Observations(id)?$expand=Datastream

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.

GET 

/v1.0/Observations(id)?$select=phenomenonTime,result

PATCH

Update an Observation with new values for its properties.

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

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);
    }
});
Copy

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)"
Copy

PATCH 

/v1.0/Observations(id)

5
 
1
2
3
4
5

DELETE

Delete an Observation.

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

$.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);
    }
});
Copy

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

DELETE 

/v1.0/Observations(id)

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.

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

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);
    }
});
Copy

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"
Copy

POST 

/v1.0/FeaturesOfInterest

10
 
1
2
3
4
5
6
7
8
9
10

GET

Example 1: GET

Retrieve all FeaturesOfInterest.

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

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

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

GET 

/v1.0/FeaturesOfInterest

Exmaple 2: GET by id

Retrieve a specific FeatureOfInterest.

GET 

/v1.0/FeaturesOfInterest(id)

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

GET 

/v1.0/FeaturesOfInterest(id)?$expand=Observations

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.

GET 

/v1.0/FeaturesOfInterest(id)?$select=description

PATCH

Update a FeatureOfInterest with new values for its properties.

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

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);
    }
});
Copy

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)"
Copy

PATCH 

/v1.0/FeaturesOfInterest(id)

10
 
1
2
3
4
5
6
7
8
9
10

DELETE

Delete a FeatureOfInterest.

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

$.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);
    }
});
Copy

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

DELETE 

/v1.0/FeaturesOfInterest(id)

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.

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

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

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

GET 

/v1.0/Things?$expand=Datastreams

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

GET 

/v1.0/Thing?$expand=Datastreams/ObservedProperty

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

GET 

/v1.0/Datastreams(id)?$expand=Observations,ObservedProperty

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.

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

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

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

GET 

/v1.0/Observations?$select=result,phenomenonTime

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.

GET 

/v1.0/Datastreams(id)?$select=name,Observations&$expand=Observations/FeatureOfInterest

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

GET 

/v1.0/Datastreams(id)?$expand=Observations($select=result,phenomenonTime)

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.

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

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

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

GET 

/v1.0/Observations?$orderby=phenomenonTime desc

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.

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

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

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

GET 

/v1.0/Observations?$top=5

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

GET 

/v1.0/Observations?$top=3&$orderby=phenomenonTime desc

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.

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

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

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

GET 

/v1.0/Things?$skip=5

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.

GET 

/v1.0/Observations?$skip=2&$top=2&$orderby=phenomenonTime

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.

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

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

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

GET 

/v1.0/Things?$count=true

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.

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

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

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

GET 

/v1.0/Datastreams(id)/Observations?$filter=result lt 10

Example 2: Returns all Observations before the specified time.

GET 

/v1.0/Observations?$filter=phenomenonTime lt '2016-11-24T14:37:01.000Z'

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

GET 

/v1.0/Locations?$filter=st_equals(location,geography'POINT(-79.407 43.661)')

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

GET 

/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

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

GET 

/v1.0/Datastreams(id)?$expand=Observations($filter=result eq 2)

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

GET 

/v1.0/Datastreams(id)?$expand=Observations($filter=result eq 2;$select=result,phenomenonTime)

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.

GET 

/v1.0/Datastreams(id)/Observations?$resultFormat=dataArray

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

GET 

/v1.0/TaskingCapabilities

Example 2: Get by id

Retrieve a specific TaskingCapability.

GET 

/v1.0/TaskingCapabilities(id)

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

GET 

/v1.0/Tasks

Example 2: Get by id

Retrieve a specific Task.

GET 

/v1.0/Tasks(id)

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.

GET 

/v1.0/Actuators

Example 2: GET by id

Retrieve a specific Actuator.

GET 

/v1.0/Actuators(id)

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

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

POST 

/v1.0/Tasks

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.

  • Connecting to server:tasking-test.sensorup.com

    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.