OGC SensorThings API

Available as a Docker Extension

This connector is not part of the default function list. It ships as a Docker Extension, where the installation is explained.

The OGC SensorThings API connector talks to an OGC SensorThings compliant server (such as a FROST server) and manages Things, Locations, ObservedProperties, Sensors, Datastreams, and Observations. This class requires an instance. The code class name is SensorThings.

Example use case

Imagine an environmental monitoring application that collects data from various sensors deployed in a city. Using the OGC SensorThings API, the application:

• retrieves current air quality indexes from different areas within the city

• gathers temperature and humidity readings to monitor weather conditions

• accesses noise level data to identify noise pollution hotspots

General conventions

• All IDs refer to the @iot.id property of SensorThings resources.

• All date and time values follow ISO 8601.

• For geospatial data in Locations, GeoJSON is recommended (encodingType: 'application/geo+json').

Irreversible action

All delete functions (deleteThing, deleteLocation, deleteObservedProperty, deleteSensor, deleteDatastream, deleteObservation) permanently remove the resource from the server.

Filter expressions

All get* list functions accept an optional OGC compliant filter expression, such as:

name eq 'StationA'
description ne 'Old station'
properties/owner eq 'City Council'

Instance management

create

Creates a SensorThings client instance.

Parameters

Input	Description	Type
apiUrl	The URL of the SensorThings server, for example https://server.de/FROST-Server/v1.1. If omitted, the internal FROST server is used.	string

Output

Returns the name of the created instance.

delete

Deletes a client instance.

Parameters

None.

Output

Returns true upon removal.

Irreversible action

Deleting removes the instance configuration.

Things

createThing

Creates a Thing, an object of the physical or information world that can be identified and integrated into communication networks.

Parameters

Input	Key	Description	Type
options	name	Name of the Thing.	string
	description	Description of the Thing. Default empty.	string
	properties	Any further properties of the Thing. Default {}.	object
	uniqueName	If true, an existing Thing with the same name is updated instead of creating a duplicate. Default false.	boolean

Output

Returns the numeric ID of the created Thing. If uniqueName is set and a Thing with the same name exists, that Thing is updated and the server answer of the update is returned instead.

getThings

Retrieves all or a filtered set of Things.

Parameters

Input	Description	Type
filter	Optional filter expression, see Filter expressions.	string

Output

Returns the server result object with a value array of Things. Locations are expanded.

getThing

Reads all information of a single Thing.

Parameters

Input	Description	Type
id	The Thing ID.	integer

Output

Returns the Thing object with expanded Locations and HistoricalLocations.

updateThing

Updates a Thing.

Parameters

Input	Description	Type
id	The Thing ID.	integer
changes	An object containing only the fields to change, for example name, description, or properties.	object

Output

Returns the server answer to the update request.

deleteThing

Deletes a Thing.

Parameters

Input	Description	Type
id	The Thing ID.	integer

Output

Returns the server answer to the delete request.

linkLocations

Links Locations to a Thing.

Parameters

Input	Description	Type
thingId	The Thing ID.	integer
locationIds	Array of Location IDs to link.	array

Output

Returns nothing. The update runs without waiting for the server, so errors are not reported back.

unlinkAllLocations

Removes all Location links from a Thing.

Parameters

Input	Description	Type
thingId	The Thing ID.	integer

Output

Returns the server answer to the update request.

Locations

createLocation

Creates a Location. The Location locates the Thing or Things it is associated with; a Thing's Location is defined as its last known location.

Parameters

Input	Key	Description	Type
options	name	Name of the Location.	string
	location	Location data in the format defined by encodingType, typically a GeoJSON object.	any
	description	Description of the Location. Default empty.	string
	properties	Any further properties of the Location. Default {}.	object
	encodingType	Encoding type of the location data. Default application/geo+json.	string
	uniqueName	If true, an existing Location with the same name is updated instead of creating a duplicate. Default false.	boolean
thingIds		Array of Thing IDs to link the Location to. Default [].	array

