Smart Citizen API

Smart Citizen Platform Open API

Welcome

The Smart Citizen API allows you to request back information from your devices and do incredible things with it.

It is a REST API and it returns the information in JSON format. This means you can easily access the information from any language like Javascript, PHP, Processing.org, Python, and start doing things with it quickly.

To access the API you will always need and api_key you can obtain here.

The API is currently under BETA more functions will be comming soon. Please, report any problem or suggestion on the forum.

Data

Data - Get Latest Data

Get back the latest updates from a user devices in order to do whatever you want. Check the examples to learn more and remember you need a valid api_key you can obtain here.

/v0.0.1/:api_key/lastpost.json

Examples

Request:

   http://api.smartcitizen.me/v0.0.1/6e0428e19cf2bff1a9c05d14d0400bf4/lastpost.json

Parameter

Field	Type	Description
api_key	String	User unique API Key. Obtain your key here.

Success (200)

Field	Type	Description
device	Json	Device information with the requested data posts.

Success-Response:

HTTP/1.1 200 OK
	 {
	  "device": {
	    "id": "24",
	    "title": "Pral2a",
	    "description": "Test",
	    "location": "Barcelona",
	    "city": "Barcelona",
	    "country": "Spain",
	    "exposure": "outdoor",
	    "elevation": "100.0",
	    "geo_lat": "41.383180",
	    "geo_long": "2.157960",
	    "created": "2013-04-24 18:09:05",
	    "last_insert_datetime": "2013-05-16 11:44:56",
	    "posts": [
	      {
	        "timestamp": "2013-05-01 19:46:51",
	        "temp": 21.6,
	        "hum": 51.8,
	        "co": 131054,
	        "no2": 75121,
	        "light": 24.2,
	        "noise": 50,
	        "bat": 92.9,
	        "panel": 4.41,
	        "nets": 6,
	        "insert_datetime": "2013-05-01 21:47:00"
	      }
	    ]
	  }
	}

Error (4xx)

Name	Description
invalidAPIKEY	Check on your platform profile you are using a valid `API KEY`.

Error-Response:

   HTTP/1.1 404 Not Found
   {
     "error": "Feed do not exist. Data not available"
   }

Data - Get Sensors Data

Get data back from one device in order to do whatever you want. You can request data by a time range and even retrieve averages agregated by days or hours. Check the examples to learn more and remember you need a valid api_key you can obtain here.

/v0.0.1/:api_key/:device_id/post.json?from_date=:from&to_date=:to&group_by=:range

Examples

Return the last update of device 24:

   http://api.smartcitizen.me/v0.0.1/6e0428e19cf2bff1a9c05d14d0400bf4/41/posts.json

Return the last day average of device 24:

   http://api.smartcitizen.me/v0.0.1/6e0428e19cf2bff1a9c05d14d0400bf4/41/posts.json?group_by=day

Return all the data from May 2013 of device 24:

   http://api.smartcitizen.me/v0.0.1/6e0428e19cf2bff1a9c05d14d0400bf4/41/posts.json?from_date=2013-05-01&to_date=2013-05-31

Return all the data averaged per day from May 2013 of device 24:

   http://api.smartcitizen.me/v0.0.1/6e0428e19cf2bff1a9c05d14d0400bf4/41/posts.json?from_date=2013-05-01&to_date=2013-05-31&group_by=day

Parameter

Field	Type	Description
api_key	String	User unique API Key. Obtain your key here.
device_id	Number	Device unique ID.
from optional	Date	Starting date `YYYY-MM-DD`. If not set gets a limit of 500 posts since the `to` date.
to optional	Date	Finish date `YYYY-MM-DD`. If not set gets the current date.
range optional	String["hour","day"]	Get data averaged by a range.

Success (200)

Field	Type	Description
device	Json	Device information with the requested data posts.

Success-Response:

