Querying Sensor Data
In this article, we’ll explore how to query data from a Sensor via the REST API. The main query endpoint contains a wide variety of parameters, many of which are optional.
We’ll start with a basic data queries and in later articles, expand on the options available.
Latest Sensor Data
Query the latest data from the high-speed cache. This method provides you with a low-latency, high-speed method to get the latest readings from one Device or a large batch of Devices. This method is suitable for low interval polling routines :
URL: https://iot.aretas.ca/rest/sensorreport/latest
HTTP Method: POST
Auth Required: Yes
Body: JSON (application/json)
Parameters: A JSON represented list of MAC/Device IDs
Content-Type: application/json
Response: A list of SensorReport Objects
Example Result:
[
{"data":0,"mac":1080679464,"timestamp":1574190007361,"type":33},
{"data":0,"mac":1080679464,"timestamp":1574190007536,"type":34},
{"data":396,"mac":1080679464,"timestamp":1574190007723,"type":181},
{"data":15.742,"mac":1080679464,"timestamp":1574190003186,"type":246},
{"data":58.743,"mac":1080679464,"timestamp":1574190003011,"type":248},
{"data":0,"mac":1080679464,"timestamp":1574190007171,"type":32},
{"data":43.4,"mac":1082666794,"timestamp":1574190050764,"type":248},
{"data":20.32,"mac":1082666794,"timestamp":1574190050949,"type":246}
]
The received data contains an array of SensorReadings. A Sensor reading contains the following fields:
Field: data = the sensor data
Field: mac = the device address / id / mac
Field: timestamp = the UNIX Epoch timestamp when the sensor reading was acquired
Field: type = the sensor type
GitHub example:
https://github.com/AretasSensorNetworks/APIExamples/blob/master/javascript/latest-sensor-data.html
Sensor Type Metadata
Sensor data and other data is exchanged with the API categorized by Type. The Type can ultimately be anything (a gas concentration, door switch, light level, etc). The API contains many pre-defined Types that allow you to maintain naming and display consistency (labels, colors for charting etc.) across your apps. Most importantly, the Sensor Type metadata maps names / labels to sensor types (e.g. maps the internal number to a user friendly name).
URL: https://iot.aretas.ca/rest/sensortype/list
HTTP Method: GET
Auth Required: Yes
Body: JSON (application/json)
Parameters: enabled {true|false}
Content-Type: application/json
Response: A list of SensorReport Objects
Example Result:
[{
"charCode": "SO2",
"charting": false,
"display": true,
"enabled": true,
"gasStatsSupported": true,
"label": "Sulphur Dioxide",
"sensorColor": "0x0",
"sensorGasFormula": "SO2",
"type": 176,
"units": "ppm"
}, {
"charCode": "SO2_HIGH",
"charting": false,
"display": true,
"enabled": true,
"gasStatsSupported": true,
"label": "Sulphur Dioxide",
"sensorColor": "0x0",
"sensorGasFormula": "SO2",
"type": 178,
"units": "ppm"
}, {
"charCode": "CO2",
"charting": true,
"display": true,
"enabled": true,
"gasStatsSupported": true,
"label": "Carbon Dioxide 2",
"sensorColor": "0xFF9667",
"sensorGasFormula": "CO2",
"type": 180,
"units": "ppm"
}, {
"charCode": "CO2",
"charting": true,
"display": true,
"enabled": true,
"gasStatsSupported": true,
"label": "Carbon Dioxide",
"sensorColor": "0xFF5407",
"sensorGasFormula": "CO2",
"type": 181,
"units": "ppm"
}, {
"charCode": "CO2E",
"charting": true,
"display": true,
"enabled": true,
"gasStatsSupported": true,
"label": "Carbon Dioxide Equivalent",
"sensorColor": "0x35D4A0",
"sensorGasFormula": "CO2",
"type": 182,
"units": "ppm"
}]
GitHub Example:
https://github.com/AretasSensorNetworks/APIExamples/blob/master/javascript/sensortype-list.html
Querying Time Series Data
The main Sensor Data Query endpoints have many optional parameters. We’ll start by demonstrating a basic data query and then in future articles, we will demonstrate more advanced features.
Note: Due to the very large amount of data sent for long queries, the JSON Response Object structure is minimized somewhat (only contains the timestamp, type and data). Therefore it’s necessary to tokenize the requests for any asynchronous languages. The token is usually the Device ID / MAC. When the server successfully executes the query and returns the data, the Device ID / MAC will be included in the Response Headers.
URL: https://iot.aretas.ca/rest/sensordata/byrange
HTTP Method: GET
Auth Required: Yes
Parameters: Query Params
Minimum required query parameters include:
- mac {long integer, device id}
- begin {long integer, timestamp}
- end {long integer, timestamp}
- limit {long integer, maximum number of records to fetch}
Content-Type: application/json
Response: A list of SensorDatum Objects
Sample Results:
[{
"data": 68.23,
"timestamp": 1574197342803,
"type": 248
}, {
"data": 22.09,
"timestamp": 1574197343064,
"type": 246
}, {
"data": 0,
"timestamp": 1574197345045,
"type": 32
}, {
"data": 0,
"timestamp": 1574197345239,
"type": 33
}, {
"data": 0,
"timestamp": 1574197345424,
"type": 34
}, {
"data": 2096,
"timestamp": 1574197347309,
"type": 182
}, {
"data": 258,
"timestamp": 1574197347487,
"type": 96
}, {
"data": 68.24,
"timestamp": 1574197464620,
"type": 248
}, {
"data": 22.13,
"timestamp": 1574197465126,
"type": 246
}, {
"data": 0,
"timestamp": 1574197468806,
"type": 32
}, {
"data": 0,
"timestamp": 1574197469076,
"type": 33
}]
Sample Javascript Ajax call to query the data store:
//8 hour interval
let end = Date.now();
let begin = end - (8 * 60 * 60 * 1000);
//construct an object with the required query parameters
//change the MAC address to the device you'd like to query
let queryData = {
mac: 1,
begin: begin,
end: end,
limit: 1000000
}
$.ajax({
beforeSend: function (xhr) {
xhr.setRequestHeader("Authorization", "Bearer " + bearerToken);
//this is where the token is added to the Request Headers
xhr.setRequestHeader("X-AIR-Token", queryData.mac);
},
dataType: "json",
type: "GET",
url: "http://iot.aretas.ca/rest/sensordata/byrange",
//traditional: true,
data: queryData,
success: function (data, status, xhr) {
//extract the token from the response to match up the MAC with the query results
let macToken = xhr.getResponseHeader("X-AIR-Token");
console.log(data);
},
error: function (error) {
console.log("Failed to query data");
console.log(error);
},
complete: function () {
}
});
GitHub Example:
https://github.com/AretasSensorNetworks/APIExamples/blob/master/javascript/query-sensor-data.html
0 Comments