Querying Sensor Data

You are here:
< Back

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:

  1. mac {long integer, device id}
  2. begin {long integer, timestamp}
  3. end {long integer, timestamp}
  4. 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

 

 

 

 

Table of Contents

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.