HTTP/1.1 200 OK
	 {
	  "device": {
	    "id": "24",
	    "title": "Pral2a",
	    "description": "Test",
	    "location": "Barcelona",
	    "city": "Barcelona",
	    "country": "Spain",
	    "exposure": "outdoor",
	    "elevation": "100.0",
	    "geo_lat": "41.383180",
	    "geo_long": "2.157960",
	    "created": "2013-04-24 18:09:05",
	    "last_insert_datetime": "2013-05-16 11:44:56",
	    "posts": [
	      {
	        "timestamp": "2013-05-01 19:46:51",
	        "temp": 21.6,
	        "hum": 51.8,
	        "co": 131054,
	        "no2": 75121,
	        "light": 24.2,
	        "noise": 50,
	        "bat": 92.9,
	        "panel": 4.41,
	        "nets": 6,
	        "insert_datetime": "2013-05-01 21:47:00"
	      }
	    ]
	  }
	}

Error (4xx)

Name	Description
invalidAPIKEY	Check on your platform profile you are using a valid `API KEY`.

Error-Response:

   HTTP/1.1 404 Not Found
   {
     "error": "Feed do not exist. Data not available"
   }

Devices

Devices - Get Devices Info (BETA)

Get back all the devices on the platform in order to do whatever you want. This query is currently limited to selected api_key users, contact support in order to get a BETA key. Check the examples to learn more.

/api/:api_key/devices.json

Examples

Request:

http://api.smartcitizen.me/v0.0.1/6e0428e19cf2bff1a9c05d14d0400bf4/devices.json

Parameter

Field	Type	Description
api_key	String	User unique API Key. Obtain your key here.

Success (200)

Field	Type	Description
devices	Json	User information.

Success-Response:

HTTP/1.1 200 OK
{
  "devices": [
      {
        "id": "24",
        "title": "Pral2a",
        "description": "Test",
        "location": "Barcelona",
        "city": "Barcelona",
        "country": "Spain",
        "exposure": "outdoor",
        "elevation": "100.0",
        "geo_lat": "41.383180",
        "geo_long": "2.157960",
        "created": "2013-04-24 18:09:05",
        "last_insert_datetime": "2013-05-16 11:44:56"
      }
    ]
}

Error (4xx)

Name	Description
invalidAPIKEY	Check on your platform profile you are using a valid `API KEY`.
unauthorizedAPIKEY	Contact support in order to check you have a valid `API KEY`.

Error-Response:

   HTTP/1.1 404 Not Found
   {
     "error": "Feed do not exist. Data not available"
   }

Users

Users - Get User Info

Get back all the information about a user in order to do whatever you want. Check the examples to learn more and remember you need a valid api_key you can obtain here.

/v0.0.1/:api_key/me.json

Examples

Request:

   http://api.smartcitizen.me/v0.0.1/6e0428e19cf2bff1a9c05d14d0400bf4/me.json

Parameter

Field	Type	Description
api_key	String	User unique API Key. Obtain your key here.

Success (200)

Field	Type	Description
me	Json	User information.

Success-Response:

HTTP/1.1 200 OK
{
  "me": {
    "id": "5",
    "username": "Guillem",
    "city": "Barcelona",
    "country": "Spain",
    "website": "",
    "email": "[email protected]",
    "created": "2013-04-23 00:34:13",
    "devices": [
      {
        "id": "24",
        "title": "Pral2a",
        "description": "Test",
        "location": "Barcelona",
        "city": "Barcelona",
        "country": "Spain",
        "exposure": "outdoor",
        "elevation": "100.0",
        "geo_lat": "41.383180",
        "geo_long": "2.157960",
        "created": "2013-04-24 18:09:05",
        "last_insert_datetime": "2013-05-16 11:44:56"
      }
    ]
  }
}

Error (4xx)

Name	Description
invalidAPIKEY	Check on your platform profile you are using a valid `API KEY`.

Error-Response:

   HTTP/1.1 404 Not Found
   {
     "error": "Feed do not exist. Data not available"
   }

Generated with apiDoc 0.1.11 - 2013-09-25T17:03:37.904Z