Read Historical Data
-
Retrieves historical data, quality and timestamp of one or more items.
-
Required security permission - READ.
-
HTTP methods supported: GET, POST.
Description
This endpoint allows to read processed or raw historical data of one or more items. The endpoint utilises the Lua API gethistory function when the request is sent to the Core.
Parameters
Name | Type | Optional | Description |
---|---|---|---|
start_time |
string |
no |
The start time (UTC) of the interval to retrieve data for. |
end_time |
string |
no |
The end time (UTC) of the interval to retrieve data for. |
identifier |
string |
no |
Item or property path. |
aggregate |
string |
yes |
The aggregate type as string code; optional parameter, by default "AGG_TYPE_INTERPOLATIVE". See Aggregates Coding Group for available codings. |
intervals_no |
number |
yes |
The number of intervals in the [start, end] timespan; optional parameter, by default 100. Note: The end time value itself is not included in the timespan. |
percentage_good |
number |
yes |
A number representing the percentage of values to be returned that have quality "good"; optional parameter, by default 100. |
percentage_bad |
string |
yes |
A number representing the percentage of values to be returned that have quality "bad"; optional parameter, by default 100. |
treat_uncertain_as_bad |
string |
yes |
Indicates how the server treats data returned with a StatusCode severity 'Uncertain', with respect to Aggregate calculation; optional parameter, by default false. |
sloped_extrapolation |
boolean |
yes |
Indicates how the server interpolates data when no boundary value exists (i.e. extrapolating into the future from the last known value); optional parameter, by default false. |
partial_interval_treatment |
string |
yes |
Optional, by default 'UASTANDARD'. |
raw_as_item_values |
boolean |
yes |
Indicates raw historical data points should be returned as a flat list of ItemValues; Optional, by default 'false'. |
processed_as_item_values |
boolean |
yes |
Indicates processed historical data points should be returned as a flat list of ItemValues. By default true. Can be used to force the Web API to return three arrays (V,Q,T) per interval. |
insights |
boolean |
yes |
Indicates application insights should be included in the response, by default false. |
Read raw historical data request
Read historical data endpoint can be used for raw historical data requests by setting aggregate type to "AGG_TYPE_RAW" and the number of intervals to 1, the default read historical data response structure is to return values as a flat list of ItemValues. In order to change the default response structure set the parameter raw_as_item_values to true.
Examples
Simple Read Historical Data example
This example shows how to retrieve the historical data of a single or multiple objects.
HTTP GET
Request URL
-
/api/v2/readhistoricaldata?start_time=2019-03-20T08:06:33.599Z&end_time=2019-03-20T08:07:33.599Z&identifier=/System/Core/Examples/Demo Data/Process Data/DC4711&intervals_no=2
Response body
{
"data": {
"end_time": "2019-03-20T08:07:33.599Z",
"items": [
{
"aggregate": "AGG_TYPE_INTERPOLATIVE",
"intervals": [
{
"Q": 34359738368,
"T": 1553069193599,
"V": 10
},
{
"Q": 17179869184,
"T": 1553069223599,
"V": 2.8862976074218689
}
],
"p": "/System/Core/Examples/Demo Data/Process Data/DC4711"
}
],
"start_time": "2019-03-20T08:06:33.599Z"
}
}
HTTP POST
Request body
{
"start_time": "2019-03-20T08:06:33.599Z",
"end_time": "2019-03-20T08:07:33.599Z",
"intervals_no": 2,
"items": [
{
"p": "/System/Core/Examples/Demo Data/Process Data/DC4711",
"aggregate": "AGG_TYPE_INTERPOLATIVE"
}
]
}
Response body
{
"data": {
"end_time": "2019-03-20T08:07:33.599Z",
"items": [
{
"aggregate": "AGG_TYPE_INTERPOLATIVE",
"intervals": [
{
"Q": 34359738368,
"T": 1553069193599,
"V": 10
},
{
"Q": 17179869184,
"T": 1553069223599,
"V": 2.8862976074218689
}
],
"p": "/System/Core/Examples/Demo Data/Process Data/DC4711"
}
],
"start_time": "2019-03-20T08:06:33.599Z"
}
}
Read historical data with aggregate type set to RAW
This example shows the read raw historical data execution with read historical data endpoint. Aggregate type is set to "AGG_TYPE_RAW" and the number of intervals to 1, the default read historical data response structure is to return values as a flat list of ItemValues.
HTTP GET
Request URL
-
/api/v2/readhistoricaldata?start_time=2019-03-20T08%3A06%3A33.599Z&end_time=2019-03-20T08%3A07%3A33.599Z&identifier=%2FSystem%2FCore%2FExamples%2FDemo%20Data%2FProcess%20Data%2FDC4711&aggregate=AGG_TYPE_RAW&intervals_no=1
Response body
{
"data": {
"end_time": "2019-03-20T08:07:33.599Z",
"items": [
{
"aggregate": "AGG_TYPE_RAW",
"intervals": [
{
"Q": [
0,
0,
0
],
"T": [
1553069193599,
1553069221776,
1553069251776
],
"V": [
10,
2.8862976074218689,
2.7107971191406188
]
}
],
"p": "/System/Core/Examples/Demo Data/Process Data/DC4711"
}
],
"start_time": "2019-03-20T08:06:33.599Z"
}
}
Read raw historical data 'v, q, t'
In this example read raw historical data response is structured as 'v, q, t' data arrays. Aggregate type is set to "AGG_TYPE_RAW", the number of intervals to 1 and raw_as_item_values set to true.
HTTP GET
Request URL
-
/api/v2/readhistoricaldata?start_time=2019-03-20T08%3A06%3A33.599Z&end_time=2019-03-20T08%3A07%3A33.599Z&identifier=%2FSystem%2FCore%2FExamples%2FDemo%20Data%2FProcess%20Data%2FDC4711&aggregate=AGG_TYPE_RAW&intervals_no=1&raw_as_item_values=true
Response body
{
"data": {
"end_time": "2019-03-20T08:07:33.599Z",
"items": [
{
"aggregate": "AGG_TYPE_RAW",
"intervals": [
{
"Q": 0,
"T": 1553069193599,
"V": 10
},
{
"Q": 0,
"T": 1553069221776,
"V": 2.8862976074218689
},
{
"Q": 0,
"T": 1553069251776,
"V": 2.7107971191406188
}
],
"p": "/System/Core/Examples/Demo Data/Process Data/DC4711"
}
],
"start_time": "2019-03-20T08:06:33.599Z"
}
}