Data Retrieval
- Last UpdatedDec 13, 2023
- 3 minute read
The Historian Data REST API allows you to retrieve data from your solution. Data retrieval with the Historian Data REST API is available through both Historian Client Web and Historian Client Web, so ensure that you refer to the correct syntax for your product from the examples below.
Forming retrieval requests
Use the following syntax for retrieval requests, depending on whether you are using HTTP or HTTPS:
http://<servername>:32569/Historian/<api_version>/<resource>?<query>
https://<servername>:32573/Historian/<api_version>/<resource>?<query>
Note: 32569 and 32573 are the default ports for HTTP and HTTPS. If your environment is configured to use different ports for either protocol, replace the ports used in this document with the appropriate ports for your environment.
The URL includes the following elements:
|
Syntax element |
Explanation |
|
<servername>:32569 or <servername>:32573 |
The servername and port number used by AVEVA Historian Client Web. If the server is the local computer, this could be "localhost:32569" for HTTP or "localhost:32573" for HTTPS. |
|
Historian/<api_version> |
The API version. For example, "v2". |
|
<resource> |
The Historian Data REST API retrieval resource. See the complete list. |
|
?<query> |
A query using OData parameters and operators |
For example, this retrieval request gets analog summary data via an endpoint URL using basic authentication:
http://localhost:32569/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
Supported OData parameters
These parameters are supported for system query via the Historian Data REST API. They are all case-sensitive.
|
Parameter |
Description |
|---|---|
|
$filter |
Specifies an expression or function that must evaluate to true for a record to be returned in the collection. A $filter expression supports references to properties and literals. Literal values include:
|
|
$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. This parameter cannot be used in queries, 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 parameter. |
Time-series extension parameters
The Historian Data REST API supports the following custom extension parameters in retrieval queries to better control 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.
-
TagFilter is used to specify which tags to return data on. TagFilter must be used with $filter, which defines the range of results. TagFilter only works with the ProcessValues call. TagFilter supports the following operators:
-
startswith
-
endswith
-
contains
-
Supported operators
These logical operators are supported for queries:
|
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 |
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 …))
Syntax for combining expressions
-
Use and to use multiple terms for the same parameter. For example:
$filter=DateTime+ge+2023-08-31T00:00:00z+and+DateTime+le+2023-08-31T12:00:00z
-
Use & to join separate parameters. For example:
$filter=DateTime+ge+2023-08-31T00:00:00z&TagFilter=startswith(FQN, 'turbine')
-
In a query, you can have only a single expression specifying a period of time combined with a single expression filtering specific tags. Combine expressions with the "and" operator. The expression itself can be complex, using any of the supported logical operators. Use parentheses ( ) to create precedence groups within an expression.