Please ensure Javascript is enabled for purposes of website accessibility
Powered by Zoomin Software. For more details please contactZoomin

AVEVA™ Historian

TABLE OF CONTENTS

Data retrieval

Save PDF
Save selected topicSave selected topic and subtopicsSave all topics
Share
Share to emailCopy topic URL
  • Last UpdatedMar 19, 2025
  • 4 minute read

The Historian Data REST API allows you to retrieve data from your Insight solution.

Retrieval requests use a GET method and a retrieval endpoint URL. The retrieval endpoint URL differs depending on whether you are using token authentication (with a retrieval token) or basic authentication, with no token.

  • GET method with basic authentication
    Requests to retrieve data via basic authentication require no retrieval token. Rather, these requests must use the endpoint URL specified by the Integration Settings page. Get details here.

  • GET method with token authentication
    You can use retrieval token to access your Insight data using token authentication. Get details here.

Insight solution retrieval requests flowchart.

Forming retrieval requests

  • With basic authentication, use this syntax to form your retrieval requests:

    https://online.wonderware.[DOMAINSUFFIX]/s/<solution_ID>/apis/historian/<api_version>/<resource>?<query_parameters>

  • With token authentication, use syntax to form your retrieval requests:

    https://online.wonderware.[DOMAINSUFFIX]/apis/historian/<api_version>/<resource>?<query_parameters>

    For more information, see Retrieval endpoints and tokens.

This URL includes these parts:

Syntax element

Explanation

https://online.wonderware.[DOMAINSUFFIX]/

The base URL

s/<solution_ID>

The unique identifier for your Insight solution.

This is not used if you use token authentication with a solution-specific retrieval token.

apis/historian/<api_version>

The API and version

<resource>

The Historian Data REST API retrieval resource. See the complete list.

?<query_parameters>

Query parameters.

These may be OData parameters using OData syntax tokens and operators; for example "$filter" as in this syntax:

https://online.wonderware.com/apis/historian/v2/
AnalogSummary?$filter=FQN+eq+'Baytown.tank_level'

Or, REST parameters; for example "TagFilter", as in this syntax:

https://online.wonderware.com/apis/historian/v2/
AnalogSummary?TagFilter=FQN eq 'Baytown.tank_level’

Note that TagFilter is used only with AnalogSummary, ProcessValues, and StateSummary.

For example, this retrieval request gets analog summary data via an endpoint URL using basic authentication:

https://online.wonderware.[DOMAINSUFFIX]/s/ik97r5/apis/historian/v2/AnalogSummary
?$filter=FQN+eq+'Depot.Train09'+and+StartDateTime+ge+2017-06-09T09:00:00-07:00+and
+EndDateTime+ge+2017-06-09T10:00:00-07:00&Resolution=3600000

Two powerful parameters: RetrievalMode and Resolution

You can use the RetrievalMode and Resolution parameters in retrieval queries to better control of your search results.

  • RetrievalMode specifies how the resulting data is calculated for Raw and ProcessValues entities. Valid values are:

    • Average

    • Cyclic

    • Integral

    • Minimum

    • BestFit

    • Delta

    • Interpolated

    • Slope

    • Counter

    • Full

    • Maximum

  • Resolution specifies the granularity of data returned for Raw, ProcessValues, and Summary entities.

Using TagFilter

You can use the TagFilter parameter as a part of a GET or POST query with ProcessValues, AnalogSummary, and StateSummary resources. See examples.

It allows a query string using OData filter query notation.

TagFilter can include:

  • Up to 20 AND clauses

  • Up to 20 OR clauses

  • Up to 2 UDF clauses

You cannot mix AND and OR in the same query.

Operators should be lowercase.

  • Valid Format:

    Historian/v2/ProcessValues?TagFilter=startswith(Source,'MVDS') and TagType eq 'string'

  • Invalid Format:

    Historian/v2/ProcessValues?TagFilter=startswith(Source,'MVDS') And TagType eq 'string'

Most searches are case-insensitive. However, search by these attributes is case-sensitive:

  • InterpolationType

  • MessageOn

  • MessageOff

These are the supported (and not supported) features for TagFilter:

Supported

Not Supported

  • V2 controllers

  • Use with ProcessValues, AnalogSummary and StateSummary

  • GET and POST queries

  • StartsWith, EndsWith

  • SkipToken

  • Nested query with same operator type ("and" or "or"). Examples:

    Historian/v2/ProcessValues?
    TagFilter=
    startswith(Source,'MVDS') and TagType
    eq 'string' and EngUnit eq ‘None’

    Historian/v2/ProcessValues?
    TagFilter=
    startswith(Source,'MVDS') or TagType
    eq 'string' or EngUnit eq ‘None’

  • V1 controller

  • Toupper and tolower functions

  • Nested query with grouping precedence operator; that is: ‘()’

  • Query with mixed operator like "and, or"

  • These attributes support only "eq" and not "startswith or endswith"

    • EngUnitMax

    • EngUnitMin

    • InterpolationType

    • MessageOff

    • MessageOn

    • Any TagExtendedProperty that is not a string (booleans, integers, doubles, guids)

  • Geospatial primitives, such as Geolocation, Geography, Geometry are not fully supported by TagFilter .

Supported syntax tokens and operators

These tokens are supported for system query via the Historian Data REST API. They are all case-sensitive.

Token

Description

$filter

Specifies an expression or function that must evaluate to true for a record to be returned in the collection.

All typical OData functions are supported for the $filter clause.

The $filter expression supports references to properties and literals. Literal values include:

  • Strings enclosed in single quotes

  • Numbers and Boolean values (true or false)

    Filtering for process value and summary data is case-sensitive.

    However, while event property names are case-sensitive, filtering is case-insensitive. For example, if you filter property values based on a value of "true," values such as "TRUE," "True," and "true" could be returned. The case returned in the query results reflects the case of the stored value.

$select

Specifies a subset of properties to return.

$skip

Specifies the number of records to skip from the beginning of the result set.

$skiptoken

Used to get the next record set that satisfies the query conditions. You do not need to include this token in the query, but you will see it upon query execution.

$top

Specifies the maximum number of records to return. This subset is formed by selecting only the first N items of the set, where N is a positive integer specified by this query option.

These logical operators are supported for the query options:

Operator

Description

eq

Equal

ne

Not equal

gt

Greater than

ge

Greater than or equal

lt

Less than

le

Less than or equal

and

Logical and

or

Logical or

not

Logical negation

In the filter expression, you can have only a single time clause combined with a single filter clause using the "and" operator. The filter clause itself can be complex, using any of the supported logical operators. Use parentheses ( ) to create precedence groups within an expression in filter clause.

Note: Use "%20" to indicate a space. Use "%27" to indicate a single quote.
If you are using the JSONView viewer in the Chrome browser, you can use a plus sign (+) to indicate a space to make the URI string more readable.

If the expression includes multiple values for the criteria, you must specify each criteria separately using the "or" operator. For example:

...
((Priority+eq+100+or+Priority+eq+200+or+Priority+eq+500+or+Priority+eq+700)+and+(filter …))

In This Topic
TitleResults for “How to create a CRG?”Also Available in