Historical Data API

The Historical Data API allows you to fetch historical information about ARDI assets.

Historical queries are performed using a HTTP GET or POST request on /api/gethistorybulk.

This function can provide data in a variety of formats depending on the application.

Note in all of these formats, there are three fields returned - the time stamp, the value and the point number. The point number is a zero-based index into the list of data points you provided.

For example, if you called the API function with points set to '201:29:measurement,255:29:measurement', values for the first point would have an point number of '0' and the second a point number of '1'.

TDL - Tab Delimited

2012-11-29 05:00:00<tab>0<tab>25.44
2012-11-29 05:00:00<tab>1<tab>22.5

TDLE - Tab Delimited with Unix Epoch

1354165200<tab>0<tab>25.44
1354165200<tab>1<tab>22.5

XML - XML-Formatted History

<recording>
   <sample time="2012-11-29 05:00:00" point="0" value="25.44"/>
   <sample time="2012-11-29 05:00:00" point="1" value="22.5"/>
</recording>

Note - this format is particularly poor for large volumes of data - we suggest using other formats if you are requesting more than a single channel of data

JSON - Javascript Object Notation Format

Note that timestamps are delivered as Javascript timestamps (UTC milliseconds)

{ "records": [
  [ 13541652000000,0,25.44 ],
  [ 13541652000000,1,22.5 ] ]
}

This is the default function used when you issue a query. If the underlying driver supports it, the results will be aggregated to give you summaries for time periods rather than delivering thousands of records. It works along-side the grain parameter.

Note that not all drivers support this, in which case the results will be similar to those from raw.

Every time ARDI asks for history, it needs to find the most recent values before the start of your time frame. This can actually be an expensive and difficult operation for some historians - SQL databases in particular.

For systems that play back history, the continue function skips that step - ideal for situations where you begin by calling 'interp' then wish to continue viewing data from that point onwards.

Note that not all drivers support this, in which case the results will be similar to those from interp.

This function delivers the raw data, without attempting to aggregate.

Note that not all drivers support this, in which case the results will be similar to those from interp.

This function only returns records for when a data point changes. This is particularly useful when dealing with digital values, as there may be hundreds or even thousands of recorded times where no change has occurred.

All drivers support this function.

Grain is used in most calls when you are using the 'interp' function. The grain specifies how large a sampling window you wish to use.

Grain is specified in seconds.

For example, if you were recording samples every second and you wanted the history from yesterday, a raw query would result in 86,400 samples per channel. This data is too detailed for most applications.

However, if you used a grain of '60', you'd break up those samples into minutes rather than seconds. You would get 1,400 samples. If you wanted hours, a grain of 3600 would give you 24 different recorded values.

You can also use a negative number for grain. Instead of interpreting the number as the size of the window, it is instead interpreted as the number of required samples.

So for example, a grain of -100 would say that “I would like 100 samples per channel in my resulting data” - in which case, your results would have one line every 14.4 minutes.

To get a tab delimited file showing the average temperature of the room (asset #273, property #18) in 10-minute intervals for the first day of 2016, try….

/api/gethistorybulk?start=2016-01-01 00:00:00&end=2016-01-02 00:00:00&points=273:18:measurement&function=interp&grain=600&format=tdl

You can discover the data point names for an asset using the ARDI API. In particular, the /api/asset/search and /api/asset/info functions are quite useful.