Skip to content
This repository has been archived by the owner on Jan 8, 2024. It is now read-only.

Data API

Jump to bottom
wagmarcel edited this page Jan 10, 2018 · 1 revision

Submit Data

Submit data from specific device. You can use REST API capabilities to submit data for specific device and it's component. Device and component have to be registered in the cloud before sending observations.

  • Device location (loc) should be sent as [decimal latitude, decimal longitude, height in meters] using WGS84 Datum

  • Attributes should be sent as key:value pairs, where both key and value sent as string

Param Type Description Value
Authorization HTTP Header Device Token Authorization: Bearer eyJ0eX...
Content-Type HTTP Header Type of body content application/json
DeviceId URL Slug The ID of the device from which the data is being submitted AA-BB-CC-DD-EE-FF-11 
POST /data/{deviceId}
POST /data/admin/{deviceId} (Using admin token)
{
    "on": 1354741967799,
    "accountId": "550e8400-e29b-41d4-a716-446655440000",
    "data": [            
        {
            "componentId": "436e7e74-6771-4898-9057-26932f5eb7e1_01",
            "on": 1354741966688,
            "loc": [ 45.5434085, -122.654422, 124.3 ],
            "value": "26.7"
        },
        {
            "componentId": "436e7e74-6771-4898-9057-26932f5eb7e1_01",
            "on": 1354741966699,
            "loc": [ 45.5434085, -122.654422 ],
            "value": "26.8"
        },
        {
            "componentId": "436e7e74-6771-4898-9057-26932f5eb7e1_02",
            "on": 1354741966688,
            "value": "35",
            "attributes": {
                "accuracy": "±2%RH",
                "reading": "digital"
            }
        },
        {
            "componentId": "436e7e74-6771-4898-9057-26932f5eb7e1_03",
            "on": 1354741966677,
            "value": "TWFuIGlzIGRpc3Rpbmd1aXNoZWQsIG5vdCBvbmx5IGJ5IGhpcyByZWFzb24sIGJ1dCBieSB0aGlz
        IHNpbmd1bGFyIHBhc3Npb24gZnJvbSBvdGhlciBhbmltYWxzLCB3aGljaCBpcyBhIGx1c3Qgb2Yg
        dGhlIG1pbmQsIHRoYXQgYnkgYSBwZXJzZXZlcmFuY2Ugb2YgZGVsaWdodCBpbiB0aGUgY29udGlu
        dWVkIGFuZCBpbmRlZmF0aWdhYmxlIGdlbmVyYXRpb24gb2Yga25vd2xlZGdlLCBleGNlZWRzIHRo
        ZSBzaG9ydCB2ZWhlbWVuY2Ugb2YgYW55IGNhcm5hbCBwbGVhc3VyZS4="
        }
    ]   
}

Response 201

Retrieve Data

Retrieve data sent to the Cloud. You can use REST API to request data that was submitted to the Cloud.

For all output types, if request would result in 500 000 samples or more, error 413 - Entity too large will be returned.

Param Type Description Value
Authorization HTTP Header Access Token Authorization: Bearer eyJ0eX...
Content-Type HTTP Header Type of body content application/json
accountId URL Slug The ID of an Account 534da46c820cb9f74a0d3de6 
Request (application/json)
POST accounts/{accountId}/data/search
{
  "from": <milliseconds from epoch>,
  "to": <milliseconds from epoch>,
  "targetFilter": {
    "deviceList": [
      "<ID>"
    ]
  },
  "metrics": [
    {
      "id": "<component_id>",
      "op": "none" // currently it's the only value supported
    }
  ]
}

Request Body

Param Description Value
from beginning of the time window 0
to end of the time window, optional 1407979291860
targetFilter the filter object that will be used to select devices "criteria" | "deviceList" (see definition below)
maxItems number of dataPoints to return. Time period will be devided into this number of windows, and all points in each window will be averaged. DO NOT include maxPoints if you want the actual data values which were submitted. 100
metrics array of metrics (data series) to return - each object in array contains ID that represents the ID of component. Up to 10 such objects can be provided. "metrics": [ {"id": "e3a48caa-e4c5-46bb-951e-8f9d0a4be516","op": "none"}]
queryMeasureLocation true to include the geo location of each measurement, optional, false by default. Cannot be true if maxItems parameter is provided. true/false
recipients array of mail message recipients, optional "recipients": [ "[email protected]" ]

