Visualisation API

How to get data for a Timestreams Visualisation.

In short:

• ask the server what time it is
• optionally ask the server for a list of existing Timestreams, or you need to know the ID of a specific Timestream
• ask for the metadata that describes the datasource currently feeding the Timestream
• ask the server for an initial data set (the last 30 readings, for example)
• repeatedly ask the server for data that has arrived since you last asked

In practical terms:

• ask the server what time it is

Method name: timestreams.ext_get_time Arguments: username, password

timestreams.ext_get_time USERNAME PASSWORD

curl --noproxy localhost -d "timestreams.ext_get_timeUSERNAMEPASSWORD" http://localhost/relatedev/xmlrpc.php

returns the current server time in seconds. All queries involving a timestamp sent to the server should be relative to this timestamp to avoid time zone problems - i.e. calculate your local time offset from the server's current time, and apply this offset when telling the server when you last asked for something.

1346924718

• get a list of Timestreams.

Method name: timestreams.ext_get_timestreams Arguments: username, password

timestreams.ext_get_timestreams USERNAME PASSWORD

curl --noproxy localhost -d "timestreams.ext_get_timestreamsUSERNAMEPASSWORD" http://localhost/relatedev/xmlrpc.php

currently returns an array of all Timestreams. Realistically you would only care about timestream_id and name (the friendly name)

timestream_id18 nameadadda head_id21 metadata_id26 starttime2012-08-19 14:50:41 endtime2012-08-19 15:12:18 timestream_id17 nametestimg head_id20 metadata_id28 starttime2012-08-28 16:11:52 endtime2012-08-28 16:12:09

• ask for the metadata that describes the datasource currently feeding the Timestream

Method name: timestreams.ext_get_timestream_metadata Arguments: username, password, timestream id

timestreams.ext_get_timestream_metadata USERNAME PASSWORD 17

curl --noproxy localhost -d "timestreams.ext_get_timestream_metadataUSERNAMEPASSWORD17" http://localhost/relatedev/xmlrpc.php

returns metadata about the datasource - max value, min value, information about the sensor, units etc

metadata_id28 tablenamewp_5_5_ts_Image_89 measurement_typeImage first_record min_value0 max_value100 unitimage/png unit_symbolPNG device_details5909E86B-DF41-54E6-AD21-FD767045AB33 other_infoTesting data_typeVARCHAR(200)

• ask the server for an initial data set (the last 30 readings, for example)

Method name: timestreams.ext_get_timestream_metadata Arguments: username, password, timestream id, time last asked, maximum number of readings to return

Note how the initial time last asked argument is 0, indicating we want the latest 30 readings initially.

timestreams.ext_get_timestream_data USERNAME PASSWORD 17 0 30

curl --noproxy localhost -d "timestreams.ext_get_timestream_dataUSERNAMEPASSWORD17134692471810" http://localhost/relatedev/xmlrpc.php

Returns an array of readings. "valid_time" is the time that this reading actually happened, so is the one to display if necessary. "value" is the actual reading - temperature reading, URL of an image etc

id14 valuehttp://robin.timestreams.wp.horizon.ac.uk/files/2012/08/wp_5_5_ts_Image_89_img13.png valid_time2012-08-28 16:11:23 transaction_time2012-08-28 16:12:31 id15 valuehttp://robin.timestreams.wp.horizon.ac.uk/files/2012/08/wp_5_5_ts_Image_89_img14.png valid_time2012-08-28 16:11:23 transaction_time2012-08-28 16:12:43 id12 valuehttp://robin.timestreams.wp.horizon.ac.uk/files/2012/08/wp_5_5_ts_Image_89_img11.png valid_time2012-08-28 16:11:12 transaction_time2012-08-28 16:12:11 id13 valuehttp://robin.timestreams.wp.horizon.ac.uk/files/2012/08/wp_5_5_ts_Image_89_img12.png valid_time2012-08-28 16:11:12 transaction_time2012-08-28 16:12:23

Subsequently repeat this call, but now include the time we last asked, which we should have remembered from the previous call. Timestamp is a unix timestamp in seconds, as below.

timestreams.ext_get_timestream_data USERNAME PASSWORD 17 1346924718 30