# OGC SensorThings API

{% hint style="danger" %}
**This extension is currently taken out from the default list**

If you feel that is exactly what you need, please [reach out to us](mailto:support@heisenware.com).
{% endhint %}

## 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 `properties`field 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](https://fraunhoferiosb.github.io/FROST-Server/sensorthingsapi/requestingData/STA-Example-Queries.html), 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](https://docs.ogc.org/is/15-078r6/15-078r6.html)

[FROST Server Documentation](https://fraunhoferiosb.github.io/FROST-Server/)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.heisenware.com/app-builder/build-backend/function-explorer/extensions/ogc-sensorthings-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.