Reporting API Reference

By using reporting you can query the telemetry data recorded by Devices. Data can be extracted at device level or at network level. In the latter case telemetry data for all devices that are directly under a network will be returned. Recording telemetry data is done through sinks. There are two basic types of sinks that can record telemetry data: current data sinks and time series sinks. In case of current data sinks the latest data will override the previous data in case of any device while time series sinks will store all telemetry data arrived in a time series format so the history of measurements can be reached later.
In the following description you will see some placeholders:

  • <APIURL>: the full url root of the API. Like api.thriot.io/reporting
  • <DEVICEID>: 32 characters long unique identifier for device
  • <NETWORKID>: 32 characters long unique identifier for device
  • <APIKEY>: 32 characters long crypto-safe random key
  • <SINKTYPE>: 1 = current data, 2 = time series

Device-level reports

Get available sinks
Description Get the available sinks that can be used to query telemetry data either in current data or in time series mode.
Url
<APIURL>/v1/devices/sinks
Verb GET
Auth header
X-DeviceId: <DEVICEID>
X-ApiKey: <APIKEY>

The ApiKey can be the device key of the device, the network key of any of the container networks, or the api key of the container service.

Response object
[{
 "SinkName": "<NAME>",
 "SinkType": <SINKTYPE>
}, ...]
HTTP Response code 200 (Ok)
Error codes 401 (Unauthorized): bad authentication parameters passed
503 (Temporary unavailable): Call throttled

 

Get current data in JSON
Description Get the latest recorded data for a device in JSON format
Url
<APIURL>/v1/devices/json/<SINKNAME>

Ensure to UrlEncode the SinkName before adding it to the request Url.

Verb GET
Auth header
X-DeviceId: <DEVICEID>
X-ApiKey: <APIKEY>

The ApiKey can be the device key of the device, the network key of any of the container networks, or the api key of the container service.

Response object
{
 "Devices": [{
   "DeviceId": "<DEVICEID>",
   "Name": "<DEVICENAME>",
   "Timestamp": <LONG>,
   "Payload": "<PAYLOAD>"
 }, ...]
}

In this call there is at most 1 record in the Devices list. The Timestamp is a UNIX timestamp (seconds elapsed since 1970.1.1).

HTTP Response code 200 (Ok)
Error codes 401 (Unauthorized): bad authentication parameters passed
503 (Temporary unavailable): Call throttled

 

Get time series data in JSON
Description Get the time series data for a device in JSON format for a given day
Url
<APIURL>/v1/devices/json/<SINKNAME>/<TIMESTAMP>

Ensure to UrlEncode the SinkName before adding it to the request Url.  Timestamp contains a time value in the day we want to query the time series data. The time is in UNIX format (seconds elapsed since 1970.1.1). The time stamp can be anywhere in the day of interest.

Verb GET
Auth header
X-DeviceId: <DEVICEID>
X-ApiKey: <APIKEY>

The ApiKey can be the device key of the device, the network key of any of the container networks, or the api key of the container service.

Response object
{
 "Devices": [{
   "DeviceId": "<DEVICEID>",
   "Name": "<DEVICENAME>",
   "Data": [{
       "Timestamp": <LONG>,
       "Payload": "<PAYLOAD>"
   }, ...]
 }, ...]
}

The Timestamp is a UNIX timestamp (seconds elapsed since 1970.1.1).

HTTP Response code 200 (Ok)
Error codes 401 (Unauthorized): bad authentication parameters passed
503 (Temporary unavailable): Call throttled

 

Get current data in CSV
Description Get the latest recorded data for a device in CSV format
Url
<APIURL>/v1/devices/csv/<SINKNAME>

Ensure to UrlEncode the SinkName before adding it to the request Url.

Verb GET
Auth header
X-DeviceId: <DEVICEID>
X-ApiKey: <APIKEY>

The ApiKey can be the device key of the device, the network key of any of the container networks, or the api key of the container service.

Response object  CSV format response with deviceid, device name, timestamp and property values. The Timestamp is a UNIX timestamp (seconds elapsed since 1970.1.1).
HTTP Response code 200 (Ok)
Error codes 401 (Unauthorized): bad authentication parameters passed
503 (Temporary unavailable): Call throttled

 

Get time series data in CSV
Description Get the time series data for a device in CSV format for a given day
Url
<APIURL>/v1/devices/csv/<SINKNAME>/<TIMESTAMP>

Ensure to UrlEncode the SinkName before adding it to the request Url. Timestamp contains a time value in the day we want to query the time series data. The time is in UNIX format (seconds elapsed since 1970.1.1). The time stamp can be anywhere in the day of interest.

Verb GET
Auth header
X-DeviceId: <DEVICEID>
X-ApiKey: <APIKEY>

