Skip to content
This repository was archived by the owner on Jun 25, 2024. It is now read-only.

Data API

Jump to bottom
mtomczew edited this page Sep 9, 2014 · 17 revisions

Submit Data

Submit data from specific device.

  • 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 23094823424y2i3uy4i2u3y4i2i43uy
DeviceId URL Slug The ID of the device from which the data is being submitted AA-BB-CC-DD-EE-FF-11 
Request (application/json)
POST /data/{deviceId}
{
    "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 204

Retrieve Data

Retrieve data from specific device.

Param Type Description Value
Authorization HTTP Header Access Token Authorization: Bearer 23094823424y2i3uy4i2u3y4i2i43uy
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)
maxPoints 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 whcih were submitted. 100
metrics array of metrics (data series) to return "metrics": [ {"id": "e3a48caa-e4c5-46bb-951e-8f9d0a4be516","op": "none"}]
queryMeasureLocation true to include the geo location of each measurement, optional, false by default true/false
recipients array of mail message recipients, optional "recipients": [ "example@gmail.com" ]

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|gt|lt>", "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 "60-03-80-96-05-d8" and "22-14-21-48-59-4e":

{
  "from": -86400,
  "targetFilter": {
    "deviceList": ["60-03-80-96-05-d8", "22-14-21-48-59-4e" ]
  },
  "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

Clone this wiki locally