Getting Started

This API provides an interface via the endpoint /context/sensorthings/, allowing you to interact with the FROST-Server, an implementation of the OGC SensorThings API standard.

SensorThings API is a standard designed by the Open Geospatial Consortium (OGC) to standardize the way sensor data and observations are accessed and managed in IoT (Internet of Things) applications. The FROST-Server is an open-source server implementation of this standard.

In order to use an API via APISIX, you need to have an account created on our Keycloak IDM and have an administrator grant you access to a data space.

For accessing the API with valid credentials, please see How to Get an Access Token.

The OGC SensorThings API is a RESTful API. This means that data from the API can be easily viewed using a normal web browser. One can simply navigate from one object to the next by clicking the URLs provided within the data.

Data Spaces

While the native FROST-Server model does not include this concept of data spaces, we implement it by adding Projects to manage and separate data. Hence, this API supports a generic approach to tenancy by organizing data into Projects. These projects act as the data spaces in the FROST-Server, and access is controlled through project-specific roles. A user can only interact with the data within a project if they are assigned a role for that data space. Each user in the FROST-Server must have a specific UserProjectRole, which defines their permissions to read, write, or administer data within that data space.

Swagger Doc

A Swagger documentation is provided alongside this API description, detailing everything you need to work with the API.

Additional Documentation

For more information, please see the following detailed docs:

• Data Model
• Basic Requests
• Tailoring Responses
• Filtering Entities
• Expanding Entities
• Example Queries

Examples

Before executing the following examples, an access token must be created. Please refer to the guide: How to Get an Access Token.

Tip: All cURL commands provided can be copied into Postman for easy testing.

Create a Thing

This example demonstrates how to create a new Thing in the SensorThings API:

curl --location 'https://api.civitas-core.de/context/sensorthings/v1.1/Things' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access token>' \
--data-raw '{
    "name": "Weather Station",
    "description": "A weather station located in Berlin",
    "properties": {
        "location": "Berlin"
    }
}'

Create a Datastream

This example shows how to create a Datastream for a Thing, linking it to a Sensor and an Observed Property:

curl --location 'https://api.civitas-core.de/context/sensorthings/v1.1/Datastreams' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access token>' \
--data-raw '{
    "name": "Temperature Stream",
    "description": "Temperature readings from the weather station",
    "Thing": {
        "@iot.id": <Thing_ID>
    },
    "ObservedProperty": {
        "@iot.id": <ObservedProperty_ID>
    },
    "Sensor": {
        "@iot.id": <Sensor_ID>
    },
    "unitOfMeasurement": {
        "name": "Degree Celsius",
        "symbol": "°C",
        "definition": "http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#DegreeCelsius"
    }
}'