NAV

Summary

Definition

Example

GET https://api.smartcitizen.me/v0/

HTTP/1.1 200 OK
{
  "current_user_url": "https://api.smartcitizen.me/v0/me",
  "components_url": "https://api.smartcitizen.me/v0/components",
  "devices_url": "https://api.smartcitizen.me/v0/devices",
  "kits_url": "https://api.smartcitizen.me/v0/kits",
  "measurements_url": "https://api.smartcitizen.me/v0/measurements",
  "sensors_url": "https://api.smartcitizen.me/v0/sensors",
  "users_url": "https://api.smartcitizen.me/v0/users"
}

The Smartcitizen V0 API is a publicly available interface allowing anyone to develop applications and experiments on top of the Smartcitizen platform. For more general and hardware information check the documentation.

SmartCitizen UML

Legacy

The original API is still fully supported by the new backend in order your projects and experiments can keep running on the next months.

However we encourage you to migrate to the new and more powerful API.

Schema

All API access is over HTTPS (with the exception of /add) and accessed via api.smartcitizen.me.

Blank fields are included as null instead of being omitted.

All timestamps are returned in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

Root Endpoint

You can issue a GET request to the root endpoint to get all the endpoint categories that the API supports:

$ curl https://api.smartcitizen.me

JSON-P Callbacks

You can send a ?callback parameter to any GET call to have the results wrapped in a JSON function.

Postman

We recommend that you try our API using Postman, we have created a shared collection that you can import from here https://www.getpostman.com/collections/85a92402907e3cb07759

Versioning

By default, all requests receive the v0 version of the API. We encourage you to explicitly request this version via the URL or the HTTP Accept header.

endpoint
BAD https://api.smartcitizen.me/users
GOOD https://api.smartcitizen.me/v0/users

Accept: application/vnd.smartcitizen; version=0,application/json

Authentication

There are 3 ways you can access the API. OAuth 2.0 is the recommended method.

OAuth 2.0

# OAuth2 Token (sent as a parameter)
$ curl -G https://api.smartcitizen.me/v0/me?access_token=OAUTH-TOKEN

# OAuth2 Token (sent in a header)
$ curl -H "Authorization: token OAUTH-TOKEN" https://api.smartcitizen.me/v0/me

You can obtain a general access_key by sending an authenticated POST request to https://api.smartcitizen.me/v0/sessions

A basic example resides here https://example.smartcitizen.me and its source code is here https://github.com/johnrees/smartcitizen-oauth-example.

Applications can be added here https://id.smartcitizen.me/oauth/applications. Whilst in development this is completely open for public access but this will change. The correct Client ID and Client Secret can be found at https://id.smartcitizen.me/oauth/applications.

HTTP Basic Auth

# Add a base64 encoded hash of 'username:password' in the header
curl 'https://api.smartcitizen.me/v0/me' -H 'Authorization: Basic am9objpzbWFydHBhc3M='

# NOT RECOMMENDED - add username and password in the header
curl 'https://api.smartcitizen.me/v0/me' --user username:password

This method enables you to authenticate your requests with your username and password. Despite using SSL we do not recommend this method as it can be very easy to accidentally share your secret credentials.

Filtering Responses

Pagination

$ curl --include 'https://api.smartcitizen.me/v0/users?page=5'
HTTP/1.1 200 OK
Link: <https://api.smartcitizen.me/v0/users?page=1>; rel="first",
  <https://api.smartcitizen.me/v0/users?page=173>; rel="last",
  <https://api.smartcitizen.me/v0/users?page=6>; rel="next",
  <https://api.smartcitizen.me/v0/users?page=4>; rel="prev"
Total: 4321
Per-Page: 25

Most endpoints that return more than a single result e.g. /v0/users, v0/devices will return blocks of the result set that can be manipulated using the following parameters.

Parameter Default Description
page
integer
1 page
per_page
integer
25 page

The headers will include links to the Total results count, number of results shown Per-Page and first, last, next and previous results.

Example

GET https://api.smartcitizen.me/v0/search?q=barcelona

