Summary
-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.
+The Smart Citizen 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.
# Shell example
# In the shell examples we use either curl or the `http` (HTTPIe) program
// Javascript example
@@ -456,18 +445,22 @@ Summary
"example_response":"example_value"
}
]
-
Schema
-All API access is over HTTPS (with the exception of /add) and accessed via api.smartcitizen.me
Schema
+In a general sense, any user can own as many device as needed. Each device represents a "real" device, containing sensors, which perform measurements. A device in a real world can be registered multiple times in the API, but it will only store data in one device. In addition, user can create experiments, which are collection of devices with a certain purpose. This feature is currently experimental!
+ +
Blank fields are included as null instead of being omitted.
All API access is over HTTPS and accessed via api.smartcitizen.me. Some overall characteristics to bear in mind:
All timestamps are returned in ISO 8601 format:
+-
+
- Blank fields are included as
nullinstead of being omitted.
+ - Obviously, some items are filtered by the API if your response are not authorized. See authhentication. +
- All timestamps are returned in ISO 8601 format, non-localised:
YYYY-MM-DDTHH:MM:SSZ.
+
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:
+You can issue a GET request to the root endpoint to get all the endpoint categories that the API supports. From all the possible endpoints, you will mostly care about devices, measurements, sensors and users.
$ curl https://api.smartcitizen.me
http GET https://api.smartcitizen.me/v0/
@@ -481,20 +474,19 @@ Root Endpoint
});
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"
+ "notice":"Welcome. The old API has been removed.",
+ "api_documentation_url":"https://developer.smartcitizen.me",
+ "current_user_url":"https://api.smartcitizen.me/v0/me",
+ "devices_url":"https://api.smartcitizen.me/v0/devices",
+ "measurements_url":"https://api.smartcitizen.me/v0/measurements",
+ "sensors_url":"https://api.smartcitizen.me/v0/sensors",
+ "users_url":"https://api.smartcitizen.me/v0/users",
+ "tags_url":"https://api.smartcitizen.me/v0/tags",
+ "tags_sensors_url":"https://api.smartcitizen.me/v0/tag_sensors",
+ "version_git":"1.1.5\n"
}
-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.
+Versioning
+By default and, for now, 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.
| Example | -Type | -Value | -Description | -
|---|---|---|---|
| /users?q[username_eq]=adam | -string | -adam | -Users where username equals 'adam' | -
| /users?q[username_cont]=osc | -string | -osc | -Users where username contains 'osc' | -
| /devices?q[name_cont]=sck | -string | -sck | -Devices where username contains 'sck' | -
| /devices?q[owner_id_eq]=1 | -integer | -1 | -Devices where owner ID equals 1 | -
| /devices?q[tags_name_in]=Barcelona | -string | -Barcelona | -Devices which have the tag 'Barcelona' (case sensitive). | -
| /devices?with_tags=Barcelona|Amsterdam | -string | -Barcelona|Amsterdam | -Devices which have ANY of the tags separated by PIPE | | -
| /devices?q[postprocessing_id_not_null]=1 | -integer | -1 | -Devices where postprocessing is not_null |
-
| /sensors?q[id_lt]=100 | -integer | -100 | -Sensors where ID less than 100 | -
https://github.com/activerecord-hackery/ransack/wiki/Basic-Searching
+ +For information about the Search Matchers, check the Ransack documentation.
Keys for devices
| description | |
| owner_id | -|
| owner_username | |
| mac_address (only for admin) | +owner_id |
| created_at | @@ -756,25 +689,13 @@last_recorded_at |
| geohash | -|
| uuid | -|
| state | |
| exposure (*) | -|
| tag_name | +exposure |
| postprocessing_id | -|
| kit_id (*) | +kit_id |
| geohash | @@ -782,12 +703,7 @@|
| uuid | |
| token (only for admins) | -
Keys for users
| uuid |
Keys for sensors
+Examples
| Key | +Query | +Type | +Value | +Description |
|---|---|---|---|---|
| id | -||||
| name | +/users?q[username_eq]=adam | +string | +adam | +Users where first name equals 'Adam' |
| unit | +/devices?q[owner_id_eq]=1 | +integer | +1 | +Devices where owner ID equals 1 |
| measurement_id | +/devices?q[tags_name_in]=Barcelona | +string | +Barcelona | +Devices which have the tag 'Barcelona' (case sensitive). |
| ancestry | +/devices?with_tags=Barcelona|Amsterdam | +string | +Barcelona|Amsterdam | +Devices which have ANY of the tags separated by PIPE | |
| created_at | +/devices?q[postprocessing_id_not_null]=1 | +integer | +1 | +Devices where postprocessing is not_null |
| updated_at | +/sensors?q[id_lt]=100 | +integer | +100 | +Sensors where ID less than 100 |
| uuid | +/users?q[username_cont]=sck | +string | +sck | +Users where username contains 'sck' |
Sorting Results
@@ -917,16 +854,6 @@Users
Add a User
string
string
string
Get Current User (me)
} -Used to retrieve information about the currently authenticated user. -Returns a detailed representation of the user.
+Used to retrieve information about the currently authenticated user. It returns a detailed representation of the user.
| Parameter | +Field | Description | Unique ID for the user |
|---|---|---|---|
| first_name string |
-First name of the user | +role* string |
+There are currently three different roles: citizen, researcher and admin. See role. |
| last_name string |
-Last name of the user | +username* string |
+Username of the user |
| email string |
-Email address of the authenticated user, will be [FILTERED] for unauthenticated requests | +profile_picture* file |
+Upload the image that represents the user. It will return a Rails active_storage link to the asset |
| username* string |
-Username of the user | +url string |
+Webpage 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. This is the old way and might be migrated later. Use profile_picture instead |
+location.country_code string |
+2 letter country-code of the user |
| profile_picture* file |
-Upload the image that represents the user. It will return a Rails active_storage link to the asset | +updated_at* datetime |
+The date and time that the user updated data on the platform |
| devices array |
-Array of devices that the user manages on the platform | +email string |
+Email address of the authenticated user, will be [FILTERED] for unauthenticated requests |
| joined_at* datetime |
-The date and time that the user joined the platform | +forwarding_token string |
+Hash containing a forwarding secret topic to be used in data forwarding |
| updated_at* datetime |
-The date and time that the user updated data on the platform | +forwarding_username string |
+Hash containing a forwarding secret username to be used in data forwarding |
| role* string |
-Access privileges of the user, citizen is the default. admin accounts have full access to the platform. |
+devices array |
+Array of devices that the user owns on the platform |
Roles
+The role defines privileges of the user, for which citizen is the default role. admin accounts have full access to the platform, while researchers can enable data forwarding for the devices they own. This differentiation is done to allow experimental features, such as forwarding, to be tested in a more restricted environments and see how they scale. researcher roles do not have throttling on API requests, while citizen requests are limited to 90 requests/minute. Beyond these two differences, there is no other impact on the data or actions allowed. You can write us to have researcher access at our support mail.
Update Current User
PATCH https://api.smartcitizen.me/v0/me
http PATCH https://api.smartcitizen.me/v0/me access_token=randomToken1234
@@ -1114,73 +1034,11 @@ Update Current User
"uuid": "feca2180-d0dd-49fd-8815-ec59ca6d48f6"
}
An authenticated user can update their own details. They have the same parameters used as adding a user
+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
# new way
-curl -XPATCH 'https://api.smartcitizen.me/v0/me?access_token=MYAPITOKEN' --form "profile_picture=@mypicture.jpeg"
-http -f PATCH 'https://api.smartcitizen.me/v0/me access_token=MYAPITOKEN' profile_picture@mypicture.jpeg
-
-# old way
-http PATCH https://api.smartcitizen.me/v0/me/avatar access_token=9d00b4c027f757ef1c5 filename=new-avatar.jpg
-HTTP/1.1 200 OK
-{
- "key": "avatars/fec/1armjai.new-avatar.jpg",
- "policy": "eyJleHBpcmF0aW9uIjoiMjAxNS0wNy0zMVQxMDozMToyNloiLCJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJzbWFydGNpdGl6ZW4ifSxbInN0YXJ0cy13aXRoIiwiJGtleSIsImF2YXRhcnMvZmVjLzFhcm1qYWkubmV3LWF2YXRhci5qcGciXSx7ImFjbCI6InB1YmxpYy1yZWFkIn0seyJzdWNjZXNzX2FjdGlvbl9zdGF0dXMiOiIyMDAifSxbImNvbnRlbnQtbGVuZ3RoLXJhbmdlIiwwLDEwNzM3NDE4MjRdXX0=",
- "signature": "eIvTwQf+vPfvZJ/nV/Q1a2L3rJE="
- // New way returns this:
- "profile_picture": "https://api.smartcitizen.me/rails/active_storage/blobs/zc...c1/mypicture.jpeg",
-}
-There are 2 ways of uploading avatars.
- -This is the new way (using Rails Active Storage):
+This is the only supported way, using Rails Active Storage:
curl -XPATCH 'https://api.smartcitizen.me/v0/me?access_token=MYAPITOKEN' --form "profile_picture=@mypicture.jpeg"
Step 1 of 2 (Old method)
-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
http POST https://api.smartcitizen.me/v0/password_resets?username=testing
HTTP/1.1 200 OK
{
@@ -1188,7 +1046,7 @@ Reset a Password
}
# password reset email has been sent to user: testing
Step 1 of 4
-Initiate the password reset
+Initiate the password reset.
POST https://api.smartcitizen.me/v0/password_resets?email_or_username=username
Reset a Password
} ...-
This endpoint retrieves all users.
+This endpoint retrieves all users. This returns the same fields as the me endpoint if authenticated and authorized. Private fields are returned as [FILTERED].
Get a User
GET https://api.smartcitizen.me/v0/users/(:id|:username)
http https://api.smartcitizen.me/v0/users/2
@@ -1596,7 +1454,7 @@ Get a User
]
}
This endpoint retrieves a specific user.
+This endpoint retrieves a specific user. If authenticated, it will return the same fields as the me endpoint if authenticated and authorized. Private fields are returned as [FILTERED].
URL Parameters
| ID or username | -The ID or username of the user to retrieve | +The ID (int) or username (string) of the user to retrieve. |
Devices
World Map of Devices
-GET https://api.smartcitizen.me/v0/devices/world_map
http GET https://api.smartcitizen.me/v0/devices/world_map
+Devices
Get a Device
+GET https://api.smartcitizen.me/v0/devices/:id
+http GET https://api.smartcitizen.me/v0/devices/1616
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,
+ "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": [
- "indoor",
- "offline"
+ "offline",
+ "outdoor"
],
- "exposure": "indoor",
+ "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": {
- "": "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
+ "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
+ }
+ ]
},
- "added_at": "2015-02-02T15:59:51Z"
+ "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 an array with of summarized device objects for displaying on the world map.
-
-
-
-
+Returns a single device. Example of a complete response - http://api.smartcitizen.me/v0/devices/1616
-Parameter
+Field
Example
Description
@@ -1674,11 +1677,16 @@ Devices
World Map of Devices<
id*
integer
1619
-Unique ID of the device
+Incremental, unique ID of the device
+
+
+uuid*
uuid
+"fc9d12cf-b3aa-4030-9abf-2315e8f8a65d"
+Unique ID for the device
name
string
-Long Lane, SE1 (new)
+My amazing sensor
Name of the device
@@ -1687,106 +1695,299 @@ Devices
World Map of Devices<
Description of the device
-owner_id*
integer
-848
-Unique ID of the device's owner
+state
string
+"has_published"
+(Automatic) state of the device. See state.
-owner_username
string
-dankarran
-Unique username of the device's owner
+system_tags
string array
+['new', 'indoor']
+See system_tag values table below.
-latitude
decimal
-51.4996843
-Latitude of the device
+user_tags
string array
+['new', 'indoor']
+An Array of user tags, predefined from a specific list available in tags.
-longitude
decimal
--0.086883400000033
-Longitude of the device
+last_reading_at*
datetime
+"2015-04-30T17:56:04.432Z"
+Last reading from any of the sensors of the device.
-city
string
-Southwark
-City of the device
+created_at*
datetime
+"2015-04-30T17:56:04.432Z"
+When the device was created in the platform.
-country_code
string
-GB
-Alpha-2 Country Code of the device
+updated_at*
datetime
+"2015-04-30T17:56:04.432Z"
+When the device info was last updated (it does not get modified by new data).
-kit_id
integer
-3
-Kit that the device belongs to
+notify.stopped_publishing
bool
+true
+Notification setting in case the device stopped publishing
-state
string
-not_configured
-See state values table below
+notify.low_battery
bool
+false
+Notification setting in case the device has low battery
-system_tags
string array
-['new', 'indoor']
-See system_tag values table below
+device_token
string
+123abc
+Device token (secret)
-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.
+postprocessing
postprocessing
+-
+See data postprocessing
-added_at*
datetime
-"2015-04-30T17:56:04.432Z"
-When the device was added to the platform
+location
location
+See location
+Object containing device's location
+
+
+data_policy
policy
+See data policy
+Object containing device's data policy
+
+
+hardware
hardware
+See hardware
+Object containing device's hardware information
+
+
+owner*
owner
+See owner
+Device's owner information
+
+
+data
data
+See data
+Data object containing the device's sensors and latest readings
-Possible values for state
+Location
+This object contains information on the device location. Lat/long precision is set to 5 digits (equivalent to a resolution of meters). An optional location blurring feature can be enabled with the precise_location feature in the data policy field, for those cases that seek to preserve their location privacy (although the device owner place the pin at a different location at their own will). If precise_location is not enabled, the lat/long precision will still be 5 digits, but the location will be blurred keeping only up to 3 digits of accuracy (hundred meters).
+
-Key
-Value
+Field
+Example
+Description
-not_configured
-Device has been added to the platform but we do not have its MAC address
+location.ip
decimal
+
-never_published
-Device has been added, we have the MAC but no readings have been received
+location.exposure
string
+"indoor"
+Indoor or Outdoor
-has_published
-At least one reading has been recorded, submitted and saved to the platform
+location.elevation
decimal
+25
+Elevation of the location where the device is placed
-archived
-The device has been temporarily removed from the platform
+location.longitude
decimal
+-0.08622
+Longitude of the location where the device is placed
-
-Possible values for system_tag
-
-String
-Description
+location.latitude
decimal
+50.43231
+Latitude of the location where the device is placed
-
-new
-The device was added to the platform less than 7 days ago
+location.city
string
+Southwark
+City where the device is located
-indoor
-The device is placed indoors
+location.country_code
string
+GB
+Alpha-2 Country Code where the device is located
-outdoor
-The device is placed outdoors (default)
+location.country
string
+Great Britain
+Country where the device is located
-Add a Device
+Data postprocessing
+This information is used to process data on those devices that require some automated data processing tools. Check the docs for more information.
+Data Policy
+This is used to define the user's priority on their device.
+
+
+
+Field
+Example
+Description
+
+
+
+data_policy.is_private
bool
+false
+If the device is private or not. This hides the device to other users
+
+
+data_policy.enable_forwarding
bool
+false
+If the device has data forwarding enabled. Currently only available to researchers (see users)
+
+
+*data_policy.precise_location *
bool
+false
+If the device has a precise location enabled. The user can't store a precise location if this is disabled. See location
+
+
+Hardware
+This object represents the device hardware information.
+
+
+
+Field
+Example
+Description
+
+
+
+hardware.name
string
+"SCK 2.1 with CO2"
+Complete name of the device, including hardware definition and version
+
+
+hardware.type
string
+"SCK"
+If the hardware is a SCK or other type
+
+
+hardware.version
string
+"2.1"
+Hardware version, ideally in a major.minor format
+
+
+hardware.slug
string
+"sck,2.1"
+For internal use only
+
+
+hardware.last_status_message
status
+See status
+Status message by the device
+
+
+Status
+This message is delivered by Smart Citizen devices via MQTT through the info topic. This is used to retrieve firmware information, and potential debugging information. This is filtered for unauthorised requests.
+
+
+
+Field
+Example
+Description
+
+
+
+id
string
+AFF32AD50515157382E3120FF152B26
+Serial Number of the main microcontroller
+
+
+mac
string
+86:0D:8E:A7:4E:7D
+MAC address of the Wi-Fi Antenna
+
+
+time
datetime
+2024-10-03T03:00:18Z
+When the last status message was received
+
+
+esp_bd
datetime
+2024-10-03T03:00:18Z
+When the Wi-Fi antenna firmware was built
+
+
+hw_ver
string
+2.1
+Hardware version
+
+
+rcause
string
+SYST
+Reason for last reset of the device
+
+
+sam_bd
datetime
+2024-10-03T03:00:18Z
+When the main microcontroller firmware was built
+
+
+esp_ver
string
+0.9.8-48c75ee-master
+Wi-Fi antenna firmware version
+
+
+sam_ver
string
+0.9.8-48c75ee-master
+Main microcontroller firmware version
+
+
+State
+Represents the device state, defined in an automated way by the platform.
+
+Field | Example | Description
+ | Description
+--- | -----
+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
+System Tags
+
+
+String
+Description
+
+
+
+new
+The device was added to the platform less than 7 days ago
+
+
+indoor
+The device is placed indoors
+
+
+outdoor
+The device is placed outdoors (default)
+
+
+Data
+This object contains the latest readings for the device.
+
+
+
+Field
+Example
+Description
+
+
+
+sensors
array of sensors
+[sensor]
+An array of sensor objects, with the latest reading value, prev_value, and date of the reading injected into them. It also includes measurement associated with each.
+
+
+Add a Device
POST https://api.smartcitizen.me/v0/devices
http 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
@@ -1968,367 +2169,31 @@ Update a Device
string
string
indoor or outdoordecimal
decimal
Get a Device
-GET https://api.smartcitizen.me/v0/devices/:id
http 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 | ++ | A comma-seperated list of tag names more info | |
| location.country_code string |
-US | -Alpha-2 country code where the device is | +exposure string |
++ | Either indoor or outdoor |
| location.country string |
-United States | -Country name generated from country_code |
+latitude decimal |
+41.401108 | +Latitude of the device |
| sensors array |
-[sensor, sensor] | -An array of sensor objects, with the value (final calibrated reading) and raw_value (uncalibrated reading) injected into them. |
+longitude decimal |
+2.215319 | +Longitude of the device |
Remove a Device
+DELETE https://api.smartcitizen.me/v0/devices/:id
http 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.
Get All Devices
GET https://api.smartcitizen.me/v0/devices
http GET https://api.smartcitizen.me/v0/devices
@@ -2544,16 +2409,119 @@ Get All Devices
When included, returns devices in order of distance from the coordinates
-Remove a Device
-DELETE https://api.smartcitizen.me/v0/devices/:id
-http DELETE https://api.smartcitizen.me/v0/devices/10
+World Map of Devices
+GET https://api.smartcitizen.me/v0/devices/world_map
+http 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"
+}
+...
-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.
+Returns an array with of summarized device objects for displaying on the world map.
+
+
+
+
+
+
+
+Field
+Example
+Description
+
+
+
+id*
integer
+1619
+Incremental, unique ID of the device
+
+
+name
string
+My amazing sensor
+Name of the device
+
+
+description
string
+An SCK in Southwark
+Description of the device
+
+
+state
string
+"has_published"
+(Automatic) state of the device. See state.
+
+
+system_tags
string array
+['new', 'indoor']
+See system_tag values table below.
+
+
+user_tags
string array
+['new', 'indoor']
+An Array of user tags, predefined from a specific list available in tags.
+
+
+last_reading_at*
datetime
+"2015-04-30T17:56:04.432Z"
+Last reading from any of the sensors of the device.
+
+
+location
location
+See location
+Object containing device's location
+
+
+hardware
hardware
+See hardware
+Object containing device's hardware information
+
+
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.
+Every device has sensor(s). A sensor is something on a device that can record data. This could be anything: temperature, noise, humidity, voltage...
Get all Sensors
GET https://api.smartcitizen.me/v0/sensors
http GET https://api.smartcitizen.me/v0/sensors
@@ -2572,7 +2540,7 @@ Get all Sensors
}
...
-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.
+Since real-world sensors can contain multiple sub-sensors. For instance, the Sensirion SHT31 records temperature and humidity, in a single package. To represent this, we use the concept of parent. If a sensor has a parent then it is a sub-sensor. You can find which sensor a sub-sensors belongs to with the parent_id.
@@ -2589,16 +2557,36 @@ Get all Sensors
Unique ID for the sensor
+parent_id*
integer
+ID of the parent (null if none)
+
+
name
string
-Name of the user
+Name of the sensor
description
string
-Description of the user
+Description of the sensor
+
+
+datasheet
string
+Link to the sensor datasheet
unit
string
-The unit of measurement that is recorded with the sensor
+The unit of measurement for readings recorded with the sensor
+
+
+unit_definition
string
+Link to the vocabulary for the unit
+
+
+measurement
measurement
+Measurement taken with the sensor
+
+
+tags
sensortag
+Sensor tag
created_at*
datetime
@@ -2945,7 +2933,7 @@ Request Parameters
Response
-Parameter
+Field
Description
@@ -3106,7 +3094,7 @@ Post Readings
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.
-http POST https://api.smartcitizen.me/v0/devices/1816/readings?access_token=XEGwy6BsEybbz3BjYxemxfTQcHjAAJ1
+http POST https://api.smartcitizen.me/v0/devices/1816/readings?access_token=xxxxxxxxxxx
{
"data": [{
"recorded_at": "2016-06-08 10:30:00",
@@ -3191,366 +3179,8 @@ Sensor Parameters
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
-http 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
-http 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.
+Measurements
+Measurements help us understand what Sensors are recording.
Get All Measurements
GET https://api.smartcitizen.me/v0/measurements
http GET https://api.smartcitizen.me/v0/measurements
@@ -3589,6 +3219,10 @@ Get All Measurements
Description of the measurement
+definition
string
+Link to a vocabulary defining the measurement
+
+
created_at*
datetime
When the measurement was added to the platform
@@ -3610,26 +3244,11 @@ Get a single Measurement
"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
-http 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"
-}
-...
-
+Components are used to join Devices to Sensors. These are not accessible via the API, but are documented here for reference in case you deploy the platform yourself.
+
-Parameter
+Field
Description
@@ -3642,12 +3261,8 @@ Get All Components
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)
+device_id*
integer
+ID of the Device that the component is associated with
sensor_id*
integer
@@ -3655,14 +3270,16 @@ Get All Components
created_at*
datetime
-When the measurement was added to the platform
+When the component was added to the platform
updated_at*
datetime
-When the measurement was updated on the platform
+When the component was updated on the platform
-Tags
Get all Tags
+Tags
+Tags are used on devices to group them in flexible ways.
+Get all Tags
GET https://api.smartcitizen.me/v0/tags
GET https://api.smartcitizen.me/v0/tags
@@ -3698,6 +3315,16 @@ Tags
Get all Tags
Further information about the tag
+
+created_at*
datetime
+When the tag was added to the platform
+
+
+updated_at*
datetime
+When the tag was updated on the platform
+
Adding/editing a device's tags
PATCH https://api.smartcitizen.me/v0/devices/:id
@@ -3716,6 +3343,10 @@ Updating a Tag
Deleting a Tag
DELETE https://api.smartcitizen.me/v0/tags/:id
Admin only
+Sensor Tags
+Sensor tags are not available via the API. This documentation is included only for reference.
+
+Sometimes, it's useful to associate tags to sensors, to make it easier to understand what the are. For instance, a Carbon monoxide sensor may record voltages, and we may want to consider those readings as raw. This is represented with SensorTags. However, since voltage can be also used for measuring electric properties, we use these tags, and not other ad-hoc measurements to avoid duplication.
Response Status Codes
Error Messages
HTTP/1.1 404 Not Found
{
"id" : "record_not_found",
@@ -3809,7 +3440,7 @@ Error Codes
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.
@@ -3853,7 +3484,20 @@ Websockets
Live demo: http://codepen.io/pral2a/pen/jrPNzy
-Onboarding
Start onboarding process
+Data forwarding
+
+MQTT
+Instead of using websockets, you can also use MQTT, to get rendered data from the devices in real-time. This can help into bringing MQTT features such as persistent sessions and allow for a more robust data ingestion. We support MQTT/s, MQTT over SSL/TLS, like HTTPS. Everytime a device publishes data to the platform data is pushed over, with the same model as device GET.
+
+MQTT forwarding is only enabled if the user is a researcher (see users) and if they have enabled forwarding on their device. See data policy on the device section. You need to collect your forwarding_username and forwarding_token secrets from the users endpoint after an authenticated request.
+# You will need mosquitto (and mosquitto_sub) for this
+mosquitto_sub -h mqtt.smartcitizen.me -u '<forwarding_username>' -t '/forward/<forwarding_token>/device/<device_id>/readings' -v
+
+# You can get all the devices from a user
+mosquitto_sub -h mqtt.smartcitizen.me -u '<forwarding_username>' -t '/forward/<forwarding_token>/device/+/readings' -v
+
+# Note that wildcard topics at the /forward level are not allowed
+
Onboarding
Start onboarding process
POST https://api.smartcitizen.me/v0/onboarding/device
http POST https://api.smartcitizen.me/v0/onboarding/device