2.6. Sensor Data

In the WoTKit, sensor data consists of a timestamp followed by one or more named fields. There are a number of reserved fields supported by the WoTKit:

  Reserved field name Description
(OPTIONAL) timestamp the time that the sensor data was collected. This is an ISO 8601 timestamp (for example Jan 1, 1970 UTC in ISO 8601: 1970-01-01T00:00:00Z) Optional; if not supplied, a server-supplied timestamp will be used.
(READ-ONLY) id a unique identifier for the data reading. This is to distinguish one reading from another when they share the same timestamp. This field is read only and should not be sent by the client when sending new data.
(READ-ONLY) sensor_id the globally unique sensor id that produced the data. This is a read only field generated by the wotkit that should not be sent by a client when sending new data.
(READ-ONLY) sensor_name the globally unique sensor name, in the form {username}.{sensorname}. This is a read only field and should not be sent by the client when sending new data.

When a new sensor is created, a number of default fields are created by the wotkit for a sensor as follows. Note that these can be changed by editing the sensor fields.

Default field name Description
lat the current latitude location of the sensor in degrees (number). Needed for map visualizations.
lng the current longitude location of the sensor in degrees (number). Needed for map visualizations.
value the primary value of the sensor data collected (number). Needed for most visualizations.
message a text message, for example a twitter message (text). Needed for text/newsfeed visualizations.

In addition to these reserved fields, additional required or optional fields can be added by updating the sensor fields in the WoTKit UI or Sensor Fields in the API.

Note

Remember that * Python’s time.time() function generates the system time in seconds, not milliseconds. To convert this to an integer in milliseconds use int(time.time()*1000). Using Java you can obtain the timestam in milliseconds via System.currentTime().

2.6.1. Sending New Data

To send new data to a sensor, POST name value pairs corresponding to the data fields to the /sensors/{sensorname}/data URL.

Any fields marked as required must be provided, or an error will be returned. There is no need to provide a timestamp since it will be assigned by the server. Data posted to the system will be processed in real time.

Note

When sending name value pairs that are not specified by the sensor’s fields the server will save the data without a type. When adding a new field after sending this data WoTKit will make an attempt to cast the recorded data to the type specified by the new field.

To send new data:

URL http://wotkit.sensetecnic.com/api/v1/sensors/{sensorname}/data
Privacy Private
Format json or x-www-form-urlencoded
Method POST
Returns 201 Created if successful.

You can POST data as either application/json or appliction/x-www-form-urlencoded.

An example of POSTing using www-form-urlencoded data would be:

example

curl --user {username}:{password} --request POST
-d value=5 -d lng=6 -d lat=7 'http://wotkit.sensetecnic.com/api/v1/sensors/{username}.{sensorname}/data'

The same example using JSON would be:

example

curl --user {username}:{password} --request POST -H 'Content-Type: application/json'
-d '{"value":5, "lng":6, "lat":7}' 'http://wotkit.sensetecnic.com/api/v1/sensors/{username}.{sensorname}/data'

2.6.2. Sending Bulk Data

To send a range of data, you PUT data (rather than POST) data into the system.

  • The data sent must contain a list of JSON objects, any fields marked as required in the sensor fields must be contained in each JSON object.
  • If providing a single piece of data, existing data with the provided timestamp will be deleted and replaced. Otherwise, the new data will be added.
  • If providing a range of data, any existing data within this timestamp range will be deleted and replaced by the new data.

Note

The data sent does not require a timestamp. If the timestamp is omitted WoTKit will use the current server time. Again, any fields marked as required must be provided.

To update data:

URL http://wotkit.sensetecnic.com/api/v1/sensors/{username}.{sensorname}/data
Privacy Private
Format json
Method PUT
Returns ****HTTP status code; No Response 204 if successful

Example of valid data:

[{"timestamp":"2012-12-12T03:34:28.626Z","value":67.0,"lng":-123.1404,"lat":49.20532},
{"timestamp":"2012-12-12T03:34:28.665Z","value":63.0,"lng":-123.14054,"lat":49.20554},
{"timestamp":"2012-12-12T03:34:31.621Z","value":52.0,"lng":-123.14063,"lat":49.20559},
{"timestamp":"2012-12-12T03:34:35.121Z","value":68.0,"lng":-123.14057,"lat":49.20716},
{"timestamp":"2012-12-12T03:34:38.625Z","value":51.0,"lng":-123.14049,"lat":49.20757},
{"timestamp":"2012-12-12T03:34:42.126Z","value":55.0,"lng":-123.14044,"lat":49.20854},
{"timestamp":"2012-12-12T03:34:45.621Z","value":56.0,"lng":-123.14215,"lat":49.20855},
{"timestamp":"2012-12-12T03:34:49.122Z","value":55.0,"lng":-123.14727,"lat":49.20862},
{"timestamp":"2012-12-12T03:34:52.619Z","value":59.0,"lng":-123.14765,"lat":49.20868}]

example

curl --user {username}:{password} --request PUT -H "Content-Type: application/json" --data-binary @data.txt 'http://wotkit.sensetecnic.com/api/v1/sensors/{username}.{sensorname}/data'

where data.txt contains JSON data similar to the above JSON array.

2.6.3. Deleting Data

Currently you can only delete data by timestamp, where timestamp is in numeric or ISO form. Note that if more than one sensor data point has the same timestamp, they all will be deleted.

To delete data:

URL http://wotkit.sensetecnic.com/api/v1/sensors/{sensorname}/data/{timestamp}
Privacy Private
Format n/a
Method DELETE
Returns 204 No Content if successful.

2.6.4. Raw Data Retrieval

To retrieve raw data use the following:

URL http://wotkit.sensetecnic.com/api/v1/sensors/{sensor-name}/data?{query-params}
Privacy Public or Private
Format json
Method GET
Returns 200 OK on success. A JSON object in the response body containing a list of timestamped data records.

The query parameters supported are the following:

Name Value Description
start the absolute start time of the range of data selected in milliseconds. (Defaults to current time.) May only be used in combination with another parameter.
end the absolute end time of the range of data in milliseconds
after the relative time after the start time, e.g. after=300000 would be 5 minutes after the start time (Start time MUST also be provided.)
afterE the number of elements after the start element or time. (Start time MUST also be provided.)
before the relative time before the start time. E.g. data from the last hour would be before=3600000 (If not provided, start time default to current time.)
beforeE the number of elements before the start time. E.g. to get the last 1000, use beforeE=1000 (If not provided, start time default to current time.)
reverse true: order the data from newest to oldest; false (default):order from oldest to newest

Note

These queries looks for timestamps > “start” and timestamps <= “end”

2.6.5. Formatted Data Retrieval

To retrieve data in a format suitable for Google Visualizations, we support an additional resource for retrieving data called dataTable.

URL http://wotkit.sensetecnic.com/api/v1/sensors/{sensor-name}/dataTable?{query-params}
Privacy Public or Private
Format json
Method GET
Returns 200 OK on success. A formatted JSON object in the response body containing a list of timestamped data records.

This resource is similar to Raw Data Retrieval, but adds two parameters: tqx and tq. You can read more about these parameters at the specification document: Chart Tools Datasource Protocol.

The complete list of available parameters is:

Name Value Description
start the absolute start time of the range of data selected in milliseconds. (Defaults to current time.) May only be used in combination with another parameter.
end the absolute end time of the range of data in milliseconds
after the relative time after the start time, e.g. after=300000 would be 5 minutes after the start time (Start time MUST also be provided.)
afterE the number of elements after the start element or time. (Start time MUST also be provided.)
before the relative time before the start time. E.g. data from the last hour would be before=3600000 (If not provided, start time default to current time.)
beforeE the number of elements before the start time. E.g. to get the last 1000, use beforeE=1000 (If not provided, start time default to current time.)
reverse true: order the data from newest to oldest; false (default):order from oldest to newest
tqx A set of colon-delimited key/value pairs for standard parameters, defined here.
tq A SQL clause to select and process data fields to return, explained here.

Note