HTTP/1.1 200 OK
[
{
  "id": 506,
  "type": "Device",
  "name": "Barceloneta Sensor",
  "description": "Barcelona sensor place at a 7th floor in front of the beach. Working on different batteries to have more autonomy outdoors. Next: Solar Panel!",
  "owner_id": 3,
  "owner_username": "tomasdiez",
  "city": "Barcelona",
  "country_code": "ES"
}
...

To search both Users and Devices at the same time you can use the global search endpoint.

Required Parameters

Parameter Description
q
string
Query string

Response

There can be two types of object included in the response array, Devices and Users.

Device Object

Parameter Description
id
integer
Unique ID for the device
name
string
Name of the device
owner_id
integer
Unique ID of the device’s owner
owner_username
string
Unique username of the device’s owner
city
string
City the device is in
country_code
string
Alpha-2 country code of the device

User Object

Parameter Description
id
integer
Unique ID for the user
username
string
Unique username of the user
avatar
string
URL of the user’s avatar
city
string
City the user is in
country_code
string
Alpha-2 country code of the user

Basic Searching

Similar to the pagination, you can filter and sort most responses that return more than one result. This is done with the ransack library.

https://github.com/activerecord-hackery/ransack/wiki/Basic-Searching

Query Type Value Description
/users?q[first_name_eq]=adam string adam Users where first name equals ‘Adam’
/devices?q[owner_id_eq]=1 integer 1 Devices where owner ID equals 1
/sensors?q[id_lt]=100 integer 100 Sensors where ID less than 100
/users?q[username_cont]=sck string sck Users where username contains 'sck’

Keys for devices

Key
id
owner_id
name
description
mac_address
created_at
updated_at
kit_id
geohash
last_recorded_at
uuid
state

Keys for users

Key
id
username
email
created_at
updated_at
city
country_code
url
avatar_url
uuid

Sorting Results

You can order results with the q[sort] parameter

Parameter Value Description
/users?q[sort]=username%20asc
string
username asc Users ordered by username in ASCENDING order
/devices?q[sort]=id%20desc
integer
id desc Devices ordered by id in DESCENDING order

Pretty Printing

# Default Minimal Response
curl "https://api.smartcitizen.me/v0/sensors/10"

{"id":10,"name":"Battery","description":"Custom Circuit","unit":"%","created_at":"2015-02-02T18:18:00.276Z","updated_at":"2015-02-02T18:18:00.276Z"}

# Pretty Response
curl "https://api.smartcitizen.me/v0/sensors/10?pretty=true"

{
  "id" : 10,
  "name" : "Battery",
  "description" : "Custom Circuit",
  "unit" : "%",
  "created_at" : "2015-02-02T18:18:00.276Z",
  "updated_at" : "2015-02-02T18:18:00.276Z"
}

You can format responses so that they are easier to read by adding pretty=true to a request.

Users

Add a User

POST https://api.smartcitizen.me/v0/users

Example

POST https://api.smartcitizen.me/v0/users email=testing@test.com password=testpass username=testinguser

HTTP/1.1 201 Created
{
    "avatar": "http://smartcitizen.s3.amazonaws.com/avatars/default.svg",
    "devices": [],
    "email": "[FILTERED]",
    "id": 3858,
    "joined_at": "2015-07-31T10:20:27Z",
    "location": {
        "city": null,
        "country": null,
        "country_code": null
    },
    "role": "citizen",
    "updated_at": "2015-07-31T10:20:27Z",
    "url": null,
    "username": "testinguser",
    "uuid": null
}

Most actions on the API require authenticated access. To obtain an OAuth 2.0 access_token the first step is to have a user account.

Parameter Required? Description
first_name
string
First name of the user
last_name
string
Last name of the user
email
string
Email address of the user
username
string
Username of the user
password
string
Password of the user
city
string
City where the user is located
country_code
string
2 letter country-code of the user
url
string
Webpage of the user

Get Current User (me)

GET https://api.smartcitizen.me/v0/me

Example

GET https://api.smartcitizen.me/v0/me access_token=9d00b4c027f757ef1c7b254b9f795d1ebd1e04f7a21b01d5a9dfe5f6e37439b5

HTTP/1.1 200 OK
{
  "avatar": "http://images.smartcitizen.me/s100/feca2180/firewatch-4.jpg",
  "devices": [
    {
      "added_at": "2015-07-31T10:11:09Z",
      "description": "new description",
      "id": 1816,
      "kit_id": null,
      "last_reading_at": null,
      "latitude": null,
      "longitude": null,
      "mac_address": "00:0a:95:9d:68:16",
      "name": "my sck",
      "state": "never_published",
      "system_tags": [
        "new",
        "offline"
      ],
      "updated_at": "2015-07-31T10:15:06Z",
      "uuid": "cb480089-c000-4e69-96c0-ad6378f3a537"
    }
  ],
  "email": "john@bitsushi.com",
  "id": 2997,
  "joined_at": "2015-02-02T15:17:28Z",
  "location": {
    "city": "Barcelona",
    "country": "Spain",
    "country_code": "ES"
  },
  "role": "citizen",
  "updated_at": "2015-07-31T10:12:46Z",
  "url": "http://www.google.com",
  "username": "john",
  "uuid": "feca2180-d0dd-49fd-8815-ec59ca6d48f6"
}

Used to retrieve information about the currently authenticated user. Returns a detailed representation of the user.

Parameter Description
id*
integer
Autoincrementing unique ID for the user
uuid*
uuid
Unique ID for the user
first_name
string
First name of the user
last_name
string
Last name of the user
email
string
Email address of the authenticated user, will be [FILTERED] for unauthenticated requests
username*
string
Username of the user
location.city
string
City in which the user is located
location.country_code
string
2 letter country-code of the user
location.country
string
Full country name. Automatically generated from country_code, using this data
url
string
Webpage of the user
avatar*
string
URL to the image that represents the user
devices
array
Array of devices that the user manages on the platform
joined_at*
datetime
The date and time that the user joined the platform
updated_at*
datetime
The date and time that the user updated data on the platform
role*
string
Access privileges of the user, citizen is the default. admin accounts have full access to the platform.

Update Current User

PATCH https://api.smartcitizen.me/v0/me

Example

PATCH https://api.smartcitizen.me/v0/me access_token=9d00b4c027f757ef1c7b254b9f795d1ebd1e04f7a21b01d5a9dfe5f6e37439b5 url=‘http://www.google.com’

HTTP/1.1 200 OK
{
  "avatar": "http://images.smartcitizen.me/s100/feca2180/firewatch-4.jpg",
  "devices": [
    {
      "added_at": "2015-07-31T10:11:09Z",
      "description": null,
      "id": 1816,
      "kit_id": null,
      "last_reading_at": null,
      "latitude": null,
      "longitude": null,
      "mac_address": "00:0a:95:9d:68:16",
      "name": "my sck",
      "state": "never_published",
      "system_tags": [
        "new",
        "offline"
      ],
      "updated_at": "2015-07-31T10:11:09Z",
      "uuid": "cb480089-c000-4e69-96c0-ad6378f3a537"
    }
  ],
  "email": "john@bitsushi.com",
  "id": 2997,
  "joined_at": "2015-02-02T15:17:28Z",
  "location": {
    "city": "Barcelona",
    "country": "Spain",
    "country_code": "ES"
  },
  "role": "citizen",
  "updated_at": "2015-07-31T10:12:46Z",
  "url": "http://www.google.com",
  "username": "john",
  "uuid": "feca2180-d0dd-49fd-8815-ec59ca6d48f6"
}

An authenticated user can update their own details. They have the same parameters used as adding a user

Change an Avatar

PATCH https://api.smartcitizen.me/v0/me/avatar

Example

PATCH https://api.smartcitizen.me/v0/me/avatar access_token=9d00b4c027f757ef1c7b254b9f795d1ebd1e04f7a21b01d5a9dfe5f6e37439b5 filename=new-avatar.jpg

HTTP/1.1 200 OK
{
  "key": "avatars/fec/1armjai.new-avatar.jpg",
  "policy": "eyJleHBpcmF0aW9uIjoiMjAxNS0wNy0zMVQxMDozMToyNloiLCJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJzbWFydGNpdGl6ZW4ifSxbInN0YXJ0cy13aXRoIiwiJGtleSIsImF2YXRhcnMvZmVjLzFhcm1qYWkubmV3LWF2YXRhci5qcGciXSx7ImFjbCI6InB1YmxpYy1yZWFkIn0seyJzdWNjZXNzX2FjdGlvbl9zdGF0dXMiOiIyMDAifSxbImNvbnRlbnQtbGVuZ3RoLXJhbmdlIiwwLDEwNzM3NDE4MjRdXX0=",
  "signature": "eIvTwQf+vPfvZJ/nV/Q1a2L3rJE="
}

Step 1 of 2

Initiate the upload by sending the filename as a `PATCH request

PATCH https://api.smartcitizen.me/v0/me/avatar

Step 2 of 2

POST https://smartcitizen.s3-eu-west-1.amazonaws.com

Parameter Value
file
string
Filedata of the new avatar image
key
string
key from the previous response
policy
string
policy from the previous response
policy
string
signature from the previous response
AWSAccessKeyId
string
AKIAJ753OQI6JPSDCPHA
acl
string
public-read
success_action_status
integer
200

After a successful request, and the image was added to the S3 bucket, the user’s avatar will be automatically changed.

Reset a Password

Example

POST https://api.smartcitizen.me/v0/password_resets?username=testing

HTTP/1.1 200 OK
{
  "message": "Password Reset Instructions Delivered"
}
# password reset email has been sent to user: testing

Step 1 of 4

Initiate the password reset

POST https://api.smartcitizen.me/v0/password_resets?username_or_email=:username

or

POST https://api.smartcitizen.me/v0/password_resets?username_or_email=:email

Step 2 of 4

Email is sent to the relevant user, containing PASSWORD_RESET_TOKEN

Step 3 of 4

Return the User(username=USERNAME) object

POST https://api.smartcitizen.me/v0/password_resets/:password_reset_token

Step 4 of 4

Set the new password

PATCH https://api.smartcitizen.me/v0/password_resets/:password_reset_token?password=:password

Get All Users

GET https://api.smartcitizen.me/v0/users

Example

GET https://api.smartcitizen.me/v0/users

HTTP/1.1 200 OK
[
{
  "id": 1,
  "uuid": "4725977d-0490-4984-b5a4-df2a483a85ae",
  "role": "admin",
  "username": "testing",
  "avatar": "https://images.smartcitizen.me/s100/avatars/472/1arck5q.firewatch-6.jpg",
  "url": null,
  "location": {
    "city": null,
    "country": null,
    "country_code": null
  },
  "joined_at": "2015-01-27T18:43:26Z",
  "updated_at": "2015-07-30T09:59:28Z",
  "email": "[FILTERED]",
  "devices": [
    {
      "id": 1148,
      "uuid": "dd4b6f66-5b51-44d0-a9de-e7fd1999287d",
      "mac_address": "[FILTERED]",
      "name": null,
      "description": null,
      "latitude": 52.3079989,
      "longitude": 4.97154509999996,
      "kit_id": 3,
      "state": "never_published",
      "system_tags": [
        "offline",
        "outdoor"
      ],
      "last_reading_at": null,
      "added_at": "2015-02-02T15:59:49Z",
      "updated_at": "2015-05-25T07:31:28Z"
    },
    {
      "id": 1762,
      "uuid": "f119ff40-348c-4827-b266-06c3a4e5fbe3",
      "mac_address": "[FILTERED]",
      "name": "RyanLim",
      "description": "Tiong Bahru",
      "latitude": 1.28645,
      "longitude": 103.826917,
      "kit_id": 3,
      "state": "never_published",
      "system_tags": [
        "indoor",
        "offline"
      ],
      "last_reading_at": null,
      "added_at": "2015-02-02T15:59:51Z",
      "updated_at": "2015-05-25T07:31:29Z"
    },
    {
      "id": 344,
      "uuid": "c6b1792d-8a0d-44f0-bce3-89cb6819dac5",
      "mac_address": "[FILTERED]",
      "name": "SmartCitizenSk",
      "description": null,
      "latitude": 53.406754,
      "longitude": -2.158843,
      "kit_id": 2,
      "state": "never_published",
      "system_tags": [
        "indoor",
        "offline"
      ],
      "last_reading_at": null,
      "added_at": "2015-02-02T15:59:47Z",
      "updated_at": "2015-05-25T07:31:27Z"
    },
    {
      "id": 1242,
      "uuid": "da84118a-4e49-4c59-baf1-f622a10b69de",
      "mac_address": "[FILTERED]",
      "name": null,
      "description": null,
      "latitude": 52.3079989,
      "longitude": 4.97154509999996,
      "kit_id": 3,
      "state": "never_published",
      "system_tags": [
        "offline",
        "outdoor"
      ],
      "last_reading_at": null,
      "added_at": "2015-02-02T15:59:49Z",
      "updated_at": "2015-05-25T07:31:28Z"
    },
    {
      "id": 860,
      "uuid": "937c78eb-ec19-47c0-a9ad-1be6cec4b8d6",
      "mac_address": "[FILTERED]",
      "name": "Bwired.nl",
      "description": null,
      "latitude": 51.7242901136958,
      "longitude": 5.30086557678224,
      "kit_id": 3,
      "state": "never_published",
      "system_tags": [
        "indoor",
        "offline"
      ],
      "last_reading_at": null,
      "added_at": "2015-02-02T15:59:48Z",
      "updated_at": "2015-05-25T07:31:27Z"
    },
    {
      "id": 1749,
      "uuid": "bb26425d-30ae-4d9b-a6a6-7b828c8ed1ba",
      "mac_address": "[FILTERED]",
      "name": "Yongin1",
      "description": null,
      "latitude": 37.2410864,
      "longitude": 127.1775537,
      "kit_id": 3,
      "state": "never_published",
      "system_tags": [
        "indoor",
        "offline"
      ],
      "last_reading_at": null,
      "added_at": "2015-02-02T15:59:51Z",
      "updated_at": "2015-05-25T07:31:28Z"
    },
    {
      "id": 747,
      "uuid": "42beffb0-76b4-4e75-bbd3-2636c5be90fd",
      "mac_address": "[FILTERED]",
      "name": "AroundMe HQ",
      "description": null,
      "latitude": 45.4319105,
      "longitude": 7.80372020000004,
      "kit_id": 2,
      "state": "never_published",
      "system_tags": [
        "indoor",
        "offline"
      ],
      "last_reading_at": null,
      "added_at": "2015-02-02T15:59:48Z",
      "updated_at": "2015-05-25T07:31:29Z"
    },
    {
      "id": 1149,
      "uuid": "6849e0dd-8265-45b8-8e74-79af064cb092",
      "mac_address": "[FILTERED]",
      "name": "2e kekerstraat",
      "description": null,
      "latitude": 52.3079989,
      "longitude": 4.97154509999996,
      "kit_id": 3,
      "state": "never_published",
      "system_tags": [
        "offline",
        "outdoor"
      ],
      "last_reading_at": null,
      "added_at": "2015-02-02T15:59:49Z",
      "updated_at": "2015-05-25T07:31:29Z"
    },
    {
      "id": 1006,
      "uuid": "cb1d8723-66b0-4cae-95c4-4849e513727b",
      "mac_address": "[FILTERED]",
      "name": "SCARNING",
      "description": null,
      "latitude": 52.6724249,
      "longitude": 0.885390000000029,
      "kit_id": 3,
      "state": "never_published",
      "system_tags": [
        "offline",
        "outdoor"
      ],
      "last_reading_at": null,
      "added_at": "2015-02-02T15:59:49Z",
      "updated_at": "2015-05-25T07:31:29Z"
    },
    {
      "id": 1760,
      "uuid": "63a923c2-508e-4ac5-b90c-73b8b45561fd",
      "mac_address": "[FILTERED]",
      "name": null,
      "description": null,
      "latitude": 1.2800945,
      "longitude": 103.8509491,
      "kit_id": 3,
      "state": "never_published",
      "system_tags": [
        "indoor",
        "offline"
      ],
      "last_reading_at": null,
      "added_at": "2015-02-02T15:59:51Z",
      "updated_at": "2015-05-25T07:31:29Z"
    },
    {
      "id": 605,
      "uuid": "3a86d052-28b4-4ecc-9293-3c5aa40d6a30",
      "mac_address": "[FILTERED]",
      "name": "MySmartCitizenBoard",
      "description": null,
      "latitude": 42.1969689,
      "longitude": -88.0934108,
      "kit_id": 3,
      "state": "never_published",
      "system_tags": [
        "indoor",
        "offline"
      ],
      "last_reading_at": null,
      "added_at": "2015-02-02T15:59:48Z",
      "updated_at": "2015-05-25T07:31:31Z"
    },
    {
      "id": 1473,
      "uuid": "8f7724af-50e8-4967-869c-4ff94e016023",
      "mac_address": "[FILTERED]",
      "name": "Village Green Drive",
      "description": null,
      "latitude": 40.9253764,
      "longitude": -73.0473284,
      "kit_id": 3,
      "state": "never_published",
      "system_tags": [
        "offline",
        "outdoor"
      ],
      "last_reading_at": null,
      "added_at": "2015-02-02T15:59:50Z",
      "updated_at": "2015-05-25T07:31:31Z"
    },
    {
      "id": 1147,
      "uuid": "e211ea4c-580a-410d-9308-a328aae4d98b",
      "mac_address": "[FILTERED]",
      "name": "Guli's Sensors",
      "description": "This is the ultimate SCK",
      "latitude": 46.8037168264815,
      "longitude": -71.2302180070495,
      "kit_id": 3,
      "state": "never_published",
      "system_tags": [
        "indoor",
        "offline"
      ],
      "last_reading_at": null,
      "added_at": "2015-02-02T15:59:49Z",
      "updated_at": "2015-05-25T07:31:31Z"
    },
    {
      "id": 1376,
      "uuid": "0ac3d295-670f-4661-a165-1483ff95bde4",
      "mac_address": "[FILTERED]",
      "name": "KitTest",
      "description": null,
      "latitude": 45.6669011,
      "longitude": 12.243039,
      "kit_id": 3,
      "state": "has_published",
      "system_tags": [
        "indoor",
        "offline"
      ],
      "last_reading_at": "2015-04-27T15:30:20Z",
      "added_at": "2015-02-02T15:59:50Z",
      "updated_at": "2015-05-25T08:43:14Z"
    }
  ]
}
...

This endpoint retrieves all users.

Get a User

GET https://api.smartcitizen.me/v0/users/(:id|:username)

Example

GET https://api.smartcitizen.me/v0/users/2

HTTP/1.1 200 OK
{
  "id": 2,
  "uuid": "fdbc41c4-ba01-4bfc-b850-edda889bff2e",
  "role": "citizen",
  "username": "alex",
  "avatar": "http://smartcitizen.s3.amazonaws.com/avatars/default.svg",
  "url": null,
  "location": {
    "city": null,
    "country": null,
    "country_code": null
  },
  "joined_at": "2015-02-02T15:54:37Z",
  "updated_at": "2015-07-21T12:20:54Z",
  "email": "[FILTERED]",
  "devices": [
    {
      "id": 1357,
      "uuid": "791e06b0-d068-4f62-8701-4e41cf15e38a",
      "mac_address": "[FILTERED]",
      "name": "Citizen Science Kit #1",
      "description": "Test Kit for the Innovation Lab Kosovo, within the event Science for change / Citizen Science.",
      "latitude": 42.5813722,
      "longitude": 20.88935,
      "kit_id": 3,
      "state": "never_published",
      "system_tags": [
        "indoor",
        "offline"
      ],
      "last_reading_at": null,
      "added_at": "2015-02-02T15:59:50Z",
      "updated_at": "2015-05-25T07:31:28Z"
    },
    {
      "id": 1360,
      "uuid": "206296e5-7837-4587-af91-5b782db42135",
      "mac_address": "[FILTERED]",
      "name": "Citizen Science Pristina #2",
      "description": "this kit is to monitor the air quality in the area of Pristina and is part of the science for change initiative",
      "latitude": 42.7145797355173,
      "longitude": 21.1464852426758,
      "kit_id": 3,
      "state": "never_published",
      "system_tags": [
        "indoor",
        "offline"
      ],
      "last_reading_at": null,
      "added_at": "2015-02-02T15:59:50Z",
      "updated_at": "2015-05-25T07:31:28Z"
    },
    {
      "id": 339,
      "uuid": "c7201a30-da4b-4dec-8042-3d30da1b3363",
      "mac_address": "[FILTERED]",
      "name": "Roma Maker Faire",
      "description": "SmartCitizen Kit exhibited in the Maker Faire in Rome\r\n00:06:66:21:17:58",
      "latitude": 41.8343,
      "longitude": 12.473442,
      "kit_id": 2,
      "state": "never_published",
      "system_tags": [
        "indoor",
        "offline"
      ],
      "last_reading_at": null,
      "added_at": "2015-02-02T15:59:47Z",
      "updated_at": "2015-05-25T07:31:28Z"
    },
    {
      "id": 1402,
      "uuid": "ddd06451-b847-4972-965a-96eef438282e",
      "mac_address": "[FILTERED]",
      "name": "test for Fab10",
      "description": "mhdvsajhgdasjhgasdjhg",
      "latitude": 41.3965424157754,
      "longitude": 2.19476096466298,
      "kit_id": 3,
      "state": "never_published",
      "system_tags": [
        "indoor",
        "offline"
      ],
      "last_reading_at": null,
      "added_at": "2015-02-02T15:59:50Z",
      "updated_at": "2015-05-25T07:31:29Z"
    },
    {
      "id": 12,
      "uuid": "21631212-8633-450e-bd44-f36202d864f6",
      "mac_address": "[FILTERED]",
      "name": "Parisien Sensor",
      "description": "Test from Paris waking up",
      "latitude": 48.84676,
      "longitude": 2.41442,
      "kit_id": 2,
      "state": "never_published",
      "system_tags": [
        "offline",
        "outdoor"
      ],
      "last_reading_at": null,
      "added_at": "2015-02-02T15:59:46Z",
      "updated_at": "2015-05-25T07:31:31Z"
    }
  ]
}

This endpoint retrieves a specific user.

URL Parameters

Parameter Description
ID or username The ID or username of the user to retrieve

Devices

World Map of Devices

GET https://api.smartcitizen.me/v0/devices/world_map

Example

GET https://api.smartcitizen.me/v0/devices/world_map

HTTP/1.1 200 OK
[
{
  "id": 1630,
  "name": "IONIAN UNIVERSITY SMART CITIZEN PROJECT TEST ",
  "description": "SMART CITIZEN SENSORS BOARD",
  "owner_id": 2278,
  "owner_username": "gvlachos",
  "latitude": 39.6249838,
  "longitude": 19.9223461,
  "city": "Kérkira",
  "country_code": "GR",
  "kit_id": 3,
  "state": "has_published",
  "system_tags": [
    "indoor",
    "offline"
  ],
  "exposure": "indoor",
  "data": {
    "": "2015-06-25T07:45:03Z",
    "7": 66.875,
    "12": 20.24169189453124,
    "13": 70.262939453125,
    "14": 290.9,
    "15": 20.965,
    "16": 558.478,
    "17": 100.0,
    "18": 4128,
    "21": 2,
    "7_raw": 255,
    "12_raw": 27316,
    "13_raw": 33168,
    "14_raw": 2909,
    "15_raw": 20965,
    "16_raw": 558478,
    "17_raw": 1000,
    "18_raw": 4128
  },
  "added_at": "2015-02-02T15:59:51Z"
}
...

Returns an array with of summarized device objects for displaying on the world map.

Parameter Example Description
id*
integer
1619 Unique ID of the device
name
string
Long Lane, SE1 (new) Name of the device
description
string
An SCK in Southwark Description of the device
owner_id*
integer
848 Unique ID of the device’s owner
owner_username
string
dankarran Unique username of the device’s owner
latitude
decimal
51.4996843 Latitude of the device
longitude
decimal
-0.086883400000033 Longitude of the device
city
string
Southwark City of the device
country_code
string
GB Alpha-2 Country Code of the device
kit_id
integer
3 Kit that the device belongs to
state
string
not_configured See state values table below
system_tags
string array
[‘new’, 'indoor’] See system_tag values table below
data
object
{
7: 50.0,
7_raw: 0,
recorded_at: “2015-04-30T17:56:04.432Z”,
calibrated_at: “2015-04-30T17:56:04.432Z”,
added_at: “2015-04-30T17:56:04.432Z”
}
The latest readings stored for the device. Numerical keys are sensor ids.

So 7 is the calibrated reading of /v0/sensors/7

7_raw is what was posted to the platform.
added_at*
datetime
“2015-04-30T17:56:04.432Z” When the device was added to the platform

Possible values for state

Key Value
not_configured Device has been added to the platform but we do not have its MAC address
never_published Device has been added, we have the MAC but no readings have been received
has_published At least one reading has been recorded, submitted and saved to the platform
archived The device has been temporarily removed from the platform

Possible values for system_tag

String Description
new The device was added to the platform less than 7 days ago
indoor The device is inside
outdoor The device is outside

Add a Device

POST https://api.smartcitizen.me/v0/devices

Example

POST https://api.smartcitizen.me/v0/devices access_token=9d00b4c027f757ef1c7b254b9f795d1ebd1e04f7a21b01d5a9dfe5f6e37439b5 mac_address='00:0a:95:9d:68:16’ name='my sck’

HTTP/1.1 201 Created
{
  "added_at": "2015-07-31T10:11:09Z",
  "data": {
    "added_at": "2015-07-31T10:11:09Z",
    "firmware": "[IGNORE]",
    "location": {
      "city": null,
      "country": null,
      "country_code": null,
      "elevation": null,
      "exposure": null,
      "geohash": null,
      "ip": null,
      "latitude": null,
      "longitude": null
    },
    "recorded_at": "2015-07-31T10:11:09Z",
    "sensors": []
  },
  "description": null,
  "id": 1816,
  "last_reading_at": null,
  "mac_address": "00:0a:95:9d:68:16",
  "name": "my sck",
  "owner": {
    "avatar": "http://images.smartcitizen.me/s100/feca2180/firewatch-4.jpg",
    "device_ids": [
      1816
    ],
    "id": 2997,
    "joined_at": "2015-02-02T15:17:28Z",
    "location": {
      "city": "Barcelona",
      "country": "Spain",
      "country_code": "ES"
    },
    "url": null,
    "username": "john",
    "uuid": "feca2180-d0dd-49fd-8815-ec59ca6d48f6"
  },
  "state": "never_published",
  "system_tags": [
    "new",
    "offline"
  ],
  "updated_at": "2015-07-31T10:11:09Z",
  "uuid": null
}

You must be authenticated to add a device. The currently authenticated user will be registered as the owner of the new device.

Parameter Required? Description
name
string
Name of the device
description
string
Description of the device
mac_address
string
MAC Address of the device
kit_id
integer
Unique ID of the kit for the device
exposure
string
Either indoor or outdoor
latitude
decimal
Latitude of the device
longitude
decimal
Longitude of the device

Update a Device

PATCH https://api.smartcitizen.me/v0/devices/:id

Example

PATCH https://api.smartcitizen.me/v0/devices/1816 access_token=9d00b4c027f757ef1c7b254b9f795d1ebd1e04f7a21b01d5a9dfe5f6e37439b5 description='new description’

HTTP/1.1 200 OK
{
  "added_at": "2015-07-31T10:11:09Z",
  "data": {
    "added_at": "2015-07-31T10:15:06Z",
    "firmware": "[IGNORE]",
    "location": {
      "city": null,
      "country": null,
      "country_code": null,
      "elevation": null,
      "exposure": null,
      "geohash": null,
      "ip": null,
      "latitude": null,
      "longitude": null
    },
    "recorded_at": "2015-07-31T10:15:06Z",
    "sensors": []
  },
  "description": "new description",
  "id": 1816,
  "last_reading_at": null,
  "mac_address": "00:0a:95:9d:68:16",
  "name": "my sck",
  "owner": {
    "avatar": "http://images.smartcitizen.me/s100/feca2180/firewatch-4.jpg",
    "device_ids": [
      1816
    ],
    "id": 2997,
    "joined_at": "2015-02-02T15:17:28Z",
    "location": {
      "city": "Barcelona",
      "country": "Spain",
      "country_code": "ES"
    },
    "url": "http://www.google.com",
    "username": "john",
    "uuid": "feca2180-d0dd-49fd-8815-ec59ca6d48f6"
  },
  "state": "never_published",
  "system_tags": [
    "new",
    "offline"
  ],
  "updated_at": "2015-07-31T10:15:06Z",
  "uuid": "cb480089-c000-4e69-96c0-ad6378f3a537"
}

You must be authenticated and registered as the device’s owner if you wish to update a device.

Parameter Example Description
id
integer
2 Unique ID of the device
name
string
Beach SCK Name of the device
description
string
A Smart Citizen on the Beach Description of the device
mac_address
string
00:1C:B3:09:85:15 MAC Address of the device
kit_id
integer
3 Unique ID of the kit for the device
user_tags
string
A comma-seperated list of tag names more info
exposure
string
Either indoor or outdoor
latitude
decimal
41.401108 Latitude of the device
longitude
decimal
2.215319 Longitude of the device

Get a Device

GET https://api.smartcitizen.me/v0/devices/:id

Example

GET https://api.smartcitizen.me/v0/devices/1616

HTTP/1.1 200 OK
{
  "id": 1616,
  "uuid": "85543ca2-e543-4351-9122-98756d50e6b1",
  "name": "Orchid Surf Stay Bali",
  "description": "Located at the pool area of the hotel ",
  "state": "has_published",
  "system_tags": [
    "offline",
    "outdoor"
  ],
  "last_reading_at": "2015-07-16T08:53:16Z",
  "added_at": "2015-02-02T15:59:51Z",
  "updated_at": "2015-07-16T08:53:32Z",
  "mac_address": "[FILTERED]",
  "owner": {
    "id": 2247,
    "uuid": "bcd5b918-d89f-4cb6-a2bb-30245904bc2f",
    "username": "JesusZabala",
    "avatar": "http://smartcitizen.s3.amazonaws.com/avatars/default.svg",
    "url": null,
    "joined_at": "2015-02-02T15:55:41Z",
    "location": {
      "city": null,
      "country": null,
      "country_code": null
    },
    "device_ids": [
      1616
    ]
  },
  "data": {
    "recorded_at": "2015-07-16T08:53:32Z",
    "added_at": "2015-07-16T08:53:32Z",
    "firmware": "[IGNORE]",
    "location": {
      "ip": null,
      "exposure": "outdoor",
      "elevation": 1,
      "latitude": -8.82111778712582,
      "longitude": 115.15258114151,
      "geohash": "qw3vu65t38",
      "city": "Kuta Selatan",
      "country_code": "ID",
      "country": "Indonesia"
    },
    "sensors": [
      {
        "id": 10,
        "ancestry": null,
        "name": "Battery",
        "description": "Custom Circuit",
        "unit": "%",
        "created_at": "2015-02-02T18:18:00Z",
        "updated_at": "2015-07-05T19:53:51Z",
        "measurement_id": 7,
        "uuid": "c9ff2784-53a7-4a84-b0fc-90ecc7e313f9",
        "value": 100.0,
        "raw_value": 1000,
        "prev_value": 100.0,
        "prev_raw_value": 1000
      },
      {
        "id": 5,
        "ancestry": "3",
        "name": "DHT22 - Humidity",
        "description": "Humidity",
        "unit": "%",
        "created_at": "2015-02-02T18:15:34Z",
        "updated_at": "2015-07-05T19:53:22Z",
        "measurement_id": 2,
        "uuid": "6b4b64d9-3841-446c-a7f5-63f480932b96",
        "value": 1.0,
        "raw_value": 10,
        "prev_value": 1.0,
        "prev_raw_value": 10
      },
      {
        "id": 4,
        "ancestry": "3",
        "name": "DHT22 - Temperature",
        "description": "Temperature",
        "unit": "ºC",
        "created_at": "2015-02-02T18:15:14Z",
        "updated_at": "2015-07-05T19:53:02Z",
        "measurement_id": 1,
        "uuid": "a50dbd88-b0c7-4094-ad74-2b755e8023a8",
        "value": 29.8,
        "raw_value": 298,
        "prev_value": 29.9,
        "prev_raw_value": 299
      },
      {
        "id": 8,
        "ancestry": null,
        "name": "MICS-2710",
        "description": "MOS NO2 gas sensor",
        "unit": "kOhm (ppm)",
        "created_at": "2015-02-02T18:17:23Z",
        "updated_at": "2015-07-05T19:56:21Z",
        "measurement_id": 6,
        "uuid": "1eb0249d-29d8-41be-8e24-d3b1e5773c0f",
        "value": 197.574,
        "raw_value": 197574,
        "prev_value": 182.971,
        "prev_raw_value": 182971
      },
      {
        "id": 9,
        "ancestry": null,
        "name": "MICS-5525",
        "description": "MOS CO gas sensor",
        "unit": "kOhm (ppm)",
        "created_at": "2015-02-02T18:17:44Z",
        "updated_at": "2015-07-05T19:56:07Z",
        "measurement_id": 5,
        "uuid": "7baaecb7-2586-4063-9c15-bfa999e329aa",
        "value": 276.753,
        "raw_value": 276753,
        "prev_value": 278.468,
        "prev_raw_value": 278468
      },
      {
        "id": 21,
        "ancestry": null,
        "name": "Microchip RN-131",
        "description": "802.11 b/g WiFi",
        "unit": "# networks",
        "created_at": "2015-05-04T11:17:18Z",
        "updated_at": "2015-07-05T19:57:22Z",
        "measurement_id": 9,
        "uuid": "5b1f0e38-336a-4abf-9989-69b48f0026ef",
        "value": 4,
        "raw_value": null,
        "prev_value": 4,
        "prev_raw_value": null
      },
      {
        "id": 7,
        "ancestry": null,
        "name": "POM-3044P-R",
        "description": "Electret microphone with envelope follower sound pressure sensor (noise)",
        "unit": "dB",
        "created_at": "2015-02-02T18:16:41Z",
        "updated_at": "2015-07-05T19:56:59Z",
        "measurement_id": 4,
        "uuid": "5efd2376-6783-476b-bf85-57ead5f89654",
        "value": 67.2,
        "raw_value": 31,
        "prev_value": 59.8,
        "prev_raw_value": 13
      },
      {
        "id": 6,
        "ancestry": null,
        "name": "PVD-P8001",
        "description": "LDR Analog Light Sensor",
        "unit": "%",
        "created_at": "2015-02-02T18:15:55Z",
        "updated_at": "2015-07-05T19:56:43Z",
        "measurement_id": 3,
        "uuid": "0e9cdc5b-d369-4480-9676-bf31af6a5977",
        "value": 1.5,
        "raw_value": 15,
        "prev_value": 1.7,
        "prev_raw_value": 17
      },
      {
        "id": 11,
        "ancestry": null,
        "name": "Solar Panel",
        "description": "Custom Circuit",
        "unit": "mV",
        "created_at": "2015-02-02T18:18:12Z",
        "updated_at": "2015-07-05T19:54:09Z",
        "measurement_id": 8,
        "uuid": "4ab402c5-9297-407a-b0b2-7089520f7ed0",
        "value": 5.066,
        "raw_value": 5066,
        "prev_value": 5.067,
        "prev_raw_value": 5067
      }
    ]
  },
  "kit": {
    "id": 2,
    "uuid": "1409dba9-b06b-4ea5-904c-e0df6e09b903",
    "slug": "sck:1,0",
    "name": "SCK 1.0 - Ambient Board",
    "description": "Goteo Board",
    "created_at": "2015-02-02T18:18:50Z",
    "updated_at": "2015-05-25T14:06:25Z"
  }
}

Returns a single device. Example of a complete response - http://api.smartcitizen.me/v0/devices/1616

Parameter Example Description
id
integer
2 Unique ID of the device
owner
object
user The user that owns the device
name
string
Beach SCK Name of the device
description
string
A Smart Citizen on the Beach Description of the device
status
string
new new if never updated,
online if updated less than 10 minutes ago,
offline if updated more than 10 minutes ago
added_at
datetime
2015-02-02T15:59:48.109Z When the device was added to the platform
last_reading_at
datetime
2015-02-02T15:59:48.109Z When the device last posted a reading to the platform
updated_at
datetime
2015-02-02T15:59:48.109Z When the device’s attributes were last changed, not when it last posted data.
data
object
data-object The latest data for the device (see table below)
kit
object
kit Information about the kit that the device is
mac_address
string
00:1C:B3:09:85:15 Shown if current_user is authenticated and is owner of the device. MAC Address of the device

Data Object

Parameter Example Description
recorded_at
datetime
2015-02-11T10:03:36.653Z When the device’s data was recorded
added_at
datetime
2015-02-11T10:03:36.653Z When the device’s data was posted to the platform
calibrated_at
datetime
2015-02-11T10:03:36.653Z When the device’s data was calibrated by the platform
firmware
string
[IGNORE] Ignore for now
location.ip
string
Ignore for now
location.exposure
string
indoor or outdoor Where the device is located
location.elevation
integer
500 Measured in metres
location.latitude
decimal
39.1529768625514 Latitude
location.longitude
decimal
-77.2663983320978 Longitude
location.geohash
string
dqcn9z86d7 Geohash explanation
location.city
string
Germantown City where the device is
location.country_code
string
US Alpha-2 country code where the device is
location.country
string
United States Country name generated from country_code
sensors
array
[sensor, sensor] An array of sensor objects, with the value (final calibrated reading) and raw_value (uncalibrated reading) injected into them.

Get All Devices

GET https://api.smartcitizen.me/v0/devices

Example

GET https://api.smartcitizen.me/v0/devices

HTTP/1.1 200 OK
[
{
  "id": 674,
  "uuid": "a31b92f5-0201-4db4-ac9a-3cfb4a8bbe15",
  "name": "The Continuum",
  "description": "LA CASA",
  "state": "never_published",
  "system_tags": [
    "indoor",
    "offline"
  ],
  "last_reading_at": null,
  "added_at": "2015-02-02T15:59:48Z",
  "updated_at": "2015-05-25T07:31:27Z",
  "mac_address": "[FILTERED]",
  "owner": {
    "id": 498,
    "uuid": "4b09f4d3-040d-4b06-b5e3-8dd10b055dea",
    "username": "Mike6158",
    "avatar": "http://smartcitizen.s3.amazonaws.com/avatars/default.svg",
    "url": null,
    "joined_at": "2015-02-02T15:55:32Z",
    "location": {
      "city": null,
      "country": null,
      "country_code": null
    },
    "device_ids": [
      674
    ]
  },
  "data": {
    "recorded_at": "2015-05-25T07:31:27Z",
    "added_at": "2015-05-25T07:31:27Z",
    "firmware": "[IGNORE]",
    "location": {
      "ip": null,
      "exposure": "indoor",
      "elevation": 348,
      "latitude": 29.7030111,
      "longitude": -96.7805333,
      "geohash": "9v70vxq8d4",
      "city": "Weimar",
      "country_code": "US",
      "country": "United States"
    },
    "sensors": [
      {
        "id": 14,
        "ancestry": null,
        "name": "BH1730FVC",
        "description": "Digital Ambient Light Sensor",
        "unit": "Lux",
        "created_at": "2015-02-02T18:24:56Z",
        "updated_at": "2015-07-05T19:57:36Z",
        "measurement_id": 3,
        "uuid": "ac4234cf-d2b7-4cfa-8765-9f4477e2de5f",
        "value": null,
        "raw_value": null,
        "prev_value": null,
        "prev_raw_value": null
      },
      {
        "id": 17,
        "ancestry": null,
        "name": "Battery",
        "description": "Custom Circuit",
        "unit": "%",
        "created_at": "2015-02-02T18:26:28Z",
        "updated_at": "2015-07-05T19:55:34Z",
        "measurement_id": 7,
        "uuid": "5b0e390e-781d-4243-8e97-579eead09792",
        "value": null,
        "raw_value": null,
        "prev_value": null,
        "prev_raw_value": null
      },
      {
        "id": 13,
        "ancestry": "19",
        "name": "HPP828E031",
        "description": "Humidity",
        "unit": "%",
        "created_at": "2015-02-02T18:24:30Z",
        "updated_at": "2015-07-05T19:54:54Z",
        "measurement_id": 2,
        "uuid": "1c19ae8f-b995-460f-87a3-a9d0c140abfb",
        "value": null,
        "raw_value": null,
        "prev_value": null,
        "prev_raw_value": null
      },
      {
        "id": 12,
        "ancestry": "19",
        "name": "HPP828E031",
        "description": "Temperature",
        "unit": "ºC",
        "created_at": "2015-02-02T18:24:02Z",
        "updated_at": "2015-07-05T19:55:07Z",
        "measurement_id": 1,
        "uuid": "2922d20e-3b83-4d98-8791-cfcdfc12fa99",
        "value": null,
        "raw_value": null,
        "prev_value": null,
        "prev_raw_value": null
      },
      {
        "id": 15,
        "ancestry": "20",
        "name": "MiCS-4514",
        "description": "NO2",
        "unit": "kOhm/ppm",
        "created_at": "2015-02-02T18:25:51Z",
        "updated_at": "2015-07-05T19:57:59Z",
        "measurement_id": 6,
        "uuid": "0c5b7e74-ef87-431d-89af-dd51de84b10e",
        "value": null,
        "raw_value": null,
        "prev_value": null,
        "prev_raw_value": null
      },
      {
        "id": 16,
        "ancestry": "20",
        "name": "MiCS-4514",
        "description": "CO",
        "unit": "kOhm/ppm",
        "created_at": "2015-02-02T18:26:11Z",
        "updated_at": "2015-07-05T19:58:18Z",
        "measurement_id": 5,
        "uuid": "49a26be4-3ce1-4f2e-a09b-4296fefcfe17",
        "value": null,
        "raw_value": null,
        "prev_value": null,
        "prev_raw_value": null
      },
      {
        "id": 21,
        "ancestry": null,
        "name": "Microchip RN-131",
        "description": "802.11 b/g WiFi",
        "unit": "# networks",
        "created_at": "2015-05-04T11:17:18Z",
        "updated_at": "2015-07-05T19:57:22Z",
        "measurement_id": 9,
        "uuid": "5b1f0e38-336a-4abf-9989-69b48f0026ef",
        "value": null,
        "raw_value": null,
        "prev_value": null,
        "prev_raw_value": null
      },
      {
        "id": 7,
        "ancestry": null,
        "name": "POM-3044P-R",
        "description": "Electret microphone with envelope follower sound pressure sensor (noise)",
        "unit": "dB",
        "created_at": "2015-02-02T18:16:41Z",
        "updated_at": "2015-07-05T19:56:59Z",
        "measurement_id": 4,
        "uuid": "5efd2376-6783-476b-bf85-57ead5f89654",
        "value": null,
        "raw_value": null,
        "prev_value": null,
        "prev_raw_value": null
      },
      {
        "id": 18,
        "ancestry": null,
        "name": "Solar Panel",
        "description": "Custom Circuit",
        "unit": "mV",
        "created_at": "2015-02-02T18:26:40Z",
        "updated_at": "2015-07-05T19:54:35Z",
        "measurement_id": 8,
        "uuid": "95d59a95-3791-423c-a201-b19c327765d8",
        "value": null,
        "raw_value": null,
        "prev_value": null,
        "prev_raw_value": null
      }
    ]
  },
  "kit": {
    "id": 3,
    "uuid": "6ae30424-4e09-4318-b96d-771996657c70",
    "slug": "sck:1,1",
    "name": "SCK 1.1 - Ambient Board",
    "description": "Kickstarter Board",
    "created_at": "2015-02-02T18:23:16Z",
    "updated_at": "2015-05-25T14:06:46Z"
  }
}
...

Returns all devices, with the same data as above.

Parameter Example Description
near
string
(lat,lng)
41.401108,
2.215319
When included, returns devices in order of distance from the coordinates

Remove a Device

DELETE https://api.smartcitizen.me/v0/devices/:id

Example

DELETE https://api.smartcitizen.me/v0/devices/10

HTTP/1.1 200 OK

You can only delete devices that you own. After a device is deleted with the API there will be a grace period in which you can contact support to reinstate a device if you have removed it in error. After this grace period has passed, the device and its data will be removed permanently from our databases and cannot be restored.

Sensors

Every device has sensor(s). A sensor is something on a device that can record data. This could be anything, some examples are - temperature, humidity, battery percentage, # wifi networks.

Get all Sensors

GET https://api.smartcitizen.me/v0/sensors

Example

GET https://api.smartcitizen.me/v0/sensors

HTTP/1.1 200 OK
[
{
  "id": 3,
  "uuid": "ac284ba3-e2fc-4795-b2b1-530b32a9b05b",
  "parent_id": null,
  "name": "DHT22",
  "description": "A digital temperature and humidity sensor. It uses a capacitive humidity sensor and a thermistor to measure the surrounding air, and spits out a digital signal on the data pin (no analog input pins needed)",
  "unit": null,
  "created_at": "2015-02-02T18:14:15Z",
  "updated_at": "2015-02-02T18:14:15Z"
}
...

Sensors can contain multiple sub-sensors, such as the DHT-22, which records temperature and humidity. If a sensor has a parent_id then it is a sub-sensor.

Parameter Description
id*
integer
Autoincrementing unique ID for the sensor
uuid*
uuid
Unique ID for the sensor
name
string
Name of the user
description
string
Description of the user
unit
string
The unit of measurement that is recorded with the sensor
created_at*
datetime
When the sensor was added to the platform
updated_at*
datetime
When the sensor was updated on the platform

Get a single Sensor

GET https://api.smartcitizen.me/v0/sensors/:id

Example

GET https://api.smartcitizen.me/v0/sensors/5

HTTP/1.1 200 OK
{
  "id": 5,
  "uuid": "6b4b64d9-3841-446c-a7f5-63f480932b96",
  "parent_id": 3,
  "name": "DHT22 - Humidity",
  "description": "Humidity",
  "unit": "%",
  "created_at": "2015-02-02T18:15:34Z",
  "updated_at": "2015-07-05T19:53:22Z",
  "measurement": {
    "id": 2,
    "uuid": "9cbbd396-5bd3-44be-adc0-7ffba778072d",
    "name": "relativee humidity",
    "description": "Relative humidity is a measure of the amount of moisture in the air relative to the total amount of moisture the air can hold. For instance, if the relative humidity was 50%, then the air is only half saturated with moisture."
  }
}

Will return same parameters as above, but for a single sensor.

Readings

Get Latest Readings

GET https://api.smartcitizen.me/v0/devices/:id

Example

GET https://api.smartcitizen.me/v0/devices/1616

HTTP/1.1 200 OK
{
  "id": 1616,
  "uuid": "85543ca2-e543-4351-9122-98756d50e6b1",
  "name": "Orchid Surf Stay Bali",
  "description": "Located at the pool area of the hotel ",
  "state": "has_published",
  "system_tags": [
    "offline",
    "outdoor"
  ],
  "last_reading_at": "2015-07-16T08:53:16Z",
  "added_at": "2015-02-02T15:59:51Z",
  "updated_at": "2015-07-16T08:53:32Z",
  "mac_address": "[FILTERED]",
  "owner": {
    "id": 2247,
    "uuid": "bcd5b918-d89f-4cb6-a2bb-30245904bc2f",
    "username": "JesusZabala",
    "avatar": "http://smartcitizen.s3.amazonaws.com/avatars/default.svg",
    "url": null,
    "joined_at": "2015-02-02T15:55:41Z",
    "location": {
      "city": null,
      "country": null,
      "country_code": null
    },
    "device_ids": [
      1616
    ]
  },
  "data": {
    "recorded_at": "2015-07-16T08:53:32Z",
    "added_at": "2015-07-16T08:53:32Z",
    "firmware": "[IGNORE]",
    "location": {
      "ip": null,
      "exposure": "outdoor",
      "elevation": 1,
      "latitude": -8.82111778712582,
      "longitude": 115.15258114151,
      "geohash": "qw3vu65t38",
      "city": "Kuta Selatan",
      "country_code": "ID",
      "country": "Indonesia"
    },
    "sensors": [
      {
        "id": 10,
        "ancestry": null,
        "name": "Battery",
        "description": "Custom Circuit",
        "unit": "%",
        "created_at": "2015-02-02T18:18:00Z",
        "updated_at": "2015-07-05T19:53:51Z",
        "measurement_id": 7,
        "uuid": "c9ff2784-53a7-4a84-b0fc-90ecc7e313f9",
        "value": 100.0,
        "raw_value": 1000,
        "prev_value": 100.0,
        "prev_raw_value": 1000
      },
      {
        "id": 5,
        "ancestry": "3",
        "name": "DHT22 - Humidity",
        "description": "Humidity",
        "unit": "%",
        "created_at": "2015-02-02T18:15:34Z",
        "updated_at": "2015-07-05T19:53:22Z",
        "measurement_id": 2,
        "uuid": "6b4b64d9-3841-446c-a7f5-63f480932b96",
        "value": 1.0,
        "raw_value": 10,
        "prev_value": 1.0,
        "prev_raw_value": 10
      },
      {
        "id": 4,
        "ancestry": "3",
        "name": "DHT22 - Temperature",
        "description": "Temperature",
        "unit": "ºC",
        "created_at": "2015-02-02T18:15:14Z",
        "updated_at": "2015-07-05T19:53:02Z",
        "measurement_id": 1,
        "uuid": "a50dbd88-b0c7-4094-ad74-2b755e8023a8",
        "value": 29.8,
        "raw_value": 298,
        "prev_value": 29.9,
        "prev_raw_value": 299
      },
      {
        "id": 8,
        "ancestry": null,
        "name": "MICS-2710",
        "description": "MOS NO2 gas sensor",
        "unit": "kOhm (ppm)",
        "created_at": "2015-02-02T18:17:23Z",
        "updated_at": "2015-07-05T19:56:21Z",
        "measurement_id": 6,
        "uuid": "1eb0249d-29d8-41be-8e24-d3b1e5773c0f",
        "value": 197.574,
        "raw_value": 197574,
        "prev_value": 182.971,
        "prev_raw_value": 182971
      },
      {
        "id": 9,
        "ancestry": null,
        "name": "MICS-5525",
        "description": "MOS CO gas sensor",
        "unit": "kOhm (ppm)",
        "created_at": "2015-02-02T18:17:44Z",
        "updated_at": "2015-07-05T19:56:07Z",
        "measurement_id": 5,
        "uuid": "7baaecb7-2586-4063-9c15-bfa999e329aa",
        "value": 276.753,
        "raw_value": 276753,
        "prev_value": 278.468,
        "prev_raw_value": 278468
      },
      {
        "id": 21,
        "ancestry": null,
        "name": "Microchip RN-131",
        "description": "802.11 b/g WiFi",
        "unit": "# networks",
        "created_at": "2015-05-04T11:17:18Z",
        "updated_at": "2015-07-05T19:57:22Z",
        "measurement_id": 9,
        "uuid": "5b1f0e38-336a-4abf-9989-69b48f0026ef",
        "value": 4,
        "raw_value": null,
        "prev_value": 4,
        "prev_raw_value": null
      },
      {
        "id": 7,
        "ancestry": null,
        "name": "POM-3044P-R",
        "description": "Electret microphone with envelope follower sound pressure sensor (noise)",
        "unit": "dB",
        "created_at": "2015-02-02T18:16:41Z",
        "updated_at": "2015-07-05T19:56:59Z",
        "measurement_id": 4,
        "uuid": "5efd2376-6783-476b-bf85-57ead5f89654",
        "value": 67.2,
        "raw_value": 31,
        "prev_value": 59.8,
        "prev_raw_value": 13
      },
      {
        "id": 6,
        "ancestry": null,
        "name": "PVD-P8001",
        "description": "LDR Analog Light Sensor",
        "unit": "%",
        "created_at": "2015-02-02T18:15:55Z",
        "updated_at": "2015-07-05T19:56:43Z",
        "measurement_id": 3,
        "uuid": "0e9cdc5b-d369-4480-9676-bf31af6a5977",
        "value": 1.5,
        "raw_value": 15,
        "prev_value": 1.7,
        "prev_raw_value": 17
      },
      {
        "id": 11,
        "ancestry": null,
        "name": "Solar Panel",
        "description": "Custom Circuit",
        "unit": "mV",
        "created_at": "2015-02-02T18:18:12Z",
        "updated_at": "2015-07-05T19:54:09Z",
        "measurement_id": 8,
        "uuid": "4ab402c5-9297-407a-b0b2-7089520f7ed0",
        "value": 5.066,
        "raw_value": 5066,
        "prev_value": 5.067,
        "prev_raw_value": 5067
      }
    ]
  },
  "kit": {
    "id": 2,
    "uuid": "1409dba9-b06b-4ea5-904c-e0df6e09b903",
    "slug": "sck:1,0",
    "name": "SCK 1.0 - Ambient Board",
    "description": "Goteo Board",
    "created_at": "2015-02-02T18:18:50Z",
    "updated_at": "2015-05-25T14:06:25Z"
  }
}

(for a device)

The latest set of readings is included with the device, so if you call /v0/devices/:id you will see the most recent set of readings embedded in data.sensors as value and raw_value.

Get Historical Readings

GET https://api.smartcitizen.me/v0/devices/:device_id/readings

Example

GET https://api.smartcitizen.me/v0/devices/1616/readings?sensor_id=7&rollup=4h&from=2015-07-28&to=2015-07-30

HTTP/1.1 200 OK
{
  "device_id": 1616,
  "sensor_id": 7,
  "rollup": "4h",
  "function": "avg",
  "from": "2015-07-28T00:00:00Z",
  "to": "2015-07-30T00:00:00Z",
  "sample_size": 1776,
  "readings": [
    [
      "2015-07-29T20:00:35Z",
      65.78151658767773
    ],
    [
      "2015-07-29T16:00:46Z",
      65.67438423645321
    ],
    [
      "2015-07-29T12:00:06Z",
      65.88564593301437
    ],
    [
      "2015-07-29T08:00:07Z",
      65.86494845360832
    ],
    [
      "2015-07-29T04:00:36Z",
      65.47640791476408
    ],
    [
      "2015-07-29T00:00:12Z",
      64.98706140350879
    ],
    [
      "2015-07-28T20:00:38Z",
      63.82850241545894
    ],
    [
      "2015-07-28T16:00:03Z",
      65.36859903381644
    ],
    [
      "2015-07-28T14:14:05Z",
      65.28877551020409
    ]
  ]
}

Returns the readings that were recorded for a specific sensor on a device. Readings are returned as a tuple [recorded_at, value]

Request Parameters

Parameter Example Required? Description
device_id
integer
2 Unique ID of the device
sensor_id
integer
7 Unique ID of the sensor on the device
rollup
string
1w (1 week) Timespan to use when grouping readings. See table
from
datetime
2015-07-20 00:00:00 UTC The start of the range of readings
to
datetime
2015-07-27 00:00:00 UTC The end of the range of readings
function
string
avg Method to use when grouping the readings. See table
all_intervals
boolean
true Include all possible timestamps within the from > to range, even if they have nil values

Response

Parameter Description
device_id
integer
Unique ID of the device
rollup
string
Timespan of data groups
function
string
How the readings collection should be grouped
from
datetime
The beginning of the timeframe
from
datetime
The end of the timeframe
sample_size
integer
The count of readings that were examined to build the response
readings
array
Array of tuples, representing the recorded_at and value of each reading

Rollup measurements

key value
y years
M months
w weeks
d days
h hours
m minutes
s seconds
ms milliseconds

Functions

Parameter Description
avg Computes average readings within the rollup period
max Returns the largest readings within the rollup period
min Returns the smallest readings within the rollup period
sum  Sums all readings within the rollup period
count Counts the number of readings within rollup periods
dev Computes standard deviation
first Returns the first readings within the rollup period
last Returns the last readings within the rollup period

CSV Archive of readings

GET https://api.smartcitizen.me/v0/devices/:id/readings/csv_archive

access_token authentication required, you must either be the owner of the device or an admin.

possible responses:

200 - OK, job has been enqueued and the user will be emailed a link to the CSV file 401 - Unauthorised 403 - Forbidden 404 - Device not found 420 - (rate limiting, please only make one request every X – currently X = 6 hours) 500 - Server Error

If you try to GET the endpoint multiple times you will receive a 420 rate limit error until 6 hours have passed.

Post Readings

A device has one Blueprint we call kit, and a blueprint has many sensors through components. Most devices on the platform share the same blueprint, a default SCK 1.1 (e.g. Kickstarter Board). But new devices (e.g. Raspberry Pi’s, new Sensor Add-ons) might use a different Blueprints.

GET https://api.smartcitizen.me/v0/devices/:device_id/readings

access_token authentication required, you must either be the owner of the device or an admin.

Example

POST https://api.smartcitizen.me/v0/devices/1816/readings?access_token=XEGwy6BsEybbz3BjYxemxfTQcHjAAJ1s3vJkemhdQ45Cq4hvBM7pNlrY48SUjCfai

  

Example payloads

{ "data": [{ "recorded_at": "2016-06-08 10:30:00", "sensors": [{ "id": 22, "value": 21 }] }] } { "data": [{ "recorded_at": "2016-06-08 10:30:00", "sensors": [{ "id": "temp", "value": 21 }] }] }

Request Parameters

Parameter Example Required? Description
data
array
The data payload

Data Parameters

Parameter Example Required? Description
recorded_at
datetime
2015-07-20 00:00:00 UTC The time when the reading took place
sensors
array
The sensors objects

Sensor Parameters

Parameter Example Required? Description
id
integer
12 The id
id
string
temp Instead of the id we can use a hash as defined on the Blueprint
value
float
22 The value of the sensor (can be an integer or float)

Kits

At the moment, every device has one kit. In the future this will change, as some devices might not be associated with a kit. However, you can assume that every device is associated with a kit right now.

Get All Kits

GET https://api.smartcitizen.me/v0/kits

Example

GET https://api.smartcitizen.me/v0/kits

HTTP/1.1 200 OK
[
{
  "id": 2,
  "uuid": "1409dba9-b06b-4ea5-904c-e0df6e09b903",
  "slug": "sck:1,0",
  "name": "SCK 1.0 - Ambient Board",
  "description": "Goteo Board",
  "created_at": "2015-02-02T18:18:50Z",
  "updated_at": "2015-05-25T14:06:25Z",
  "sensors": [
    {
      "id": 4,
      "uuid": "a50dbd88-b0c7-4094-ad74-2b755e8023a8",
      "parent_id": 3,
      "name": "DHT22 - Temperature",
      "description": "Temperature",
      "unit": "ºC",
      "created_at": "2015-02-02T18:15:14Z",
      "updated_at": "2015-07-05T19:53:02Z",
      "measurement": {
        "id": 1,
        "uuid": "b3f44b63-0a17-4d84-bbf1-4c17764b7eae",
        "name": "air temperature",
        "description": "Air temperature is a measure of how hot or cold the air is. It is the most commonly measured weather parameter. Air temperature is dependent on the amount and strength of the sunlight hitting the earth, and atmospheric conditions, such as cloud cover and humidity, which trap heat."
      }
    },
    {
      "id": 5,
      "uuid": "6b4b64d9-3841-446c-a7f5-63f480932b96",
      "parent_id": 3,
      "name": "DHT22 - Humidity",
      "description": "Humidity",
      "unit": "%",
      "created_at": "2015-02-02T18:15:34Z",
      "updated_at": "2015-07-05T19:53:22Z",
      "measurement": {
        "id": 2,
        "uuid": "9cbbd396-5bd3-44be-adc0-7ffba778072d",
        "name": "relativee humidity",
        "description": "Relative humidity is a measure of the amount of moisture in the air relative to the total amount of moisture the air can hold. For instance, if the relative humidity was 50%, then the air is only half saturated with moisture."
      }
    },
    {
      "id": 10,
      "uuid": "c9ff2784-53a7-4a84-b0fc-90ecc7e313f9",
      "parent_id": null,
      "name": "Battery",
      "description": "Custom Circuit",
      "unit": "%",
      "created_at": "2015-02-02T18:18:00Z",
      "updated_at": "2015-07-05T19:53:51Z",
      "measurement": {
        "id": 7,
        "uuid": "c5964926-c2d2-4714-98b5-18f84c6f95c1",
        "name": "battery",
        "description": "The SCK remaining battery level in percentage."
      }
    },
    {
      "id": 11,
      "uuid": "4ab402c5-9297-407a-b0b2-7089520f7ed0",
      "parent_id": null,
      "name": "Solar Panel",
      "description": "Custom Circuit",
      "unit": "mV",
      "created_at": "2015-02-02T18:18:12Z",
      "updated_at": "2015-07-05T19:54:09Z",
      "measurement": {
        "id": 8,
        "uuid": "68cf6255-9b17-4002-9fe0-736267050b74",
        "name": "pv panel",
        "description": "The SCK t solar panel energy volatge when you conect one."
      }
    },
    {
      "id": 9,
      "uuid": "7baaecb7-2586-4063-9c15-bfa999e329aa",
      "parent_id": null,
      "name": "MICS-5525",
      "description": "MOS CO gas sensor",
      "unit": "kOhm (ppm)",
      "created_at": "2015-02-02T18:17:44Z",
      "updated_at": "2015-07-05T19:56:07Z",
      "measurement": {
        "id": 5,
        "uuid": "fd22c946-d6d8-40c3-97ea-0021ce6d21a1",
        "name": "co",
        "description": "Carbon monoxide is a colorless, odorless, and tasteless gas. It is a pollutant in some urban areas coming from the exhaust of internal combustion engines  (cars, trucks, ships...)  and incomplete combustion of various other fuels."
      }
    },
    {
      "id": 8,
      "uuid": "1eb0249d-29d8-41be-8e24-d3b1e5773c0f",
      "parent_id": null,
      "name": "MICS-2710",
      "description": "MOS NO2 gas sensor",
      "unit": "kOhm (ppm)",
      "created_at": "2015-02-02T18:17:23Z",
      "updated_at": "2015-07-05T19:56:21Z",
      "measurement": {
        "id": 6,
        "uuid": "2ca7194a-f4b4-4b55-916b-debb84f33fbd",
        "name": "no2",
        "description": "Nitrogen dioxide is a toxic gas. It is a pollutant in some urban areas due the excess air required for complete combustion of fuels introduces nitrogen into the combustion of internal combustion engines (cars, trucks, ships...) and power stations."
      }
    },
    {
      "id": 6,
      "uuid": "0e9cdc5b-d369-4480-9676-bf31af6a5977",
      "parent_id": null,
      "name": "PVD-P8001",
      "description": "LDR Analog Light Sensor",
      "unit": "%",
      "created_at": "2015-02-02T18:15:55Z",
      "updated_at": "2015-07-05T19:56:43Z",
      "measurement": {
        "id": 3,
        "uuid": "50aa0431-86ac-4340-bf51-ad498ee35a3b",
        "name": "light",
        "description": "Lux is a measure of how much light is spread over a given area. A full moon clear night is around 1 lux, inside an office building you usually have 400 lux and a bright day can be more than 20000 lux."
      }
    },
    {
      "id": 7,
      "uuid": "5efd2376-6783-476b-bf85-57ead5f89654",
      "parent_id": null,
      "name": "POM-3044P-R",
      "description": "Electret microphone with envelope follower sound pressure sensor (noise)",
      "unit": "dB",
      "created_at": "2015-02-02T18:16:41Z",
      "updated_at": "2015-07-05T19:56:59Z",
      "measurement": {
        "id": 4,
        "uuid": "2841719f-658e-40df-a14a-74a86adc1410",
        "name": "noise",
        "description": "dB's measure sound pressure difference between the average local pressure and the pressure in the sound wave.  A quite library is below 40dB, your house is around 50dB and a diesel truck in your street 90dB."
      }
    },
    {
      "id": 21,
      "uuid": "5b1f0e38-336a-4abf-9989-69b48f0026ef",
      "parent_id": null,
      "name": "Microchip RN-131",
      "description": "802.11 b/g WiFi",
      "unit": "# networks",
      "created_at": "2015-05-04T11:17:18Z",
      "updated_at": "2015-07-05T19:57:22Z",
      "measurement": {
        "id": 9,
        "uuid": "c3ea53a8-8235-4d0c-84ee-729e6ade589c",
        "name": "nets",
        "description": "The amount of Wi-Fi networks visible by the SCK."
      }
    }
  ]
}
...

More information about the current kits can be found on github

Parameter Description
id*
integer
Autoincrementing unique ID for the kit
uuid*
uuid
Unique ID for the kit
name
string
Name of the kit
description
string
Description of the kit
created_at*
datetime
When the kit was added to the platform
updated_at*
datetime
When the kit was updated on the platform

Get a single Kit

GET https://api.smartcitizen.me/v0/kits/:id

Example

GET https://api.smartcitizen.me/v0/kits/2

HTTP/1.1 200 OK
{
  "id": 2,
  "uuid": "1409dba9-b06b-4ea5-904c-e0df6e09b903",
  "slug": "sck:1,0",
  "name": "SCK 1.0 - Ambient Board",
  "description": "Goteo Board",
  "created_at": "2015-02-02T18:18:50Z",
  "updated_at": "2015-05-25T14:06:25Z",
  "sensors": [
    {
      "id": 4,
      "uuid": "a50dbd88-b0c7-4094-ad74-2b755e8023a8",
      "parent_id": 3,
      "name": "DHT22 - Temperature",
      "description": "Temperature",
      "unit": "ºC",
      "created_at": "2015-02-02T18:15:14Z",
      "updated_at": "2015-07-05T19:53:02Z",
      "measurement": {
        "id": 1,
        "uuid": "b3f44b63-0a17-4d84-bbf1-4c17764b7eae",
        "name": "air temperature",
        "description": "Air temperature is a measure of how hot or cold the air is. It is the most commonly measured weather parameter. Air temperature is dependent on the amount and strength of the sunlight hitting the earth, and atmospheric conditions, such as cloud cover and humidity, which trap heat."
      }
    },
    {
      "id": 5,
      "uuid": "6b4b64d9-3841-446c-a7f5-63f480932b96",
      "parent_id": 3,
      "name": "DHT22 - Humidity",
      "description": "Humidity",
      "unit": "%",
      "created_at": "2015-02-02T18:15:34Z",
      "updated_at": "2015-07-05T19:53:22Z",
      "measurement": {
        "id": 2,
        "uuid": "9cbbd396-5bd3-44be-adc0-7ffba778072d",
        "name": "relativee humidity",
        "description": "Relative humidity is a measure of the amount of moisture in the air relative to the total amount of moisture the air can hold. For instance, if the relative humidity was 50%, then the air is only half saturated with moisture."
      }
    },
    {
      "id": 10,
      "uuid": "c9ff2784-53a7-4a84-b0fc-90ecc7e313f9",
      "parent_id": null,
      "name": "Battery",
      "description": "Custom Circuit",
      "unit": "%",
      "created_at": "2015-02-02T18:18:00Z",
      "updated_at": "2015-07-05T19:53:51Z",
      "measurement": {
        "id": 7,
        "uuid": "c5964926-c2d2-4714-98b5-18f84c6f95c1",
        "name": "battery",
        "description": "The SCK remaining battery level in percentage."
      }
    },
    {
      "id": 11,
      "uuid": "4ab402c5-9297-407a-b0b2-7089520f7ed0",
      "parent_id": null,
      "name": "Solar Panel",
      "description": "Custom Circuit",
      "unit": "mV",
      "created_at": "2015-02-02T18:18:12Z",
      "updated_at": "2015-07-05T19:54:09Z",
      "measurement": {
        "id": 8,
        "uuid": "68cf6255-9b17-4002-9fe0-736267050b74",
        "name": "pv panel",
        "description": "The SCK t solar panel energy volatge when you conect one."
      }
    },
    {
      "id": 9,
      "uuid": "7baaecb7-2586-4063-9c15-bfa999e329aa",
      "parent_id": null,
      "name": "MICS-5525",
      "description": "MOS CO gas sensor",
      "unit": "kOhm (ppm)",
      "created_at": "2015-02-02T18:17:44Z",
      "updated_at": "2015-07-05T19:56:07Z",
      "measurement": {
        "id": 5,
        "uuid": "fd22c946-d6d8-40c3-97ea-0021ce6d21a1",
        "name": "co",
        "description": "Carbon monoxide is a colorless, odorless, and tasteless gas. It is a pollutant in some urban areas coming from the exhaust of internal combustion engines  (cars, trucks, ships...)  and incomplete combustion of various other fuels."
      }
    },
    {
      "id": 8,
      "uuid": "1eb0249d-29d8-41be-8e24-d3b1e5773c0f",
      "parent_id": null,
      "name": "MICS-2710",
      "description": "MOS NO2 gas sensor",
      "unit": "kOhm (ppm)",
      "created_at": "2015-02-02T18:17:23Z",
      "updated_at": "2015-07-05T19:56:21Z",
      "measurement": {
        "id": 6,
        "uuid": "2ca7194a-f4b4-4b55-916b-debb84f33fbd",
        "name": "no2",
        "description": "Nitrogen dioxide is a toxic gas. It is a pollutant in some urban areas due the excess air required for complete combustion of fuels introduces nitrogen into the combustion of internal combustion engines (cars, trucks, ships...) and power stations."
      }
    },
    {
      "id": 6,
      "uuid": "0e9cdc5b-d369-4480-9676-bf31af6a5977",
      "parent_id": null,
      "name": "PVD-P8001",
      "description": "LDR Analog Light Sensor",
      "unit": "%",
      "created_at": "2015-02-02T18:15:55Z",
      "updated_at": "2015-07-05T19:56:43Z",
      "measurement": {
        "id": 3,
        "uuid": "50aa0431-86ac-4340-bf51-ad498ee35a3b",
        "name": "light",
        "description": "Lux is a measure of how much light is spread over a given area. A full moon clear night is around 1 lux, inside an office building you usually have 400 lux and a bright day can be more than 20000 lux."
      }
    },
    {
      "id": 7,
      "uuid": "5efd2376-6783-476b-bf85-57ead5f89654",
      "parent_id": null,
      "name": "POM-3044P-R",
      "description": "Electret microphone with envelope follower sound pressure sensor (noise)",
      "unit": "dB",
      "created_at": "2015-02-02T18:16:41Z",
      "updated_at": "2015-07-05T19:56:59Z",
      "measurement": {
        "id": 4,
        "uuid": "2841719f-658e-40df-a14a-74a86adc1410",
        "name": "noise",
        "description": "dB's measure sound pressure difference between the average local pressure and the pressure in the sound wave.  A quite library is below 40dB, your house is around 50dB and a diesel truck in your street 90dB."
      }
    },
    {
      "id": 21,
      "uuid": "5b1f0e38-336a-4abf-9989-69b48f0026ef",
      "parent_id": null,
      "name": "Microchip RN-131",
      "description": "802.11 b/g WiFi",
      "unit": "# networks",
      "created_at": "2015-05-04T11:17:18Z",
      "updated_at": "2015-07-05T19:57:22Z",
      "measurement": {
        "id": 9,
        "uuid": "c3ea53a8-8235-4d0c-84ee-729e6ade589c",
        "name": "nets",
        "description": "The amount of Wi-Fi networks visible by the SCK."
      }
    }
  ]
}

Measurements

Measurements are descriptions of what Sensors are recording.

Get All Measurements

GET https://api.smartcitizen.me/v0/measurements

Example

GET https://api.smartcitizen.me/v0/measurements

HTTP/1.1 200 OK
[
{
  "id": 1,
  "uuid": "b3f44b63-0a17-4d84-bbf1-4c17764b7eae",
  "name": "air temperature",
  "description": "Air temperature is a measure of how hot or cold the air is. It is the most commonly measured weather parameter. Air temperature is dependent on the amount and strength of the sunlight hitting the earth, and atmospheric conditions, such as cloud cover and humidity, which trap heat.",
  "created_at": "2015-07-03T10:16:10Z",
  "updated_at": "2015-07-03T10:16:10Z"
}
...
Parameter Description
id*
integer
Autoincrementing unique ID for the measurement
uuid*
uuid
Unique ID for the measurement
name
string
Name of the measurement
description
string
Description of the measurement
created_at*
datetime
When the measurement was added to the platform
updated_at*
datetime
When the measurement was updated on the platform

Get a single Measurement

GET https://api.smartcitizen.me/v0/measurements/:id

Example

GET https://api.smartcitizen.me/v0/measurements/2

HTTP/1.1 200 OK
{
  "id": 2,
  "uuid": "9cbbd396-5bd3-44be-adc0-7ffba778072d",
  "name": "relativee humidity",
  "description": "Relative humidity is a measure of the amount of moisture in the air relative to the total amount of moisture the air can hold. For instance, if the relative humidity was 50%, then the air is only half saturated with moisture.",
  "created_at": "2015-07-03T10:16:23Z",
  "updated_at": "2015-07-03T10:16:23Z"
}

Components

Components are used to join Kits or Devices to Sensors.

Get All Components

GET https://api.smartcitizen.me/v0/components

Example

GET https://api.smartcitizen.me/v0/components

HTTP/1.1 200 OK
[
{
  "id": 4,
  "uuid": "6d60506b-317c-4cb9-a697-1bb5a3ee2c0d",
  "board_id": 2,
  "board_type": "Kit",
  "sensor_id": 4,
  "created_at": "2015-02-02T18:19:07Z",
  "updated_at": "2015-02-02T18:19:07Z"
}
...
Parameter Description
id*
integer
Autoincrementing unique ID for the component
uuid*
uuid
Unique ID for the component
board_id*
integer
ID of the Kit or Device that the component is associated with
board_type*
integer
Either Kit or Device (Probably Kit)
sensor_id*
integer
ID of the Sensor that the component is associated with
created_at*
datetime
When the measurement was added to the platform
updated_at*
datetime
When the measurement was updated on the platform

Tags

Get all Tags

GET https://api.smartcitizen.me/v0/tags

Example

GET https://api.smartcitizen.me/v0/tags

HTTP/1.1 200 OK
[
{
  "id": 1,
  "uuid": "f7f09e83-9da9-431b-9be2-cc411f40afbf",
  "name": "testtag",
  "description": "test description"
}
...
Parameter Example Description
id
integer
2 Unique ID of the tag
name
string
example-tag Unique name of the tag [A-Za-z0-9-_]
description
string
Further information about the tag

Adding/editing a device’s tags

PATCH https://api.smartcitizen.me/v0/devices/:id

Include comma seperated list of tag names in user_tags property.

For example, if there are tags with the names interesting and cool-hardware you could add these tags to a device by PATCHING user_tags = 'interesting,cool-hardware'. If you then wanted to remove cool-hardware you would PATCH again, but without the second tag i.e. user_tags = interesting.

Creating a Tag

POST https://api.smartcitizen.me/v0/tags Admin only

Updating a Tag

PATCH https://api.smartcitizen.me/v0/tags/:id Admin only

Deleting a Tag

DELETE https://api.smartcitizen.me/v0/tags/:id Admin only

Response Status Codes

Error Messages

HTTP/1.1 404 Not Found
{
  "id" : "record_not_found",
  "message" : "Couldn't find Device with 'id'=101308",
  "errors": null,
  "url" : null
}


HTTP/1.1 422 Unprocessable Entity
{
  "id": "unprocessable_entity",
  "message": "Unprocessable Entity",
  "errors": {
    "mac_address": [
      "can't be blank",
      "is invalid"
    ],
    "name": [
      "can't be blank"
    ]
  },
  "url": null
}

When possible, read the HTTP status codes to learn of the success of your request. The API uses the following pattern for error messages, as recommended by https://github.com/interagent/http-api-design.

Success Codes

Code Meaning
200 Request succeeded for a GET call, for a DELETE or PATCH call that completed synchronously, or for a PATCH call that synchronously updated an existing resource
201 Request succeeded for a POST call that completed synchronously, or for a PATCH call that synchronously created a new resource

Error Codes

Code Meaning
400 Bad Request – there is a problem with your request
401 Unauthorized – Your authentication credentials are incorrect
403 Forbidden – The resource requested is hidden, or you do not have the necessary privileges
404 Not Found – The specified resource could not be found
405 Method Not Allowed – You tried to access a resource with an invalid method
406 Not Acceptable – You requested a format that isn’t json
422 Unprocessable Entity: Your request was understood, but contained invalid parameters
429 Too Many Requests
500 Internal Server Error
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later

Real Time

Websockets

The real time API uses websockets to push devices information in real-time and it is based on the famous socket.io library. We support WSS, WebSockets over SSL/TLS, like HTTPS. We also support fallback to long polling for older browsers.

data-received is currently the only available topic. Everytime a device publishes data to the platform data is pushed over the channel. With the same model as device GET.

Example

io.connect(‘wss://smartcitizen.xyz’).on('data-received’, doSomething);

  

Example webpage

<html> <head> <script src="https://cdnjs.cloudflare.com/ajax/libs/socket.io/1.4.6/socket.io.js"></script> <style> body { font-family: Helvetica, Arial, sans-serif; color: white; font-weight: bold; } div { float: left; display: block; background: #4FC9E8!important; margin: 5px; width: 100px; padding: 5px; height: 100px; } </style> <script> io.connect('wss://smartcitizen.xyz') .on('data-received', function(device) { document.body.innerHTML = document.body.innerHTML + "<div>" + device.data.name + "</div>" }); </script> </head> <body> </body> </html> Live demo: http://codepen.io/pral2a/pen/jrPNzy