====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**.

===Alternatives===

Please note that each channel of data returned from this function may be at its own unique time resolution. Some data may have sub-second resolution while other points may only update once a minute, or not at all.

If you are looking for a complete, synchronised table of information for direct use in spreadsheets, reporting or AI, please consider using the [[analyst:aql_tabular_data|table]] function in the [[[[aql:welcome|ARDI query language]].

===Parameters===

^Name^Usage^
|start|The start time for the query. This is specified in YYYY-MM-DD HH:MM:SS and must be provided in **UTC**|
|end|The end time for the query. Formatted as above.|
|points|The comma-delimited list of [[data points|data points]] to read|
|format|The format of the returned data. See //Data Formats// below|
|function|The query function to use. See //Query Functions// below|
|grain|The resolution of the returned data. See //Grain// below|

===Data Formats===

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

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

**TDLE** - Tab Delimited with Unix Epoch

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

**XML** - XML-Formatted History

<code>
<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>
</code>

//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)

<code>
{ "records": [
  [ 13541652000000,0,25.44 ],
  [ 13541652000000,1,22.5 ] ]
}
</code>

===Query Functions===

=='interp' - Interpolated==

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**.

=='raw' - Raw Data==

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**.

=='changes' - Changes Only==

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===

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.

===Example Queries===

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**

===Getting Data Point Names At Runtime===

You can discover the data point names for an asset using the [[ardisdk:rest_language_agnostic_api|ARDI API]]. In particular, the [[ardisdk:api_asset_search]] and [[ardisdk:api_asset_info]] functions are quite useful.