Output

Returns the numeric ID of the created Location. If uniqueName is set and a Location with the same name exists, that Location is updated and its ID is returned.

Example

# options
name: Warehouse A
description: Main storage site
location:
  type: Point
  coordinates: [9.99, 53.55]

# thingIds
[12, 13]

getLocations

Retrieves all or a filtered set of Locations.

Parameters

Input	Description	Type
filter	Optional filter expression, see Filter expressions.	string

Output

Returns the server result object with a value array of Locations. Things are expanded.

getLocation

Retrieves a single Location.

Parameters

Input	Description	Type
id	The Location ID.	integer

Output

Returns the Location object with expanded Things.

updateLocation

Updates a Location.

Parameters

Input	Description	Type
id	The Location ID.	integer
changes	An object containing only the fields to change, for example name, description, properties, location, or encodingType.	object

Output

Returns the server answer to the update request.

deleteLocation

Deletes a Location.

Parameters

Input	Description	Type
id	The Location ID.	integer

Output

Returns the server answer to the delete request.

showLocationHistory

Aggregates the historical Locations of a Thing by time and a selected property.

Parameters

Input	Description	Type
thingId	The Thing ID.	integer
property	A key found in the properties section of each Location.	string

Output

Returns an array with one entry per historical location record, each containing a time string (minute resolution) and one key per Location name holding the value of the selected property.

Observed properties

createObservedProperty

Creates an ObservedProperty, which specifies the phenomenon of an Observation.

Parameters

Input	Key	Description	Type
options	name	Name of the ObservedProperty.	string
	description	Description of the ObservedProperty. Default empty.	string
	properties	Any further properties. Default {}.	object
	definition	URI of a controlled vocabulary term. Default empty.	string
	uniqueName	If true, an existing ObservedProperty with the same name is updated instead of creating a duplicate. Default false.	boolean

Output

Returns the numeric ID of the created or updated ObservedProperty.

getObservedProperties

Retrieves all or a filtered set of ObservedProperties.

Parameters

Input	Description	Type
filter	Optional filter expression, see Filter expressions.	string

Output

Returns the server result object with a value array of ObservedProperties.

getObservedProperty

Retrieves a single ObservedProperty.

Parameters

Input	Description	Type
id	The ObservedProperty ID.	integer

Output

Returns the ObservedProperty object.

updateObservedProperty

Updates an ObservedProperty.

Parameters

Input	Description	Type
id	The ObservedProperty ID.	integer
changes	An object containing only the fields to change.	object

Output

Returns the server answer to the update request.

deleteObservedProperty

Deletes an ObservedProperty.

Parameters

Input	Description	Type
id	The ObservedProperty ID.	integer

Output

Returns the server answer to the delete request.

Sensors

createSensor

Creates a Sensor, an instrument that observes a property or phenomenon to estimate its value.

Parameters

Input	Key	Description	Type
options	name	Name of the Sensor.	string
	description	Description of the Sensor. Default empty.	string
	properties	Any further properties. Default {}.	object
	encodingType	Encoding type of the metadata document, for example application/pdf. Default empty.	string
	metadata	Metadata URI in the specified encoding type. Default empty.	string
	uniqueName	If true, an existing Sensor with the same name is updated instead of creating a duplicate. Default false.	boolean

Output

Returns the numeric ID of the created Sensor.

getSensors

Retrieves all or a filtered set of Sensors.

Parameters

Input	Description	Type
filter	Optional filter expression, see Filter expressions.	string

Output

Returns the server result object with a value array of Sensors.

getSensor

Retrieves a single Sensor.

Parameters

Input	Description	Type
id	The Sensor ID.	integer

Output

Returns the Sensor object.

updateSensor

Updates a Sensor.

Parameters

Input	Description	Type
id	The Sensor ID.	integer
changes	An object containing only the fields to change.	object

Output

Returns the server answer to the update request.

deleteSensor

Deletes a Sensor.

Parameters

