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 URL

  • /api/v2/readhistoricaldata

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"
    }
}