Data API V1.0
Click on the following link to open the Saveris Data API documentation.
The DATA API provides RESTful calls to an interface to retrieve data about HCCP or monitoring information. It is designed for developers who want to interact with the data programmatically.
The API is built using the OpenAPI 3.0.0 specification and follows the REST architectural style. It uses JSON for data exchange and supports standard HTTP response codes for successful and unsuccessful requests.
API Details
- API Version: 1.0
- License: Apache 2.0
For the terms of service, please visit Testo's website.
Base URL
The URL for this API is: https://data-api.REGION.ENV.savr.saveris.net/v1
The REGION
and ENV
in the URL should be replaced with the specific region and environment you are using. There are two environments available: "i" for integration and testing, and "p" for production. Furthermore we have three regions: "eu" for europe, "am" for america and "ap" for the apac region.
Security
The Data API uses Bearer token authentication. You should acquire a token and use it to authenticate your requests.
To get a token you need to authenticate using a /token
endpoint of the Data API. Here you will just need to send your username and password in the body and you will receive the idToken
.
API Endpoints
The API has several endpoints:
-
asynchronous
/measurements
: This endpoint supports the POST, GET and OPTIONS methods to retrieve a list of your measurements in a specific timeframe. -
asynchronous
/alarms
: This endpoint supports the POST, GET and OPTIONS methods to retrieve a list of alarms in a timeframe. -
asynchronous
/tasks
: This endpoint supports the POST, GET and OPTIONS methods to retrieve a list of all executed tasks items in a given timeframe. -
/devices/properties
: This endpoint supports the GET and OPTIONS methods to retrieve a list of your devices, sensors and channels including their properties. -
/devices/status
: This endpoint supports the GET and OPTIONS methods to retrieve a list of your devices, sensors and their status. This includes battery level and wifi level. -
/tenants
: This endpoint supports the GET and OPTIONS methods to retrieve a list of the tenants you are connected to. -
/equipments
: This endpoint supports the GET and OPTIONS methods to retrieve a list of all equipment.
Endpoints with the Asynchronous
tag are asynchronous and have a special request flow to them (see section below).
Get data from asynchronous endpoints
Request Flow
-
Authenticate yourself against the API.
-
Send a POST request to
/endpoint
with optional parameters like the timeframe you are interested in and get a UUID of the request. -
The user can now check the request status and results using the
/endpoint/request_uuid
API endpoint. -
When the request status is
Completed
, the user gets the data urls to the dataset. -
Download the dataset from the data URLs.
Requesting data
To request data, send a POST request to https://data-api.REGION.ENV.savr.saveris.net/v1/endpoint
with the Authorization
header set to Bearer IdToken
obtained in the /v1/token
endpoint (see Security section). The response will include a RequestUUID
field, which you will use to check the status of your request:
{
"Status": "Submitted",
"RequestUUID: ": "your-random-uuid"
}
Checking request status and retrieving the dataset
To check the status of your request and retrieve the data, send a GET request to https://data-api.REGION.ENV.savr.saveris.net/v1/endpoint/your-random-uuid
with the Authorization
header set to Bearer IdToken
obtained in the authentication step. The response will contain the status of your request:
{
"Status": "In progress",
"DataURLs: ": []
}
{
"Status": "Completed",
"DataURLs: ": ["your-pre-signed-url", "your-pre-signed-url",...]
}
Get REST calls on the endpoints
To get a list of the needed items, send a GET request to the specific endpoint. The API will return a JSON object containing an array of the items objects. Here is an example for the /equipments
endpoint:
Request:
GET /equipments
{
"equipments": [
{
"tenant_uuid": "string",
"equipment_uuid": "string",
"equipment_title": "string",
"area_uuid": "string",
"area_title": "string",
"equipment_type_title": "string",
"equipment_type_uuid": "string",
"processed_at": "string",
"last_modified_at": "string",
"is_active": "string",
"equipment_parts": [
{
"equipment_parts_uuid": "string",
"equipment_parts_title": "string",
"equipment_parts_purpose_title": "string",
"equipment_parts_purpose_uuid": "string",
"alarm_configurations": [
{
"limit_values_uuid": "string",
"door_contact_delay_in_ms": "number",
"alarm_delay": "number",
"display_unit": "string",
"measuring_rate": "number",
"lower_violation": "number",
"lower_warning": "number",
"upper_violation": "number",
"upper_warning": "number",
"valid_from_time": "number",
"valid_until_time": "number"
}
]
}
]
}
]
}
CORS support
The API supports CORS (Cross-Origin Resource Sharing) to allow cross-domain communication. To enable CORS, the server returns the appropriate headers in the response.
Error Handling
The API uses standard HTTP status codes to indicate success or failure of an API request. In case of an error, the API will return a JSON object containing a status
and a message
property describing the error.
For example:
{
"status": "Error",
"message": "Error Message"
}