OGC SensorThings API

This article is a work in progress.

For immediate help integrating the OGC SensorThings API, please reach out to us.

Introduction to OGC SensorThings API

The OGC SensorThings API is a standard specification aiming to simplify and standardise the integration and communication of Internet of Things (IoT) sensor data. It enables seamless interoperability between different systems, devices, and applications by providing a unified way to access and share sensor data over the internet. This API is particularly useful for real-time data exchange and monitoring tasks in diverse and distributed sensor networks.

Example

Environmental monitoring application

Imagine an environmental monitoring application that collects data from various sensors deployed in a city. This application can utilise the OGC SensorThings API to access real-time data from sensors measuring air quality, temperature, humidity, and noise levels. By making API requests, 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 and address noise pollution hotspots.

This API enables the application to provide citizens and city officials with up-to-date environmental information, supporting better decision-making and urban planning.

Functions

getThings

Retrieves all Things available on the server. A $filter expression can be applied for selective querying (e.g., filtering by name or description).

Example Filter Expression: name eq 'WeatherStation1'

getThing

Retrieves detailed information about a single Thing by its ID, including its associated Locations and HistoricalLocations.

updateThing

Updates the specified properties of an existing Thing. Possible updatable properties include:

  • name (String): The name of the Thing.

  • description (String): Description text.

  • properties (Object): Additional metadata.

deleteThing

Deletes a Thing identified by its ID.

linkLocations

Associates one or more Location entities to a Thing.

unlinkAllLocations

Removes all Location links from a Thing.

createLocation

Creates a new Location.

Options:

  • name (String): Name of the Location.

  • location (Object): Geospatial data in the format of encodingType.

  • description (String): Description of the Location.

  • properties (Object): Custom attributes.

  • encodingType (String): Defaults to 'application/geo+json'.

You may also link this Location directly to existing Things by providing their IDs.

getLocations

Retrieves all Locations. Supports $filter expressions (e.g., name eq 'SiteA').

getLocation

Retrieves a specific Location by ID.

updateLocation

Updates an existing Location’s properties:

  • name

  • description

  • properties

  • location

  • encodingType

deleteLocation

Deletes a Location by ID.

showLocationHistory

Returns the historical Locations of a Thing, aggregated over time based on a specified property found in the propertiesfield of each Location.

createObservedProperty

Creates an ObservedProperty.

Required options:

  • name (String): Name of the ObservedProperty.

Optional options:

  • description (String): Description.

  • properties (Object): Custom metadata.

  • definition (String): URI of a controlled vocabulary term.

getObservedProperties

Retrieves all ObservedProperties. Supports $filter expressions (e.g., name eq 'Temperature').

getObservedProperty

Fetches a single ObservedProperty by ID.

updateObservedProperty

Updates an existing ObservedProperty’s properties.

deleteObservedProperty

Deletes an ObservedProperty by ID.

createSensor

Creates a Sensor entity.

Required options:

  • name (String): Name of the Sensor.

Optional options:

  • description (String)

  • properties (Object)

  • encodingType (String): MIME type, e.g., application/pdf.

  • metadata (String): Metadata URI.

getSensors

Retrieves all Sensors. Supports $filter expressions.

getSensor

Fetches a Sensor by ID.

updateSensor

Updates a Sensor entity.

deleteSensor

Deletes a Sensor by ID.

Datastreams

createDatastream

Creates a Datastream entity.

Required options:

  • name (String)

  • observationType (String): URI or identifier of the observation type (e.g., http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement).

  • unitOfMeasurement (Object): Must include:

    • name (e.g., 'Degree Celsius')

    • symbol (e.g., '°C')

    • definition (URI string)

  • thingId (Integer)

  • sensorId (Integer)

  • observedPropertyId (Integer)

Optional options:

  • description (String)

getDatastreams

Retrieves all Datastreams. Supports $filter expressions.

getDatastream

Fetches a specific Datastream by ID.

updateDatastream

Updates an existing Datastream.

deleteDatastream

Deletes a Datastream by ID.

Observations

createObservation

Creates an Observation.

Required options:

  • result (any type): The value/result of the observation.

  • phenomenonTime (String, ISO 8601 format): Timestamp of the observation.

Also requires:

  • datastreamId (Integer)

getObservations

Retrieves all Observations. Supports $filter expressions (e.g., phenomenonTime ge 2024-01-01T00:00:00Z).

getObservation

Fetches a specific Observation by ID.

updateObservation

Updates an Observation entity.

deleteObservation

Deletes an Observation by ID.

Raw Requests

For flexibility, raw request methods are also provided:

  • getRaw

  • postRaw

  • patchRaw

  • deleteRaw

These allow direct URL access to the API for custom operations.

Filters and Queries

Many get* methods support OGC-compliant filter expressions, such as:

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

Notes:

  • All IDs refer to @iot.id properties from SensorThings resources.

  • All date/time values follow ISO 8601.

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

More information

OGC SensorThings API Standard 1.0

FROST Server Documentation

Last updated