Input	Description	Type
id	The Sensor ID.	integer

Output

Returns the server answer to the delete request.

Datastreams

createDatastream

Creates a Datastream, which groups a collection of Observations measuring the same ObservedProperty and produced by the same Sensor.

Parameters

Input	Key	Description	Type
options	name	Name of the Datastream.	string
	description	Description of the Datastream. Default empty.	string
	observationType	URI of the observation type used to encode observations, for example http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement.	string
	unitOfMeasurement	Object with three keys: name (full name of the unit), symbol (textual form of the unit symbol), and definition (URI defining the unit).	object
	uniqueName	If true, an existing Datastream with the same name is updated instead of creating a duplicate. Default false.	boolean
thingId		A Thing ID to link to.	integer
sensorId		A Sensor ID to link to.	integer
observedPropertyId		An ObservedProperty ID to link to.	integer

Output

Returns the numeric ID of the created or updated Datastream.

Example

# options
name: Temperature outdoor
observationType: http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement
unitOfMeasurement:
  name: Degree Celsius
  symbol: °C
  definition: http://unitsofmeasure.org/ucum.html

# thingId
1

# sensorId
2

# observedPropertyId
3

getDatastreams

Retrieves all or a filtered set of Datastreams.

Parameters

Input	Description	Type
filter	Optional filter expression, see Filter expressions.	string

Output

Returns the server result object with a value array of Datastreams.

getDatastream

Retrieves a single Datastream.

Parameters

Input	Description	Type
id	The Datastream ID.	integer

Output

Returns the Datastream object.

updateDatastream

Updates a Datastream.

Parameters

Input	Description	Type
id	The Datastream ID.	integer
changes	An object containing only the fields to change.	object

Output

Returns the server answer to the update request.

deleteDatastream

Deletes a Datastream.

Parameters

Input	Description	Type
id	The Datastream ID.	integer

Output

Returns the server answer to the delete request.

Observations

createObservation

Creates an Observation, the act of measuring or otherwise determining the value of a property.

Parameters

Input	Key	Description	Type
options	result	The measured or estimated value of the observation.	any
	phenomenonTime	The time instant or period of the observation, in ISO 8601 format.	string
datastreamId		A Datastream ID to link to.	integer

Output

Returns the numeric ID of the created Observation.

Example

# options
result: 21.4
phenomenonTime: 2024-01-01T12:00:00Z

# datastreamId
4

getObservations

Retrieves all or a filtered set of Observations, for example with the filter phenomenonTime ge 2024-01-01T00:00:00Z.

Parameters

Input	Description	Type
filter	Optional filter expression, see Filter expressions.	string

Output

Returns the server result object with a value array of Observations.

getObservation

Retrieves a single Observation.

Parameters

Input	Description	Type
id	The Observation ID.	integer

Output

Returns the Observation object.

updateObservation

Updates an Observation.

Parameters

Input	Description	Type
id	The Observation ID.	integer
changes	An object containing only the fields to change.	object

Output

Returns the server answer to the update request.

deleteObservation

Deletes an Observation.

Parameters

Input	Description	Type
id	The Observation ID.	integer

Output

Returns the server answer to the delete request.

Raw requests

For custom operations, four raw request functions provide direct URL access to the API.

getRaw

Sends a raw GET request.

Parameters

Input	Description	Type
url	The path or full URL to request.	string

Output

Returns the raw server response.

postRaw

Sends a raw POST request. No request body can be provided.

Parameters

Input	Description	Type
url	The path or full URL to request.	string

Output

Returns the raw server response.

patchRaw

Sends a raw PATCH request. No request body can be provided.

Parameters

Input	Description	Type
url	The path or full URL to request.	string

Output

Returns the raw server response.

deleteRaw

Sends a raw DELETE request.

Parameters

Input	Description	Type
url	The path or full URL to request.	string

Output

Returns the raw server response.

More information

OGC SensorThings API Standard 1.0

FROST Server Documentation