Read Historical Data
-
Retrieves historical data, quality and timestamp of one or more items.
-
Required security permission - READ.
-
HTTP methods supported: GET, POST.
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". |
intervals_no |
number |
yes |
The number of intervals in the [start, end] timespan; optional parameter, by default 100. |
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'. |
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"
}
}