When using tq sql queries, they must be url encoded. When using tqx name/value pairs, the reqId parameter is necessary.

For instance, the following would take the “sensetecnic.mule1”, select all data where value was greater than 20, and display the output as an html table.


The following combines SQL filtering and formatting with a range to output the last 100 elements of the sensor where the value is greater than 55, formated using HTML:


An example response, limited to the last 5 elements will return 3 elements, in the form:

google.visualization.Query.setResponse (
  {
    "version": "0.6",
    "status": "ok",
    "sig": "582888298",
    "table": {
    "cols": [
      {
        "id": "sensor_id",
        "label": "Sensor Id",
        "type": "number",
        "pattern": ""
      },
      {
        "id": "sensor_name",
        "label": "Sensor Name",
        "type": "string",
        "pattern": ""
      },
      {
        "id": "timestamp",
        "label": "Timestamp",
        "type": "datetime",
        "pattern": ""
      },
      {
        "id": "lat",
        "label": "latitude",
        "type": "number",
        "pattern": ""
      },
      {
        "id": "lng",
        "label": "longitude",
        "type": "number",
        "pattern": ""
      },
      {
        "id": "value",
        "label": "Speed",
        "type": "number",
        "pattern": ""
      },
      {
        "id": "message",
        "label": "Message",
        "type": "string",
        "pattern": ""
      }
    ],
    "rows": [


      {
        "c":[
          {"v":1.0},
          {"v":"sensetecnic.mule1"},
          {"v":new Date(2014,3,28,16,20,13)},
          {"v":49.22522},{"v":-123.166},
          {"v":66.0},{"v":null}
        ]
      },
      {
        "c":[
          {"v":1.0},
          {"v":"sensetecnic.mule1"},
          {"v":new Date(2014,3,28,16,20,16)},
          {"v":49.22422},
          {"v":-123.16398},
          {"v":58.0},
          {"v":null}
        ]
       },
      {
        "c":[
          {"v":1.0},
          {"v":"sensetecnic.mule1"},
          {"v":new Date(2014,3,28,16,20,20)},
          {"v":49.22307},
          {"v":-123.16276},
          {"v":58.0},
          {"v":null}
        ]
      }
    ],
    "p": {
      "lastId": "2014-06-19T22:45:36.281Z"
    }
  }
}
)

2.6.6. Aggregated Data Retrieval

Aggregated data retrieval allows one to receive data from multiple sensors, queried using the same parameters as when searching for sensors or sensor data. The query must be specified using one of the following 5 patterns.

Pattern 1 - With Start/End

start The most recent starting time of the query. This value is optional and defaults to the current time.
end A timestamp before the start time.
limit Specifies the limit to return. This value is optional, with a default value of 1000.
offset Specifies the offset to return. This value is optional, with a default value of 0.

Pattern 2 - With Start/After

start A starting timestamp.
after A relative timestamp after start.
limit Specifies the limit to return. This value is optional, with a default value of 1000
offset Specifies the offset to return. This value is optional, with a default value of 0

Pattern 3 - With Start/Before

start A starting timestamp.
before A relative timestamp before start.
limit Specifies the limit to return. This value is optional, with a default value of 1000
offset Specifies the offset to return. This value is optional, with a default value of 0

Pattern 4 - With Start/BeforeE

start A starting timestamp.
beforeE The number of elements to return before start
offset Specifies the offset to return. This value is optional, with a default value of 0

Pattern 5 - With Start/AfterE

start A starting timestamp.
afterE The number of elements to return after start
offset Specifies the offset to return. This value is optional, with a default value of 0

The following parameters may be added to any of the above patterns:

  • scope
  • tags
  • private (deprecated, use visibility instead)
  • visibility
  • text
  • active
  • location (in the form: “location=-31.257,-12.55:-21.54,9.65”)
  • metadata
  • groups

To receive data from more that one sensor, use the following:

URL http://wotkit.sensetecnic.com/api/v1/data?{query-param}={query-value}&{param}={value}...
Privacy Public or Private
Format json
Method GET
Returns 200 OK on success. A JSON object in the response body containing a list of timestamped data records.