3.1. 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 |
|---|---|
| timestamp | the time that the sensor data was collected. This is a long integer representing the number of milliseconds from Jan 1, 1970 UTC. Optional; if not supplied, a server-supplied timestamp will be used. |
| id | a unique identifier for the data reading. This is to distinguish one reading from another when they share the same timestamp. Read only; This field is read only and should not be sent by the client when sending new data. |
| sensor_id | the globally unique sensor id that produced the data. Read only; This is a read only field generated by the wotkit that should not be sent by a client when sending new data. |
| sensor_name | the globally unique sensor name, in the form {username}.{sensorname}. Read only; 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 default fields, additional fields can be added by updating the sensor fields in the WoTKit UI or Sensor Fields in the API.
Note
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).
In Javascript: var d = new Date(); d.getTime();
In Java: System.currentTime().
3.1.1. Sending New Data¶
To send new data to a sensor, POST name value pairs corresponding to the data
fields to /sensors/{sensorname}/data. There is no need to supply the sensor id, or sensor name fields since the sensor
is specified in the URL.
If a timestamp is not provided in the request body, it will be set to the current time by the the server.
To send new data:
| URL | http://wotkit.sensetecnic.com/api/v2/sensors/{sensorname}/data |
| Privacy | Private |
| Format | not applicable |
| Method | POST |
| Returns | 201 Created if successful. |
Example
curl --user {id}:{password} --request POST -d value=5 -d lng=6 -d lat=7
'http://wotkit.sensetecnic.com/api/v2/sensors/test-sensor/data'
3.1.2. Updating a Range of Historical Data¶
To insert or update a range of historical data, you PUT data (rather than POST) data into the system. Note that data PUT into the WoTKit will not be processed in real time, since it occurred in the past. Thus, a timestamp field is required.
- The request body must be a list of JSON objects, as specified in Sensor Data. In the case of updating existent data is that each objet MUST contain a timestamp value which will be updated.
Note
Any existing data matching the provided timestamp be deleted and replaced by the data supplied.
To update data:
| URL | http://wotkit.sensetecnic.com/api/v2/sensors/{sensorname}/data |
| Privacy | Private |
| Format | JSON |
| Method | PUT |
| Returns | 204 No Content if successful. 400 Bad Request if unsuccessful. |
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 {id}:{password} --request PUT --data-binary @data.txt
'http://wotkit.sensetecnic.com/api/v2/sensors/test-sensor/data'
where data.txt contains JSON data similar to the above JSON array.
3.1.3. Retrieving a Single Data Item¶
If you know the data element’s id, you can query for a single data element using the following query.
| URL | http://wotkit.sensetecnic.com/api/v2/sensors/{sensor-name}/data/{data_id} |
| Privacy | Public or Private, depending on sensor privacy |
| Format | json |
| Method | GET |
| Returns | 200 OK on success. A JSON object in the response body containing a list of timestamped data records. |
3.1.4. Retrieving Data Using Query¶
To retrive sensor data over a time range you can use the following endpoint. An interactive guide on how to use this endpoint is available at: Querying Sensor Data.
| URL | http://wotkit.sensetecnic.com/api/v2/sensors/{sensor-name}/data |
| Privacy | Public or Private, depending on sensor privacy |
| 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. They can only be used together if they appear in the same Group below.
| Parameter | Group | Type | Description |
|---|---|---|---|
recent_t |
1 | integer | Gets the elements up to recent_t milliseconds ago |
recent_n |
2 | integer | Gets the n recent elements |
start |
3 | timestamp | The absolute starting point (in milliseconds since Jan 1, 1970). |
start_id |
3 | id | The starting id of sensor_data at timestamp start. Used for paging and to distinguish data elements that share the same timestamp. |
end |
3 | timestamp | The absolute ending timestamp (in milliseconds since Jan 1, 1970) |
end_id |
3 | timestamp | The end id of sensor_data with timestamp end. Used for paging. |
limit |
[2,3] | integer | specifies how many datapoints to see on each response |
3.1.5. Delete Data by Id¶
Same as api-v2-get-single-data instead using HTTP Delete.
| URL | http://wotkit.sensetecnic.com/api/v2/sensors/{sensorname}/data/{data_id} |
| Privacy | Private |
| Format | not applicable |
| Method | DELETE |
| Returns | 204 No Content if successful. |
3.1.6. Delete Data using Data Query¶
Can delete using query parameters in Retrieving Data Using Query with the restriction on only using group 3 parameters.
| URL | http://wotkit.sensetecnic.com/api/v2/sensors/{sensorname}/data |
| Privacy | Private |
| Format | not applicable |
| Method | DELETE |
| Returns | 204 No Content if successful. |