CubeSensors API Docs

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.

Endpoints

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

Authentication

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:

  1. Get a request token by issuing a signed request to http://api.cubesensors.com/auth/request_token, specifying the oauth_callback at which your app handles authorization responses.
  2. Redirect the user to the authorization URL http://api.cubesensors.com/auth/authorize?oauth_token=request token.
  3. When the user allows/denies access, their browser redirect to oauth_callback with an oauth_verifier and oauth_token. If you set oauth_callback to oob, the user is instructed to copy the verifier manually into your app.
  4. You can now obtain an access token by issuing a signed request to http://api.cubesensors.com/auth/access_token including the oauth_verifier.
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.

Response format

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"
	]
}

Limitations

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

Resources

You can currently get the list of the devices you have access to, their current data and their history.

List Devices

GET /v1/devices/

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]"

Device Info

GET /v1/devices/[device id]

Fetch device info for a specific device.

session.get('%s/devices/%s' % (RES, device_id)).json()
{
	"ok": true, 
	"device": {
		"type": "cube", 
		"uid": "[device id]",
		"extra": {
			"name": "[device name]",
			"roomtype": "[room type]"
		}
	}
}

Current state

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.

Field specifications

  • "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 signal
session.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"
	]
}

Device history

GET /v1/devices/[device id]/span

Arguments

start
span start (ISO formatted datetime, default now - 1 day)
end
span end (ISO formatted datetime, default now)
resolution
resolution in minutes (positive integer, default 1)

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"
	]
}

API mailing list

Join our API support Google Group for all developer news and questions.