Getting Started

In this tutorial we will guide your through the process of creating a sensor, uploading some data and then retrieving the data on CommonSense. While this is but a fraction of the functionality of the CommonSense, it should leave you with a clear idea of how the API works, and should allow you to understand the API Reference.

The CommonSense API is based on HTTP requests, and so you need to be able to perform your own, customized API requests to interact with the API. Before moving into the tutorial, you will have to select your favorite tool to do this. If you are new to the process of performing HTTP requests, you can use an online tool like HurlIt.

The instructions in this tutorial should be generic enough to help you perform the requests using any tool, but we will not give any tool specific information.

Finally, it is important to note that we use https calls in this tutorial. While it is possible to perform unsecured calls, we strongly advise you make secure calls.

Step 1: Creating an Account

The first step is to create an account if you do not have one already. You can request an account at Account Creation. After leaving your email address, we will get in touch with you and provide an account asap!

Step 2: Log In

Now, you are ready to perform your first API call and log in to CommonSense. This will yield you a session id, which can be used to perform further API calls. This call will include sending an MD5 hash of your password. You can obtain this using an online tool, for instance this one.

Call:

  • Method POST
  • URL https://api.sense-os.nl/login

Headers:

  • Accept application/json

Parameters:

  • username username
  • password password_md5

You should be able to retrieve a session id from the x-session_id response header. Make sure you record the session id, because you will need it in following calls.

Step 3: Create a Sensor

To be able to upload data to CommonSense, you first need a sensor for which you can upload data. You will have to give your sensors a name, a device_type which describes the make and model of the sensor, a display_name, and optionally a data_type. The description of your sensor is uploaded using a json format, as post data.

Call:

  • Method POST
  • URL https://api.sense-os.nl/sensors.json

Headers:

  • Accept application/json
  • X-SESSION_ID session_id

Post Data:

    {
        "sensor":{
            "name":"thermometer",
            "display_name":"Thermometer",
            "device_type":"TX-1000",
            "data_type":"float"
        }
    }

The call will return a 201 Created status. You can obtain the sensor id of your newly created sensor from location header: it will read something like: > location → http://api.sense-os.nl/sensors/206055

Make sure you record your sensor id, because you will need it in the next calls.

Step 4: Upload Data

Now that we have a sensors, lets give it some data. We can upload multiple data points at the same time, and give every data point a (UNIX) timestamp. If you don't give your data points a timestamp, CommonSense will timestamp them at the time they are received. The values of data points can be either a string (for instance containing an integer) or a json object. This means you can also store json objects as data points. In our example we will pretend we are uploading the temperature for the past couple of hours.

Call:

  • Method POST
  • URL https://api.sense-os.nl/sensors/sensor_id/data.json

Headers:

  • Accept application/json
  • X-SESSION_ID session_id

Post Data:

    {
        "data":[
            {
                "value":"25.6",
                "date":"1351080000"
            },
            {
                "value":"26.2",
                "date":"1351083600"
            },
            {
                "value":"27.8",
                "date":"1351087200"
            },
            {
                "value":"27.9",
                "date":"1351090800"
            }
        ]
    }

This call will return 201 Created response status.

Step 5: Retrieve Data

Your application will probably want to retrieve some data to for instance plot it on your screen or to notify you when its hot enough outside to go out for ice-cream. When retrieving data, there are a number of different options, which we will not all go into right now, but be sure to check the API Reference!

Call:

  • Method GET
  • URL https://api.sense-os.nl/sensors/sensor_id/data.json

Headers:

  • Accept application/json
  • X-SESSION_ID session_id

Parameters:

  • start_date 1351079999
  • end_date 1351090801

This call should return a 200 OK status. In the response content you can find a json object containing the data points we uploaded earlier:

    {
        "data": [
            {
                "date": 1351080000,
                "id": "5087f418b4b7357310008f91",
                "month": 10,
                "sensor_id": 206055,
                "value": "25.6",
                "week": 43,
                "year": 2012
            },
            {
                "date": 1351083600,
                "id": "5087f418b4b7357310008f92",
                "month": 10,
                "sensor_id": 206055,
                "value": "26.2",
                "week": 43,
                "year": 2012
            },
            {
                "date": 1351087200,
                "id": "5087f418b4b7357310008f93",
                "month": 10,
                "sensor_id": 206055,
                "value": "27.8",
                "week": 43,
                "year": 2012
            }.
            {
                "date": 1351090800,
                "id": "5087f418b4b7357310008f94",
                "month": 10,
                "sensor_id": 206055,
                "value": "27.9",
                "week": 43,
                "year": 2012
            }
        ]
    }

Step 6: Log Out

Once you are done with your session, it is nice to log out again so that CommonSense can delete your session id.

Call:

  • Method POST
  • URL https://api.sense-os.nl/logout

Headers:

  • Accept application/json
  • X-SESSION_ID session_id

This will once again return a 200 OK status, and from that moment on your session id will not work anymore.

Step 7: Profit!

Now its time to start building your own application that uses CommonSense. Take a look at the API Reference for a full list of functions, or head over to the API Libraries to see which languages already have a library full of supportive functions.