from and to

  • If the to key is omitted, data will be retrieved up to the current time.

  • If the from key is omitted, from will default to zero. If from is positive it will represent the number of milliseconds since Jan-01-1970T00:00:00.000. However, if from is negative, it represents the number of seconds to add to to (because the number is negative, it will decrease to, moving backward in time.

  • Due to a defect (2137), the from parameter must be included. Set it to 0 to represent the epoch.

Here are some examples:

from to meaning
0 missing Return all data available
-86400 missing return all data with timestamps in the last 24 hours (86,400 seconds)
1407979291000 1407980711000 return all observations with timestamps between 2014-08-13T18:21:31.000 UTC and 2014-08-13T18:45:11.000 UTC

Other example using device selection criteria

POST accounts/{accountId}/data/search
{
  "from": <milliseconds from epoch>,
  "to": <milliseconds from epoch>,
  "targetFilter": {
    "criteria": {
      "<device_property>": {"operator" : "<in|neq|eq|gt|lt>", "value":"<value_of_property>"}
    }
  },
  "metrics": [
    {
      "id": "component_id",
      "op": "none"
    }
  ]
}

Download as CSV

POST accounts/{accountId}/data/search?output=csv
{
  "from": <milliseconds from epoch>,
  "to": <milliseconds from epoch>,
  "targetFilter": {
    "criteria": {
      "<device_property>": {"operator" : "<in|neq|eq|like>", "value":"<value_of_property>"}
    }
  },
  "metrics": [
    {
      "id": "component_id",
      "op": "none"
    }
  ]
}

Send by email to selected recipients from this account

POST accounts/{accountId}/data/search?output=email
{
  "from": <milliseconds from epoch>,
  "to": <milliseconds from epoch>,
  "targetFilter": {
    "criteria": {
      "<device_property>": {"operator" : "<in|neq|eq|gt|lt>", "value":"<value_of_property>"}
    }
  },
  "metrics": [
    {
      "id": "component_id",
      "op": "none"
    }
  ],
  "recipients" : [
    "<email1>",
    "<email2>"
  ]
}

####Device List Example

Get observations timestamped in the last 24 hours, from components with ids "e3a48caa-e4c5-46bb-951e-8f9d0a4be516" and "76a95112-2159-4ee6-8e91-6a69b9c51edc" installed on devices with ids "D1" and "D2":

{
  "from": -86400,
  "targetFilter": {
    "deviceList": ["D1", "D2" ]
  },
  "metrics": [
    {
      "id": "e3a48caa-e4c5-46bb-951e-8f9d0a4be516",
      "op": "none"
    },
    {
      "id": "76a95112-2159-4ee6-8e91-6a69b9c51edc",
      "op": "none"
    }
  ]
}

####Criteria Example

"criteria": {
    "tags": {"operator" : "in", "value":["floor1, lab"]}
}

"criteria": {
    "deviceId": {"operator" : "eq", "value":"device_1"}
}

Response

Response 
HTTP 200 OK (application/json)
{
    "from": 1234567890,
    "to": 1234567890,
    "maxPoints": 100,
    "series": [
        {
            "deviceId": "D1",
            "deviceName": "D1",
            "componentId": "e3a48caa-e4c5-46bb-951e-8f9d0a4be516",
            "componentName": "temp",
            "componentType": "temperature.v1.0",                
            "points": [
                {"ts":9874569871, "value":25},
                {"ts":9874569899, "value":24}
            ]
        },
        {
            "deviceId": "D2",
            "deviceName": "D2",
            "componentId": "76a95112-2159-4ee6-8e91-6a69b9c51edc",
            "componentName": "Humidity 1",
            "componentType": "humidity.v1.0",                
            "points": [
                {"ts":9874569871,"value":"55"},
                {"ts":9874569899,"value":"65"}
            ]
        }            
    ]
}

Sample CSV response

Response 
HTTP 200 OK (text/csv)
Device Id,Device Name,Component Id,Component Name,Component Type,Time Stamp,Value
x0n48ix7okmqqzt897fp,Device x0n48ix7okmqqzt897fp,x0n48ix7okmqqzt897fp3,Sensor 3,humidity.v1.0,1407319322625,48.5
x0n48ix7okmqqzt897fp,Device x0n48ix7okmqqzt897fp,x0n48ix7okmqqzt897fp3,Sensor 3,humidity.v1.0,1407319392954,59
x0n48ix7okmqqzt897fp,Device x0n48ix7okmqqzt897fp,x0n48ix7okmqqzt897fp3,Sensor 3,humidity.v1.0,1407319463621,35.6666
x0n48ix7okmqqzt897fp,Device x0n48ix7okmqqzt897fp,x0n48ix7okmqqzt897fp3,Sensor 3,humidity.v1.0,1407319569001,30.5
x0n48ix7okmqqzt897fp,Device x0n48ix7okmqqzt897fp,x0n48ix7okmqqzt897fp3,Sensor 3,humidity.v1.0,1407319638636,53.6666

Table of Contents

Clone this wiki locally