Getting Started

This API provides an interface via the endpoint /context/sensorthings/, allowing you to interact with the FROST-ServerFROST-ServerA server implementation of the OGC SensorThings API for sensor data. On the platform, a data space maps to a project in FROST-Server, and users get access through project-specific roles., an implementation of the OGC SensorThings APISensorThings APIA standard API of the Open Geospatial Consortium (OGC) for sensor data. FROST-Server implements it. standard.

SensorThings APISensorThings APIA standard API of the Open Geospatial Consortium (OGC) for sensor data. FROST-Server implements it. 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-ServerFROST-ServerA server implementation of the OGC SensorThings API for sensor data. On the platform, a data space maps to a project in FROST-Server, and users get access through project-specific roles. 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 KeycloakKeycloakThe component that manages access to data spaces across all platform components. It uses realms, clients, roles, users, and groups, and represents each data space through specific roles. IDM and have an administrator grant you access to a data spaceData spaceA thematic area that contains specific data and resources in different platform components. Data is stored in exactly one data space, and access rights are specific to each data space. Roles within a data space control what users and groups can do in it..

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

The OGC SensorThings APISensorThings APIA standard API of the Open Geospatial Consortium (OGC) for sensor data. FROST-Server implements it. 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-ServerFROST-ServerA server implementation of the OGC SensorThings API for sensor data. On the platform, a data space maps to a project in FROST-Server, and users get access through project-specific roles. model does not include this concept of data spacesData spaceA thematic area that contains specific data and resources in different platform components. Data is stored in exactly one data space, and access rights are specific to each data space. Roles within a data space control what users and groups can do in it., 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 spacesData spaceA thematic area that contains specific data and resources in different platform components. Data is stored in exactly one data space, and access rights are specific to each data space. Roles within a data space control what users and groups can do in it. in the FROST-ServerFROST-ServerA server implementation of the OGC SensorThings API for sensor data. On the platform, a data space maps to a project in FROST-Server, and users get access through project-specific roles., 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 spaceData spaceA thematic area that contains specific data and resources in different platform components. Data is stored in exactly one data space, and access rights are specific to each data space. Roles within a data space control what users and groups can do in it.. Each user in the FROST-ServerFROST-ServerA server implementation of the OGC SensorThings API for sensor data. On the platform, a data space maps to a project in FROST-Server, and users get access through project-specific roles. must have a specific UserProjectRoleUserProjectRoleIn FROST-Server, the assignment of a role to a user within a specific project. It governs the ability of the user to read, write, or manage the sensor data and related entities of that project., which defines their permissions to read, write, or administer data within that data spaceData spaceA thematic area that contains specific data and resources in different platform components. Data is stored in exactly one data space, and access rights are specific to each data space. Roles within a data space control what users and groups can do in it..

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 APISensorThings APIA standard API of the Open Geospatial Consortium (OGC) for sensor data. FROST-Server implements it.:

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"
    }
}'