Down-sampled data is a great way of improving performance of retrieving data. Raw data in the BACE system is aggregated per minute, hour and day for this reason. In general we recommend the data-downsampledendpoint for accessing data. This endpoint is the most high performing endpoint for data polling. It is excellent for graphing and visualisation purposes.
A list of all downsampled endpoints accessible by user can be retrieved as follows:
By default you will receive aggregated data per day from the device. In order to get more precise data we should request a smaller chunks of time, like so:
Because the time interval the data was requested over was more than a day in this case, the endpoint responded with hour aggregates. The precision of the data depends, i.e. the aggregation period is determined by the time interval data is requested over. The smaller the time interval, the more precise the data will be. The logic for this is shown in the schematic below.
In order to reduce the resource load on our data storage, a maximum of 100 different datasets can be fetched in one request. A dataset is a unique combination of 1 group, 1 device and 1 datatype. For example, if you have 2 groups with 2 devices each reporting 2 datatypes, that’s 8 distinct datasets. This limitation can be avoided by applying further filtering, explained in the next paragraph.
Filtering
This limitation is avoided by querying smaller chunks of time, or fewer datasets.
With filters you determine what data you want to retrieve. As explained in the previous section the most common onces are id_group or source_device. The table below provides comprehensive overview of parameters that can be applied:
Field
Description
id_container_data_latest
UUID which describes combination of Group, Physical Device and Datatype
id_group
UUID of Group
datatype
Datatype of stored data
source_device
UUID of Physical Device, BACE Cloud have received data from
timestamp_seconds
Timestamp in seconds
min_val
Minimal value
max_val
Maximal value
avg_val
Average value
count_val
Count of downsampled samples
You can also request data between two timestamps to get more data, with a higher resolution.
For example you would be interested in getting temperature data.
To get more detailed information about datatype meaning, you should make GET request, to the Group endpoint with the same ID group, you have used to get data, and expand response on dataTypes
GET https://dashboard.bace-iot.com/api/v2/group/b7624b4d-...?expand=dataTypes
Now when we know, that Temperature has datatype 5000, we can go back to Downsampled data endpoint and find id_container_data_latest, matching our Temperature datatype
Now we can request just Temperature in °C data. We will make our request more specific. In our response from data_downsampled endpoint we can see "timestamp_seconds": 1647993600 - Wed Mar 23 2022 01:00:00 GMT+0100 (Central European Standard Time). Then we will try to request data for 24 hours from this timestamp.
Wed Mar 23 2022 01:00:00 GMT+0100 (Central European Standard Time) - Thu Mar 24 2022 01:00:00 GMT+0100 (Central European Standard Time)
We will make GET request to the same endpoint, but we will add two more filters and will sort received data on a timestamp_seconds - descending.
GET https://dashboard.bace-iot.com/api/v2/data-downsampled?filter[id_container_data_latest]=8faac4b0-…&filter[timestamp_seconds][gt]=1647993600&filter[timestamp_seconds][lt]=1648080000&sort=-timestamp_seconds
Now we can find more data in the response, with 1 value per minute. But we can still see that there is some data in between, because "count_val": 2.
So to get raw data we can make last request.
GET https://dashboard.bace-iot.com/api/v2/data-downsampled?filter[id_container_data_latest]=8faac4b0-a971-47c6-bd16-c80b2ef99299&filter[timestamp_seconds][gt]=1648051080&filter[timestamp_seconds][lt]=1648051140&sort=-timestamp_seconds
In this case we are requesting data between 1648051080 - Wed Mar 23 2022 16:58:00 GMT+0100 (Central European Standard Time) and 1648051140 - Wed Mar 23 2022 16:59:00 GMT+0100 (Central European Standard Time)
We can find, that "count_val": 1 It means there is no more data in between two timestamps
We can also convert timestamp, for example: 1648051122, to datetime: Wed Mar 23 2022 16:58:42 GMT+0100 (Central European Standard Time). And we will see, that time is not rounded 16:58:42
Minimal, maximal & average values are equal
Conclusion
So to get data from aggregated data endpoint we should follow reverse logic.
We start from getting 1 value per day. This is what downsampled_data endpoint returns without timestamp_seconds filters or if time interval is greater than 3 weeks.
If you want to get more accurate data, we are able to request hourly aggregated data, by having our request interval less then 3 weeks and greater than 1 day. It should return 1 value per hour.
Then we can make request and keep interval less than 1 day and greater than 1 hour to get data aggregated to 1 value per minute.
To get raw data, we should make request, where requested interval would be less than 1 hour - it should return raw data
Accessing raw data
The below example shows how the data endpoint can be called with a filter on id_group to access that groups data:
{"name": "Unauthorized","message": "Your request was made with invalid credentials.","code": 0,"status": 401,"type": "yii\\web\\UnauthorizedHttpException"}
From the response we see that this group has three data points from three different datatypes available. If more than 500 datapoints are available in the group the response will be paginated with latest data on top. Please refer to the Advanced Features section to learn about browsing through pages.
Note that both the data endpoint requires you to set a filter. Forgetting the filter will result in an error.
