Export Readings v2.0

The "Export Readings" API is used to extract "processed and structured" datastream data from the IoT Monitoring platform. It would typically be used to display a datastream status, trends or to define when a job, or other event, may comments in a third party system.

There are three calls available:

  1. All datastreams at location (details and current status of all datastreams at a specific location)
  2. Datastream details (details and current status of a specific datastream)
  3. Datastream history (historic readings from a specific datastream)

Security

In order to access the API you will need an EMAIL ADDRESS that is registered in the IoT Monitoring platform and an AUTHENTICATION TOKEN which could be obtained by an Urban.io Super User. Please contact Urban.io support to obtain this information.

Restful Interface

This is the preferred method for using the API

To use this interface GET a JSON representation of sensor data.

HTTP Verb

GET

Resource URL

https://iot-rest-prod.urbani.se/api/v1/

Request Headers

X-User-Email: [YOUR EMAIL FROM THE IOT PLATFORM]

X-User-Token: [YOUR TOKEN FROM THE IOT PLATFORM]

Location & Datastream ID's

This API documentation refers to "Location External ID" and "Datastream External ID". Please contact Urban.io support to obtain the desired information.

All Datastreams at Location

Use this API to get details of all datastreams at a specified location.

Request Method

URL: https://iot-rest-prod.urbani.se/api/v1/location/[LOCATION_ID]/datastreams

Response

A JSON array of all datastreams at the specified Location ID.

Example below:


{  
   "datastreams":[  
      {  
         "deployment":{  
            "id":3326,
            "unit_multiplier":"1.0"
         },
         "external_id":"ppdu8FSYZGG47STKue9qqg",
         "id":3191,
         "last_30_days":null,
         "last_30_days_previous":null,
         "last_7_days":null,
         "latest_reading":{  
            "from":"24",
            "label":"UNCOMFORTABLE",
            "recent":true,
            "status":"info_2",
            "timestamp":1527603228,
            "to":"26",
            "value":"25.54"
         },
         "measure":{  
            "id":3,
            "name":"Temperature",
            "requires_multiplier":null,
            "sensor_network":false,
            "series_type":"continuous",
            "units":"˚C"
         },
         "position":"Bedroom",
         "profile":{  
            "custom":false,
            "id":3,
            "logical_datastream_type":{  
               "id":3,
               "name":"Temperature",
               "series_type":"continuous",
               "units":"˚C"
            },
            "name":"Indoor Temperature",
            "operator":{  
               "external_id":"7uHtztXZpBRZvz5Pb6KBtQ",
               "id":8,
               "name":"Urbanise.com"
            },
            "rules":{  
               "ranges":[  
                  {  
                     "from":"-10",
                     "label":"FREEZING",
                     "status":"danger",
                     "to":"10"
                  },
                  {  
                     "from":"10",
                     "label":"COLD",
                     "status":"info",
                     "to":"21"
                  },
                  {  
                     "from":"21",
                     "label":"COMFORTABLE",
                     "status":"ok",
                     "to":"24"
                  },
                  {  
                     "from":"24",
                     "label":"UNCOMFORTABLE",
                     "status":"info_2",
                     "to":"26"
                  },
                  {  
                     "from":"26",
                     "label":"WARM",
                     "status":"warning",
                     "to":"31"
                  },
                  {  
                     "from":"31",
                     "label":"HOT",
                     "status":"danger",
                     "to":"50"
                  }
               ]
            }
         }
      }
            
            


Datastream Details

Use this API to get details of a specific datastream.

Request Method

URL: https://iot-rest-prod.urbani.se/api/v1/datastream/[DATASTREAM_ID]

Response

A JSON response containing details of the specified sensor will be returned.

Example below:

{  
   "datastream":{  
      "deployment":{  
         "id":3326,
         "unit_multiplier":"1.0"
      },
      "external_id":"ppdu8FSYZGG47STKue9qqg",
      "id":3191,
      "last_30_days":24.61454840203798,
      "last_30_days_previous":23.355130172013006,
      "last_7_days":24.71153617443013,
      "latest_reading":{  
         "from":"24",
         "label":"UNCOMFORTABLE",
         "recent":true,
         "status":"info_2",
         "timestamp":1527603828,
         "to":"26",
         "value":"25.59"
      },
      "measure":{  
         "id":3,
         "name":"Temperature",
         "requires_multiplier":null,
         "sensor_network":false,
         "series_type":"continuous",
         "units":"˚C"
      },
      "position":"Bedroom",
      "profile":{  
         "custom":false,
         "id":3,
         "logical_datastream_type":{  
            "id":3,
            "name":"Temperature",
            "series_type":"continuous",
            "units":"˚C"
         },
         "name":"Indoor Temperature",
         "operator":{  
            "external_id":"7uHtztXZpBRZvz5Pb6KBtQ",
            "id":8,
            "name":"Urbanise.com"
         },
         "rules":{  
            "ranges":[  
               {  
                  "from":"-10",
                  "label":"FREEZING",
                  "status":"danger",
                  "to":"10"
               },
               {  
                  "from":"10",
                  "label":"COLD",
                  "status":"info",
                  "to":"21"
               },
               {  
                  "from":"21",
                  "label":"COMFORTABLE",
                  "status":"ok",
                  "to":"24"
               },
               {  
                  "from":"24",
                  "label":"UNCOMFORTABLE",
                  "status":"info_2",
                  "to":"26"
               },
               {  
                  "from":"26",
                  "label":"WARM",
                  "status":"warning",
                  "to":"31"
               },
               {  
                  "from":"31",
                  "label":"HOT",
                  "status":"danger",
                  "to":"50"
               }
            ]
         }
      }
   }
}

Datastream History

Use this API to get historic readings for a specific datastream.

Request Method

URL: https://iot-rest-prod.urbani.se/api/v1/datastream/[DATASTREAM_ID]/readings

Optional Parameters

If no parameters are supplied the API will return the last month of data. However you have the option to use the "period" parameter to return either the last day, week, month or year.

URL: https://iot-rest-prod.urbani.se/api/v1/datastream/[DATASTREAM_ID]/readings?interavl=[PERIOD]

Response

A JSON array containing the historical values of the specified sensor.

Example below:

{  
   "readings":[  
      {  
         "ats":1520281286011,
         "ch":0,
         "di":"74567",
         "dt":"temperature",
         "dts":599000,
         "dv":-0.03999999999999915,
         "dv_per_s":-0.00006677796327211878,
         "ets":1520281290598,
         "gr":"155779",
         "ref":{  
            "c":"t9EcfhCapPdaedDAI1-8Cw",
            "ds":"ppdu8FSYZGG47STKue9qqg",
            "l":"Dgwmfh7T1Bp5AVErH79KYg",
            "m":"Temperature",
            "o":[  
               "-CHh-SoT1EmLFhcIvQdN4w"
            ]
         },
         "scaled":{  
            "dv":-0.04,
            "dv_per_s":0,
            "v":21.03
         },
         "src":"mine",
         "su":"facility",
         "ts":1520280818000,
         "v":21.03,
         "vnd":{  
            "d":{  
               "ai":"43"
            },
            "vdti":2,
            "vi":"M1"
         }
      }
   ]
}


/end