Introduction
This is the documentation for the CubeSensors API that is currently still in development. You can call it Alpha.
The API should be easy to use. If it's not, contact us.
This is the documentation for the CubeSensors API that is currently still in development. You can call it Alpha.
The API should be easy to use. If it's not, contact us.
You will find the resources at http://api.cubesensors.com/v1/
and the authentication at http://api.cubesensors.com/auth/.
ROOT = 'http://api.cubesensors.com' AUTH = '%s/auth' % ROOT RES = '%s/v1' % ROOT
We're using OAuth 1.0a for authentication. This means that you get a oauth_consumer_key
and oauth_consumer_secret
for your app and to access resources of a user you first need to get their authorization.
To get your key and secret, send us an email with your existing CubeSensors account username (email). Once we enable developer rights for your account, you'll see a new section called Your apps on your CubeSensors Dashboard and a demo app with your key and secret.
from rauth import OAuth1Service CONSUMER_KEY = '[consumer key]' CONSUMER_SECRET = 'NEVER EXPOSE/SHARE YOUR CONSUMER SECRET' cbsr = OAuth1Service( consumer_key=CONSUMER_KEY, consumer_secret=CONSUMER_SECRET, access_token_url='%s/access_token' % AUTH, authorize_url='%s/authorize' % AUTH, request_token_url='%s/request_token' % AUTH, base_url='%s/' % RES)
A short overview:
oob
, the user is instructed to copy the verifier manually into your app.request_token, request_token_secret = cbsr.get_request_token( params={"oauth_callback":"oob"}) authorize_url = cbsr.get_authorize_url(request_token) # redirect user to authorize_url # handle authorization - save oauth_verifier access_token, access_token_secret = cbsr.get_access_token( request_token, request_token_secret, method="POST", params={"oauth_verifier": oauth_verifier})
After you have the access_token you can issue signed requests on the resource endpoints.
The only format this API knows is JSON and it's returned with a Content-Type of application/json
. It does support JSONP when callback argument is specified - in this case the Content-Type is application/javascript
.
Since the API is currently read-only, all request on resources made to the API should be GET request.
session = OAuth1Session( CONSUMER_KEY, CONSUMER_SECRET, access_token=access_token, access_token_secret=access_token_secret) session.get('%s/' % RES).json()
The basic successful response includes only a status indicator ok
and data.
{ "ok": true, // data }
When getting measurements, the response will include a results array that will hold results and a field_list array that will define the result fields.
{ "ok": true, "results": [ [field values, ...] ], "field_list": [field name, ...] }
An error will be served with the appropriate HTTP status code, have ok
set to false, the HTTP code
repeated and an errors
array.
{ "ok": false, "code": 404, "errors": [ "Nothing found at this URL" ] }
Requests to the API are limited. By default we limit request to 10 per minute per cube and 1600 per 24 hours per cube. All limitations are rolling - they don't reset at full minute or hour.
You can check your limitations on every request by inspecting the headers:
X-Rate-Limit-Minute-Limit: 10 X-Rate-Limit-Minute-Remaining: 9 X-Rate-Limit-Day-Limit: 1600 X-Rate-Limit-Day-Remaining: 1599
You can currently get the list of the devices you have access to, their current data and their history.
List devices to see which devices the user gave you access to. The response will include a device id
, a name and a device type (only supported value "cube").
session.get('%s/devices/' % RES).json() { "ok": true, "devices": [ { "type": "cube", "uid": "[device id]", "extra": { "name": "[device name]", "roomtype": "[room type]" } }, ... ] } device_id = "[device id]"
session.get('%s/devices/%s' % (RES, device_id)).json() { "ok": true, "device": { "type": "cube", "uid": "[device id]", "extra": { "name": "[device name]", "roomtype": "[room type]" } } }
GET /v1/devices/[device id]/current
Get current measurements from a device. It will return the last measurements received by our server that is no more than 15 minutes old.
The measurements are all processed to human values, but the fields might change in the future.
"time"
: returned in UTC in the format year-month-dayThour:minute:secondZ (example: "2013-09-27T01:06:17Z")"temp"
: temperature in °C * 100 (example: 2130
means 21.30°C)"pressure"
: barometric pressure in mbar"humidity"
: relative humidity in % (example: 45
means 45% relative humidity)"voc"
: amount of VOC gases in the air in ppm"light"
: measured in lux"noise"
: legacy noise readings in RMS; should return null for Cubes with the latest firmware"noisedba"
: noise readings in dBA, which were introduced as part of the Sleep update and will be used in all future firmware versions"battery"
: fullness of battery in %"shake"
: either true or false, indicates whether the Cube has recently been shaken or not"cable"
: either true or false, indicates whether the Cube is on cable and thus charging or not"voc_resistance"
: raw resistance values from the VOC sensor"rssi"
: wireless signal strength indicator (RSSI), the higher the number (closer to 0), the stronger the signalsession.get('%s/devices/%s/current' % (RES, device_id)).json() { "ok": true, "results": [ [ "2013-09-27T01:06:17Z", 3119, 982, 45, 563, 1, null, 45, 75, false, false, 84089, -52 ] ], "field_list": [ "time", "temp", "pressure", "humidity", "voc", "light", "noise", "noisedba", "battery", "shake", "cable", "voc_resistance", "rssi" ] }
GET /v1/devices/[device id]/span
Get measurements for a device during a defined span, ordered so that the last measurement is the first in results.
The measurements are all processed to human values, but the fields might change in the future.
The span datetimes need to be specified with seconds and either without timezone information or with a UTC timezone (Z or +00:00).
session.get('%s/devices/%s/span' % (RES, device_id)).json() { "ok": true, "results": [ [ "2013-09-27T01:06:17Z", 3119, 982, 45, 563, 1, null, 45, 75, false, false, 84089, -52 ], ... ], "field_list": [ "time", "temp", "pressure", "humidity", "voc", "light", "noise", "noisedba", "battery", "shake", "cable", "voc_resistance", "rssi" ] }
Join our API support Google Group for all developer news and questions.