The ApiKey can be the device key of the device, the network key of any of the container networks, or the api key of the container service.

Response object CSV format response with deviceid, device name, timestamp and property values. The Timestamp is a UNIX timestamp (seconds elapsed since 1970.1.1).
HTTP Response code 200 (Ok)
Error codes 401 (Unauthorized): bad authentication parameters passed
503 (Temporary unavailable): Call throttled

 

Network-level reports

Get available sinks
Description Get the available sinks that can be used to query telemetry data either in current data or in time series mode.
Url
<APIURL>/v1/networks/sinks
Verb GET
Auth header
X-NetworkId: <NETWORKID>
X-ApiKey: <APIKEY>

The ApiKey can be the network key of the network, the network key of any of the container networks, or the api key of the container service.

Response object
[{
 "SinkName": "<NAME>",
 "SinkType": <SINKTYPE>
}, ...]
HTTP Response code 200 (Ok)
Error codes 401 (Unauthorized): bad authentication parameters passed
503 (Temporary unavailable): Call throttled

 

Get current data in JSON
Description Get the latest recorded data for all the devices in a network in JSON format
Url
<APIURL>/v1/networks/json/<SINKNAME>

Ensure to UrlEncode the SinkName before adding it to the request Url.

Verb GET
Auth header
X-NetworkId: <NETWORKID>
X-ApiKey: <APIKEY>

The ApiKey can be the network key of the network, the network key of any of the container networks, or the api key of the container service.

Response object
{
 "Devices": [{
   "DeviceId": "<DEVICEID>",
   "Name": "<DEVICENAME>",
   "Timestamp": <LONG>,
   "Payload": "<PAYLOAD>"
 }, ...]
}

The Timestamp is a UNIX timestamp (seconds elapsed since 1970.1.1).

HTTP Response code 200 (Ok)
Error codes 401 (Unauthorized): bad authentication parameters passed
503 (Temporary unavailable): Call throttled

 

Get time series data in JSON
Description Get the time series data for all the devices in a network in JSON format for a given day
Url
<APIURL>/v1/networks/json/<SINKNAME>/<TIMESTAMP>

Ensure to UrlEncode the SinkName before adding it to the request Url. Timestamp contains a time value in the day we want to query the time series data. The time is in UNIX format (seconds elapsed since 1970.1.1). The time stamp can be anywhere in the day of interest.

Verb GET
Auth header
X-NetworkId: <NETWORKID>
X-ApiKey: <APIKEY>

The ApiKey can be the network key of the network, the network key of any of the container networks, or the api key of the container service.

Response object
{
 "Devices": [{
   "DeviceId": "<DEVICEID>",
   "Name": "<DEVICENAME>",
   "Data": [{
       "Timestamp": <LONG>,
       "Payload": "<PAYLOAD>"
   }, ...]
 }, ...]
}

The Timestamp is a UNIX timestamp (seconds elapsed since 1970.1.1).

HTTP Response code 200 (Ok)
Error codes 401 (Unauthorized): bad authentication parameters passed
503 (Temporary unavailable): Call throttled

 

Get current data in CSV
Description Get the latest recorded data for all the devices in a network in CSV format
Url
<APIURL>/v1/networks/csv/<SINKNAME>

Ensure to UrlEncode the SinkName before adding it to the request Url.

Verb GET
Auth header
X-NetworkId: <NETWORKID>
X-ApiKey: <APIKEY>

The ApiKey can be the network key of the network, the network key of any of the container networks, or the api key of the container service.

Response object CSV format response with deviceid, device name, timestamp and property values. The Timestamp is a UNIX timestamp (seconds elapsed since 1970.1.1).
HTTP Response code 200 (Ok)
Error codes 401 (Unauthorized): bad authentication parameters passed
503 (Temporary unavailable): Call throttled

 

Get time series data in CSV
Description Get the time series data for all the devices in a network in CSV format for a given day
Url
<APIURL>/v1/networks/csv/<SINKNAME>/<TIMESTAMP>

Ensure to UrlEncode the SinkName before adding it to the request Url. Timestamp contains a time value in the day we want to query the time series data. The time is in UNIX format (seconds elapsed since 1970.1.1). The time stamp can be anywhere in the day of interest.

Verb GET
Auth header
X-NetworkId: <NETWORKID>
X-ApiKey: <APIKEY>

The ApiKey can be the network key of the network, the network key of any of the container networks, or the api key of the container service.

Response object CSV format response with deviceid, device name, timestamp and property values. The Timestamp is a UNIX timestamp (seconds elapsed since 1970.1.1).
HTTP Response code 200 (Ok)
Error codes 401 (Unauthorized): bad authentication parameters passed
503 (Temporary unavailable): Call throttled

 

Advertisements