-
Notifications
You must be signed in to change notification settings - Fork 0
Timestreams API Documentation
Timestreams is an API that provides functions to add and organise sensor data. It allows you to connect information from your community or school with your blog and the rest of the world.
Timestreams supports an XML-RPC API which can be called by an external client to create sensor measurement containers, add readings, metadata, contextual information, timestreams, and find such data. Timestreams has a reference implementation for WordPress. The Timestreams API extends the native Wordpress XML-RPC API so all of the native functions are available as well within the reference implementation.
The Timestreams API is built around data-classes describing measurements, metadata, documentation, context, and timestreams. This document describes the XML-RPC functions that are available to manipulate these data-classes. To use the API you will need a server implementation of it. Follow the instructions to install the API reference implementation. To use the reference implementation post XML procedure calls to your Wordpress installation's xmlrpc.php page. cURLis a useful tool to use to test your calls. The following is an example using curl to make an XML-RPC call:
curl --noproxy localhost -d "<?xml version=\"1.0\" encoding=\"iso-8859-1\"?><methodCall><methodName>timestreams.insert_reading</methodName><params><param><value><string>USERNAME</string></value></param><param><value><string>PASSWORD</string></value></param><param><value><string>wp_1_ts_temperature_1</string></value></param><param><value><string>6.7</string></value></param><param><value><string>2012-03-02 00:34:00</string></value></param></params></methodCall>" http://localhost/wordpress/xmlrpc.php
Calls return XML-RPC responses. Errors are passed as param values rather than faults (owing to a Wordpress limitation). The following is an example response:
<?xml version="1.0"?> <methodResponse> <params> <param> <value> <string>wp_2_ts_SomeMeasurementType_9</string> </value> </param> </params> </methodResponse>
Currently the first two parameters of all procedure calls are the username and password corresponding to a given blog user. In the future it is expected that these parameters will be replaced with OAuth API authorization.
The following lists the XML-RPC procedures by data-class:
Measurements contain values at given points in time for blog instance devices.
| Attribute | Description | Required |
|---|---|---|
| [type][blog_id]_[device_id]_id | Id of this measurement | Yes |
| value | Measurement reading | Yes |
| timestamp | The time the measurement was taken | Yes |
The following functions are avaialable to manipulate measurements:
- timestreams.create_measurements
- timestreams.create_measurementsForBlog
- timestreams.add_measurement
- timestreams.add_measurements
- timestreams.select_measurements
- timestreams.select_first_measurement
- timestreams.select_latest_measurement
- timestreams.count_measurements
Certain types of files such as wbecam images taken periodically are also considered as measurements and can be stored using the following API procedures. Uploaded files use the same schema as measurement data, with the uploaded file's URL being stored within the value field.
Metadata records describe measurement containers and the type of data contained within.
| Attribute | Description | Required |
|---|---|---|
| metadata_id | Id of a metadata record | Yes |
| tablename | Corresponding measurement container name | Yes |
| measurement_type | The data-class (such as temperature or CO2) that the corresponding measurement container is recording data for | Yes |
| min_value | Minimum legal value | No |
| max_value | Maximum legal value | No |
| unit | The unit of measurement (such as Celsius) | Yes |
| unit_symbol | The symbol associated with the given unit of measurement (such as C) | No |
| device_details | Information pertaining to the device that took the measurement | No |
| other_info | Anything else useful to know about this measurement container | No |
| data_type | Any legal MySQL data type (usually a numeric type such as "DECIMAL(4,1)") | Yes |
The following functions are avaialable to inspect metadata records:
Documentation records contain timestamped file data such as images, videos and audio files. This part of the API is still under development.
Context records describe a range of time points. They are user defined key,value pairs that can help annotate the data. Examples of keys include place, activity or session.
| Attribute | Description | Required |
|---|---|---|
| context_id | Id of this context item | Yes |
| Context_type | The key (such as "place") | Yes |
| value | The context value (such as "Nottingham") | Yes |
| start_time | The timestamp this context record holds from | Yes |
| end_time | The timestamp this context record ceases to hold. If this value is not set, then the record is presume to continue to hold indefinitely. | No |
The following functions are avaialable to for context records:
- timestreams.add_context
- timestreams.select_context_by_type
- timestreams.select_context_by_value
- timestreams.select_context_by_type_and_value
- timestreams.select_context_within_time_range
- timestreams.update_context
Timestreams are series of data that can be played back.