Skip to content

Visualisation API

Jump to bottom
pszjmb1 edited this page Sep 27, 2012 · 12 revisions 
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

<?xml version=\"1.0\" encoding=\"iso-8859-1\"?>
<methodCall>
<methodName>timestreams.ext_get_time</methodName>
<params>
<param><value><string>USERNAME</string></value></param>
<param><value><string>PASSWORD</string></value></param>
</params>
</methodCall>

curl --noproxy localhost -d "<?xml version=\"1.0\" encoding=\"iso-8859-1\"?><methodCall><methodName>timestreams.ext_get_time</methodName><params><param><value><string>USERNAME</string></value></param><param><value><string>PASSWORD</string></value></param></params></methodCall>" 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.

<?xml version="1.0"?>
<methodResponse>
  <params>
    <param>
      <value>
      <int>1346924718</int>
      </value>
    </param>
  </params>
</methodResponse>

- get a list of Timestreams.

Method name: timestreams.ext_get_timestreams
Arguments: username, password

<?xml version=\"1.0\" encoding=\"iso-8859-1\"?>
<methodCall>
<methodName>timestreams.ext_get_timestreams</methodName>
<params>
<param><value><string>USERNAME</string></value></param>
<param><value><string>PASSWORD</string></value></param>
</params>
</methodCall>

curl --noproxy localhost -d "<?xml version=\"1.0\" encoding=\"iso-8859-1\"?><methodCall><methodName>timestreams.ext_get_timestreams</methodName><params><param><value><string>USERNAME</string></value></param><param><value><string>PASSWORD</string></value></param></params></methodCall>" 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)

<?xml version="1.0"?>
<methodResponse>
  <params>
    <param>
      <value>
      <array><data>
  <value><struct>
  <member><name>timestream_id</name><value><string>18</string></value></member>
  <member><name>name</name><value><string>adadda</string></value></member>
  <member><name>head_id</name><value><string>21</string></value></member>
  <member><name>metadata_id</name><value><string>26</string></value></member>
  <member><name>starttime</name><value><string>2012-08-19 14:50:41</string></value></member>
  <member><name>endtime</name><value><string>2012-08-19 15:12:18</string></value></member>
</struct></value>
  <value><struct>
  <member><name>timestream_id</name><value><string>17</string></value></member>
  <member><name>name</name><value><string>testimg</string></value></member>
  <member><name>head_id</name><value><string>20</string></value></member>
  <member><name>metadata_id</name><value><string>28</string></value></member>
  <member><name>starttime</name><value><string>2012-08-28 16:11:52</string></value></member>
  <member><name>endtime</name><value><string>2012-08-28 16:12:09</string></value></member>
</struct></value>
</data></array>
      </value>
    </param>
  </params>
</methodResponse>

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

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

<?xml version=\"1.0\" encoding=\"iso-8859-1\"?>
<methodCall>
<methodName>timestreams.ext_get_timestream_metadata</methodName>
<params>
<param><value><string>USERNAME</string></value></param>
<param><value><string>PASSWORD</string></value></param>
<param><value><string>17</string></value></param>
</params>
</methodCall>

curl --noproxy localhost -d "<?xml version=\"1.0\" encoding=\"iso-8859-1\"?><methodCall><methodName>timestreams.ext_get_timestream_metadata</methodName><params><param><value><string>USERNAME</string></value></param><param><value><string>PASSWORD</string></value></param><param><value><string>17</string></value></param></params></methodCall>" http://localhost/relatedev/xmlrpc.php

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

<?xml version="1.0"?>
<methodResponse>
  <params>
    <param>
      <value>
      <struct>
  <member><name>metadata_id</name><value><string>28</string></value></member>
  <member><name>tablename</name><value><string>wp_5_5_ts_Image_89</string></value></member>
  <member><name>measurement_type</name><value><string>Image</string></value></member>
  <member><name>first_record</name><value><string></string></value></member>
  <member><name>min_value</name><value><string>0</string></value></member>
  <member><name>max_value</name><value><string>100</string></value></member>
  <member><name>unit</name><value><string>image/png</string></value></member>
  <member><name>unit_symbol</name><value><string>PNG</string></value></member>
  <member><name>device_details</name><value><string>5909E86B-DF41-54E6-AD21-FD767045AB33</string></value></member>
  <member><name>other_info</name><value><string>Testing</string></value></member>
  <member><name>data_type</name><value><string>VARCHAR(200)</string></value></member>
