Retrieving Sensor Data
Granularity refers to the level of detail at which data is retrieved from the API. It determines the size of time intervals into which the data will be aggregated.
Overview
You can use the Twinzo API to retrieve data from sensors. This API allows you to access data from various sensors installed in your system.
Endpoint
GET https://api.twinzo.eu/v3.0/sensors/sensor-data
URL Parameters
sensorId: The unique identifier of the sensor from which you want to retrieve data.
quantities: The type of data you want to retrieve (e.g., temperature, humidity).
start: The start time of the data range you want to retrieve, specified as a Unix timestamp in milliseconds.
stop: The end time of the data range you want to retrieve, specified as a Unix timestamp in milliseconds.
aggregation: (Optional) The aggregation level for the retrieved data. It determines the size of time intervals into which the data will be aggregated. If not specified, the API will use the default aggregation level.
How it Works
When retrieving data from the API, you can specify the time range for which you want data. Additionally, you can specify the aggregation level. The API will then determine the appropriate granularity for the retrieved data based on the duration of the specified time range and the aggregation level.
Aggregation Levels
The API supports the following granularity levels:
For time ranges from 0 seconds to 60 seconds: 1 second (1000 milliseconds)
For time ranges from 1 minute to 1 hour: 1 minute (60000 milliseconds)
For time ranges from 1 hour to 24 hours: 15 minutes (900000 milliseconds)
For time ranges from 1 day to 7 days: 1 hour (3600000 milliseconds)
For time ranges from 7 days to 4 months: 1 day (86400000 milliseconds)
For time ranges from 4 months to 5 years: 1 month (2592000000 milliseconds)
For time ranges greater than 5 years: 1 year (31536000000 milliseconds)
Example
For example, if you request data for a time range of 3 days and specify the aggregation level as "mean", the API will automatically aggregate the data into 1-hour intervals.
Request Example
GET https://api.twinzo.eu/v3.0/sensors/sensor-data?sensorId=1&quantities=temperature&start=0&stop=0&aggregation=mean
Response Example
{
"application/json": {
"Quantity": "Temperature",
"Unit": "Celsius",
"DataType": "Int32",
"Data": [
{
"Timestamp": 1714728346401,
"Value": "30",
"Aggregation": 60000
}
]
}
}
Explanation
In the response example above:
Timestamp: Unix timestamp (in milliseconds) of the data point.
Value: Value of the data point.
Aggregation: Granularity level in milliseconds. In this example, the data is aggregated at a 10-minute granularity level.
Default Granularity
If the time range specified is not covered by any of the defined granularity levels, the API will default to a granularity of 1 minute.
How to Use
When making a request to the API, specify the start and end timestamps of the desired time range and the aggregation level. The API will return the data aggregated according to the determined granularity level.