</struct>
      </value>
    </param>
  </params>
</methodResponse>

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

Method name: timestreams.ext_get_timestream_data
Arguments: username, password, timestream id, time last asked, maximum number of readings to return, ordper [ASC | DESC] (optional)

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

<?xml version=\"1.0\" encoding=\"iso-8859-1\"?>
<methodCall>
<methodName>timestreams.ext_get_timestream_data</methodName>
<params>
<param><value><string>USERNAME</string></value></param>
<param><value><string>PASSWORD</string></value></param>
<param><value><string>17</string></value></param>
<param><value><string>0</string></value></param>
<param><value><string>30</string></value></param>
</params>
</methodCall>

curl --noproxy localhost -d "<?xml version=\"1.0\" encoding=\"iso-8859-1\"?><methodCall><methodName>timestreams.ext_get_timestream_data</methodName><params><param><value><string>USERNAME</string></value></param><param><value><string>PASSWORD</string></value></param><param><value><string>17</string></value></param><param><value><string>1346924718</string></value></param><param><value><string>10</string></value></param></params></methodCall>" 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

<?xml version="1.0"?><methodResponse>
  <params>
    <param>
      <value>
      <array><data>
  <value><struct>
  <member><name>id</name><value><string>14</string></value></member>
  <member><name>value</name><value><string>http://robin.timestreams.wp.horizon.ac.uk/files/2012/08/wp_5_5_ts_Image_89_img13.png</string></value></member>
  <member><name>valid_time</name><value><string>2012-08-28 16:11:23</string></value></member>
  <member><name>transaction_time</name><value><string>2012-08-28 16:12:31</string></value></member>
</struct></value>
  <value><struct>
  <member><name>id</name><value><string>15</string></value></member>
  <member><name>value</name><value><string>http://robin.timestreams.wp.horizon.ac.uk/files/2012/08/wp_5_5_ts_Image_89_img14.png</string></value></member>
  <member><name>valid_time</name><value><string>2012-08-28 16:11:23</string></value></member>
  <member><name>transaction_time</name><value><string>2012-08-28 16:12:43</string></value></member>
</struct></value>
  <value><struct>
  <member><name>id</name><value><string>12</string></value></member>
  <member><name>value</name><value><string>http://robin.timestreams.wp.horizon.ac.uk/files/2012/08/wp_5_5_ts_Image_89_img11.png</string></value></member>
  <member><name>valid_time</name><value><string>2012-08-28 16:11:12</string></value></member>
  <member><name>transaction_time</name><value><string>2012-08-28 16:12:11</string></value></member>
</struct></value>
  <value><struct>
  <member><name>id</name><value><string>13</string></value></member>
  <member><name>value</name><value><string>http://robin.timestreams.wp.horizon.ac.uk/files/2012/08/wp_5_5_ts_Image_89_img12.png</string></value></member>
  <member><name>valid_time</name><value><string>2012-08-28 16:11:12</string></value></member>
  <member><name>transaction_time</name><value><string>2012-08-28 16:12:23</string></value></member>
</struct></value>
</data></array>
      </value>
    </param>
  </params>

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.

<?xml version=\"1.0\" encoding=\"iso-8859-1\"?>
<methodCall>
<methodName>timestreams.ext_get_timestream_data</methodName>
<params>
<param><value><string>USERNAME</string></value></param>
<param><value><string>PASSWORD</string></value></param>
<param><value><string>17</string></value></param>
<param><value><string>1346924718</string></value></param>
<param><value><string>30</string></value></param>
</params>
</methodCall>

If nothing has happened since you last asked, the returned array will be empty, if something has happened you will get an array of readings as before.
Clone this wiki locally