Managing Tags

The Tags API
The Tags API retrieves the qualified tag name list by a given nameMask.
Note: URI format supports asterisks (*) and question marks (?).
METHOD GET
URI https://<historianservername>:8443/historian-rest-api/v1/tags/{nameMask}/{maxNumber}
SAMPLE URI https://<historianservername>:8443/historian-rest-api/v1/tags?nameMask=*&maxNumber=100
SAMPLE cURL COMMAND curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” https://<nodename>:8443/ historian-rest-api/v1/tags?nameMask=*&maxNumber=<Number_Of_Tags>
Table 1. Query Parameters
Parameter Description Required? Values
nameMask Tagmask that searches for all tags that match the mask and applies the remaining criteria to retrieve data. The mask can include wildcards, such as asterisks (*). Optional String
maxNumber Maximum tag number provides the limit while returning the results (0 by default). This means that for a query, if using 0, all tags are returned.

If a negative number is used, then 0 is used for the maxNumber.

If a positive number is used, then that number of tags is returned. In addition, an error number of +14 notifies the user that there are more than the requested number of tags in the system.

 Optional Integer

0 by default
Table 2. Response Parameters
Parameter Data Type Required? Description
ErrorCode Number Yes For example, ErrorCode = 0, which means the operation was successful.
ErrorMessage String Yes For example, NULL.
tags String Yes Includes the following:
  • ALT_SENSOR
  • tagName1
  • tagName2
The Tagslist API

The Tags List API GET method retrieves the list of tags.

When retrieving large tag lists from Historian, you can paginate the response, allowing you to get the next page, go the end, go back one page, and go to the beginning.

Request Parameters

You can use wildcards (*, &,?) with string parameters for pattern matching. Results are sorted in ascending tag names. All parameters use the AND operator. The OR operator is not supported.

All request parameters are optional.

When there are NO wildcard characters (*, &,?) with string parameters for pattern matching, then search would be a contains search

Example: “dog” pattern will match “dog1”, “dog2”,”dogs”, “dogx”, “dog12”, “dogs are faithful”, “1dog1” and so on. When wildcards (*,&, ?) are used in the search string parameters for pattern matching, then they work as per the wildcard character definition.

? - Single character matching

* - Multi character matching

Eg1: “dog?” pattern will match: “dog1”, “dog2”,”dogs”, “dogx” and so on but not “dog12” or “dogs are faithful”

Eg2: “dog*” pattern will match “dog1”, “dog2”,”dogs”, “dogx”, “dog12”, “dogs are faithful” and so on but not “1dog1”

Parameter Name Data Type Default Description
calctype Integer -1 Returns exact match of calc type (0,1,2).
collectiondisabled Boolean If ignored, all types considered. Must be only true / false, else error out.
collectioninterval Integer 0 – means all intervals If collectorinterval = 0 consider all intervals, else exact match.
collectorcompression Boolean * Returns exact match of collector compression (true/false).
collectorname String * Default * means consider all.
collectortype Integer 0 – means consider all collector types Returns exact match of collector type.
comment String * Default * means consider all.
data storename String * Default * means consider all.
datatype Integer 0 – means consider all data types Returns exact match of data type.
description String * Default * means consider all.
egudescription String * Default * means consider all.
enumeratedset String * Default * means consider all.
hasalias Boolean If ignored, all types considered. Must be only true / false, else error out.
isstale Boolean If ignored, all types considered. Must be only true / false, else error out.
lastmodified String 1970-01-01T00:00:00.000Z >= is applied so that last modified tag is returned in the result set.
lastmodifieduser String * Default * means consider all.
numberofelements Integer 0 If 0, ignore this parameter else returns exact match of number of elements.
pageno Integer 1

Must be > 1

 If invalid, no data is returned.
pagesize Integer 128

Max 512

Min 2

 If out of range, returns error.
sourceaddress String * Default * means consider all.
tagname String * Default * means consider all.
userdefinedtypename String * Default * means consider all.

The Tags List Pagination Parameters

When retrieving large tag lists from Historian, you can paginate the response, allowing you to get the next page, go the end, and go back on page and to the beginning. Results with no errors return these pagination parameters:
Parameter Value
pagesize Current page size.
pageno Current page number
totalcount Total result other than current page.
Links to URLs All URLs are part of the HTTP response headers.
  • first – First page tags list URL (can be null if count is 0).
  • last - Last page tags list URL (can be null if count is 0).
  • prev – Previous page tags list URL (can be null if current page is 1).
  • Next - Next page tags list URL (can be null if current page is last page).
Table 3. Sample cURL commands
METHOD GET
SAMPLE cURL COMMAND: [lastmodified] curl -i -H "Accept: application/json" -H "Authorization:Bearer <TOKEN>” http://<nodename>:8443/historian-rest-api/v1/tagslist?lastmodified=2017-05-01T00:00:00.00Z
SAMPLE cURL COMMAND: [pageno=0] curl -i -H "Accept: application/json" -H "Authorization:Bearer <TOKEN>” http://<nodename>:8443/historian-rest-api/v1/tagslist?pageno=0
SAMPLE cURL COMMAND: [pageno=1] curl -i -H "Accept: application/json" -H "Authorization:Bearer <TOKEN>” http://<nodename>:8443/historian-rest-api/v1/tagslist?pageno=1
SAMPLE cURL COMMAND: [complete tagslist] curl -i -H "Accept: application/json" -H "Authorization:Bearer <TOKEN>” http://<nodename>:8443/historian-rest-api/v1/tagslist

Example Queries

The following request returns first page as pageno is ignored and pagesize is defaulted to 128, all tags are considered:
<baseurl>/v1/tagslist
The following request returns first page as pageno is ignored and pagesize is defaulted to 128, all tags are considered that are modified after 2017-05-01T00:00:00.00Z.
<baseurl>/v1/tagslist?lastmodified=2017-05-01T00:00:00.00Z

Example Results

The following info is returned for each tag from the criteria provided in the request as an array of tag info.
  • tagid - String
  • tagname - String
  • description - String
  • datatype - Integer
  • collectorname - String
  • collectortype - Integer
  • data storename - String
  • egudescription - String
  • comment - String
  • sourceaddress - String
  • sourceaddress - String
  • collectioninterval - Integer
  • collectorcompression - Boolean
  • lastmodifieduser - String
  • enumeratedset - String
  • userdefinedtypename - String
  • calctype - Integer
  • isstale - Boolean
  • lastmodified - Long
  • lastmodified - Long
  • lastmodifiedString – String – In readable format
  • has alias - Boolean
  • numberofelements - Integer
  • collectiondisabled - Boolean
Example:
{
	"TotalCount": 1031,
	"Page": 1,
	"PageSize": 4,
	"Tags": [
		{
			"Tagid": "adb70ebf-978f-46dd-ac6f-5e863cdb0739",
			"Tagname": "-anilgwxb.Constant",
			"Description": "anilgwxb.Constant",
			"DataType": 3,
			"CollectorName": "ANILGWXB_Simulation",			
			"CollectorType": 2,
			"DataStoreName": "User",
			"EngineeringUnits": "",
			"Comment": "",
			"SourceAddress": "$Constant",
			"CollectionInterval": 1000,
			"CollectorCompression": false,
			"LastModifiedUser": null,
			"EnumeratedSetName": "",
			"UserDefinedTypeName": "",
			"CalcType": 0,
			"IsStale": false,
			"HasAlias": false,
			"NumberOfElements": 0,
			"CollectionDisabled": false,
			"LastModified": 1496992712,
			"LastModifiedString": "2017-06-09T07:18:32Z"
		},
		{
			"Tagid": "88e1f448-643f-465a-95c2-d2bd08870547",
			"Tagname": "anilgwxb.Constant_1%Noise",
			"Description": "anilgwxb.Constant_1%Noise",
			"DataType": 3,
			"CollectorName": "ANILGWXB_Simulation",
			"CollectorType": 2,
			"DataStoreName": "User",
			"EngineeringUnits": "",
			"Comment": "",
			"SourceAddress": "$Constant_1%Noise",
			"CollectionInterval": 1000,
			"CollectorCompression": false,
			"LastModifiedUser": null,
			"EnumeratedSetName": "",
			"UserDefinedTypeName": "",
			"CalcType": 0,
			"IsStale": false,
			"HasAlias": false,
			"NumberOfElements": 0,
			"CollectionDisabled": false,
			"LastModified": 1496992712,
			"LastModifiedString": "2017-06-09T07:18:32Z"
			},
<SNIP>
	],
	"Links": {
		"first": "https://anilgwxb:8443/historian-rest-api/v1/tagslist?pageno=1&pagesize=4",
		"last": "https://anilgwxb:8443/historian-rest-api/v1/tagslist?pageno=258&pagesize=4",
		"prev": null,
		"next": "https://anilgwxb:8443/historian-rest-api/v1/tagslist?pageno=2&pagesize=4"
	}
}
The Raw Data API

The Raw Data API queries raw data, such as a number of samples or the time range for a list of tags. If the count is not zero, then the API service returns the number of raw samples taken beginning from the start time. If the count is zero, then the service returns the raw samples taken between the start time and the end time.

METHOD: GET, POST
URI:
GET
https://<historianservername>:8443/historian-rest-api/v1/datapoints/raw/{tagNames}/{start}/{end}/{direction}/{count}
POST
https://<historianservername>:8443/historian-rest-api/v1/datapoints/raw/{start}/{end}/{direction}/{count}
SAMPLE GET URI:

Raw By Number

Count value is a non-zero positive number, and end time is greater than start time.

https://<historianservername>:8443/historian-rest-api/datapoints/raw/tagName1/2013-10-02T11:30:00.111Z/2013-10-02T11:31:11.111Z/0/100https://<historianservername>:8443/historian-rest-api/datapoints/raw?tagNames=tagName1&start=2013-10-02T11:30:00.111Z&end=2013-10-02T11:31:11.111Z&count=100&direction=0

Raw By Time

The count value equals 0.

https://<historianservername>:8443/historian-rest-api/datapoints/raw/tagName1/2013-10-02T11:30:00.111Z/2013-10-02T11:31:11.111Z/0/0https://<historianservername>:8443/historian-rest-api/datapoints/raw?tagNames=tagName1&start=2013-10-02T11:30:00.111Z&end=2013-10-02T11:31:11.111Z&count=0&direction=0
SAMPLE POST URI:

Raw By Number

Count value is a non-zero positive number, and end time is greater than start time.

https://<historianservername>:8443/historian-rest-api/datapoints/raw/2013-10-02T11:30:00.111Z/2013-10-02T11:31:11.111Z/0/100https://<historianservername>:8443/historian-rest-api/datapoints/raw?start=2013-10-02T11:30:00.111Z&end=2013-10-02T11:31:11.111Z&count=100&direction=0

Raw By Time

The count value equals 0.

https://<historianservername>:8443/historian-rest-api/datapoints/raw/2013-10-02T11:30:00.111Z/2013-10-02T11:31:11.111Z/0/0https://<historianservername>:8443/historian-rest-api/datapoints/raw?start=2013-10-02T11:30:00.111Z&end=2013-10-02T11:31:11.111Z&count=0&direction=0
SAMPLE cURL COMMAND (GET): [Raw By Number] curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” http://<nodename>:8443/ historian-rest-api/v1/ datapoints/raw/<tagName>/<start time>/<end time>/<direction>/<count>
SAMPLE cURL COMMAND (GET): [Raw By Time] curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” http://<nodename>:8443/ historian-rest-api/v1/ datapoints/raw/<tagName>/<start time>/<end time>/<direction>/0
SAMPLE cURL COMMAND (POST): [Raw By Number] curl –X POST -i -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” -d “{\”tagNames\”:\”<tagName>;<tagName>\”}” http:// <nodename>/ historian-rest-api/v1/ datapoints/raw/ <start time>/<end time>/<direction>/<count>
SAMPLE cURL COMMAND (POST): [Raw By Time] curl –X POST -i -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” -d “{\”tagNames\”:\”<tagName>;<tagName>\”}” http:// <nodename>/ historian-rest-api/v1/ datapoints/raw? start=<start time>&end=<end time>&direction=<direction>&count=<count>
Table 4. Query Parameters
Parameter Description Required? Values
TagNames Queries the specified tag names. Yes String
Start Start time of the query, in ISO data format (such as YYYY-MM-DDTHH:mm:ss.SSSZ). Yes DateTime
End End time of the query, in ISO data format (such as YYYY-MM-DDTHH:mm:ss.SSSZ). Yes DateTime
Direction Specifies the direction (Forward or Backward from the starting time) of data sampling from the archive. The default value is Forward (1). Yes Integer, with a value such as 1.
Count Count of archive values within each calculation interval. Yes Integer, with a value such as 100.
Table 5. Response Parameters
Parameter Data Type Required? Description
ErrorCode Integer Yes For example, 0.
ErrorMessage String Yes For example, NULL.
Data String Yes The object container for the following parameters:
DataType
DoubleFloat, which stores decimal values up to 15 places.
ErrorCode
Value is 0, which means the operation was successful.
TagName
Example: TagName1.
Samples
Provides TimeStamp, Value and Quality for each sample. For example, TimeStamp = 2013-10-02T11:30:00.111Z, Value = 34.26155, and Quality = 3.
The Interpolated Data API

The Interpolated Data API queries interpolated values for a list of tags. If the start time equals the end time, the request returns one sample.

METHOD: GET, POST
URI:
GET
https://<historianservername>:8443/historian-rest-api/v1/datapoints/interpolated/{tagNames}/{start}/{end}/{count}/{intervalMs}
POST
https://<historianservername>:8443/historian-rest-api/v1/datapoints/interpolated/{start}/{end}/{count}/{intervalMs}
SAMPLE GET URI: https://<historianservername>:8443/historian-rest-api/v1/datapoints/interpolated/tagName1/2013-10-02T11:30:00.111111Z/2013-10-02T11:31:11.111Z/100/10000
SAMPLE POST URI: https://<historianservername>:8443/historian-rest-api/v1/datapoints/interpolated/2013-10-02T11:30:00.111111Z/2013-10-02T11:31:11.111Z/100/10000
SAMPLE cURL COMMAND (GET): curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” http://<nodename>:8443/ historian-rest-api/v1/ datapoints/interpolated/<tagName>/<start time>/<end time>/<count>/<intervalMS>
SAMPLE cURL COMMAND (POST): curl -i –X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” -d “{\”tagNames\”:\”<tagName>\”}” http://<nodename>:8443/ historian-rest-api/v1/ datapoints/interpolated/<start time>/<end time>/<count>/<intervalMS>
Table 6. Query Parameters
Parameter Description Required? Values
TagName Queries the tag names specified. Yes String
Start Start time of the query, in ISO data format (such as YYYY-MM-DDTHH:mm:ss.SSSZ). Yes DateTime
End End time of the query, in ISO data format (such as YYYY-MM-DDTHH:mm:ss.SSSZ). Yes DateTime
Count Count of archive values within each calculation interval. Yes Integer, with a value such as 100.
intervalMS Interval in milliseconds. Yes 64-bit signed integer, with a value such as 10000.
Table 7. Response Parameters
Parameter Data Type Required? Description
ErrorCode Integer Yes For example, 0.
ErrorMessage String Yes For example, NULL.
Data String Yes The object container for the following parameters:
DataType
DoubleFloat, which stores decimal values up to 15 places.
ErrorCode
Value is 0, which means the operation was successful.
TagName
Example is TagName1.
Samples
Provides TimeStamp, Value and Quality for each sample. For example, TimeStamp = 2013-10-02T11:30:00.111Z, Value = 34.26155, and Quality = 3.
The Current Value API

The Current Value API queries the current value data and reads the current values for a list of tags. If the start time is equal to end time, the request returns one sample.

METHOD: GET, POST
URI:
GET
https://<historianservername>:8443/historian-rest-api/v1/datapoints/raw/{tagNames}/{start}/{end}/{direction}/{count}
POST
https://<historianservername>:8443/historian-rest-api/v1/datapoints/currentvalue
SAMPLE GET URI: https://<historianservername>:8443/historian-rest-api/v1/datapoints/currentvalue?tagNames=tagName1
SAMPLE POST URI: https://<historianservername>:8443/historian-rest-api/v1/datapoints/currentvalue
SAMPLE cURL COMMAND (GET): curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” http://<nodename>:8443/ historian-rest-api/v1/ datapoints/currentvalue/<tagName>
SAMPLE cURL COMMAND (POST): curl -i –X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” -d “{\”tagNames\”:\”<tagName>\”}” http://<nodename>:8443/ historian-rest-api/v1/ datapoints/currentvalue
Table 8. Query Parameters
Parameter Description Required? Values
TagNames Queries the specified tag names. Yes String
Table 9. Response Parameters
Parameter Data Type Required? Description
ErrorCode Integer Yes For example, 0.
ErrorMessage String Yes For example, NULL.
Data String Yes The object container for the following parameters:
DataType
DoubleFloat, which stores decimal values up to 15 places.
ErrorCode
Value is 0, which means the operation was successful.
TagName
Example is TagName1.
Samples
Provides TimeStamp, Value and Quality for each sample. For example, TimeStamp = 2014-01-01T12:00:00Z, Value = 34.26155, and Quality = 3.
The Calculated Data API

The Calculated Data API queries the calculated data for a list of tags. Data can be requested using a number of samples or a time range for a list of tags. If the count is not zero, the service returns the number of raw samples beginning from the start time. If the count is zero, the services uses the interval, start time, and end time to calculate the required sample number.

METHOD: GET, POST
URI:
GET
https://<historianservername>:8443/historian-rest-api/v1/datapoints/calculated/{tagNames}/{start}/{end}/{calculationMode}/{count}/{intervalMs}
POST
https://<historianservername>:8443/historian-rest-api/v1/datapoints/calculated/{start}/{end}/{calculationMode}/{count}/{intervalMs}
SAMPLE GET URI:
Number of Samples
https://<historianservername>:8443/historian-rest-api/v1/datapoints/calculated/tagName1/2013-10-02T11:30:00.111Z/2013-10-02T11:31:11.111Z/1/100/1000
Time Range for List of Tags
https://<historianservername>:8443/historian-rest-api/v1/datapoints/calculated?tagNames=tagName1&start=2013-10-02T11:30:00.111Z&end=2013-10-02T11:31:11.111Z&count=100&calculationMode=1&intervalMs=1000
SAMPLE POST URI:
Number of Samples
https://<historianservername>:8443/historian-rest-api/v1/datapoints/calculated/2013-10-02T11:30:00.111Z/2013-10-02T11:31:11.111Z/1/100/1000
Time Range for List of Tags
https://<historianservername>:8443/historian-rest-api/v1/datapoints/calculated?start=2013-10-02T11:30:00.111Z&end=2013-10-02T11:31:11.111Z&count=100&calculationMode=1&intervalMs=1000
SAMPLE cURL COMMAND (GET): curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” http://<nodename>:8843/ historian-rest-api/v1/ datapoints/calculated/<tagName>/<start time>/<end time>/<count>/<calculation mode>/<intervalMS>
SAMPLE cURL COMMAND (POST): curl -i –X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” -d “{\”tagNames\”:\”<tagName>\”}” http://<nodename>:8843/ historian-rest-api/v1/ datapoints/calculated/<start time>/<end time>/<count>/<calculationmode>/<intervalMS>
Table 10. Query Parameters
Parameter Description Required? Values
TagNames GE identifier for a location. Yes 1000000106
Start Start time of the query, in ISO data format (such as YYYY-MM-DDTHH:mm:ss.SSSZ). Yes DateTime
End End time of the query, in ISO data format (such as YYYY-MM-DDTHH:mm:ss.SSSZ). Yes DateTime
Count Count of archive values within each calculation interval. Yes Integer, with a value such as 100.
Calculation Mode End time in milliseconds. Yes Integer, with a value such as 1.
IntervalMS Interval in milliseconds. 64-bit signed integer, with a value such as 1000.
Table 11. Response Parameters
Parameter Data Type Required? Description
ErrorCode Integer Yes For example, 0.
ErrorCode String Yes For example, NULL.
Data String Yes The object container for the following parameters:
DataType
DoubleFloat, which stores decimal values up to 15 places.
ErrorCode
Value is 0, which means the operation was successful.
TagName
Example is TagName1.
Samples
Provides TimeStamp, Value and Quality for each sample. For example, TimeStamp = 2013-10-02T11:30:00.111Z, Value = 34.26155, and Quality = 3.
The Sampled Data API
The Sampled Data API queries the sampled data for a list of tags. Data can be requested using a number of samples or a time range for a list of tags. If the count is not zero, the service returns the number of raw samples beginning from the start time. If the count is zero, the services uses the interval, start time, and end time to calculate the required sample number.
Note: For the query, you can also use optional parameters such as FilterMode and ReturnDataFields. Unused parameters can be omitted.
METHOD: GET, POST
URI:
GET
https://<historianservername>:8443/historian-rest-api/v1/datapoints/sampled
POST
https://<historianservername>:8443/historian-rest-api/v1/datapoints/sampled
SAMPLE GET URI: https://<historianservername>:8443/historian-rest-api/v1/datapoints/sampled?tagNames=tagName1&start=2013-10-02T11:30:00.111Z&end=2013-10-02T11:31:11.111Z&samplingMode=1&calculationMode=1&direction=0&count=0&intervalMs=1000
SAMPLE POST URI: https://<historianservername>:8443/historian-rest-api/v1/datapoints/sampled
SAMPLE cURL COMMAND (GET): curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” http://<nodename>:8443/ historian-rest-api/v1/ datapoints/sampled/<tagName>/<start time>/<end time>/<direction>/<count>/<intervalMS>
SAMPLE cURL COMMAND (POST): curl -i –X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” -d “{ \”tagNames\”:\”<tagName>\”, \”start\”: \”<start>\”, \”end\”: \”<end>\”, \”samplingMode\”: <samplingMode>, \”calculationMode\”: <calculationMode>, \”direction\”: <direction>, \”count\”: <count>, \”returnDataFields\”: <returnDataFields>, \”intervalMs\”: <intervalMs>, \”queryModifier\”: <queryModifier>, \”filterMode\”: <filterMode>, \”filterExpression\”: \”<filterExpression>\”}” http://<nodename>:8443/historian-rest-api/v1/datapoints/sampled
Table 12. Query Parameters
Parameter Description Required? Values
TagNames Queries the tag names specified. Yes String
Start Start time of the query, in ISO data format (such as YYYY-MM-DDTHH:mm:ss.SSSZ). Yes DateTime
End End time of the query, in ISO data format (such as YYYY-MM-DDTHH:mm:ss.SSSZ). Yes DateTime
SamplingMode Also known as SamplingModeType. Optional Integer, with a value such as 1.
CalculationMode Also known as CalculationModeType. Optional Integer, with a value such as 1.
Direction Specifies the direction (Forward or Backward from the starting time) of data sampling from the archive. The default value is Forward (1). Optional Integer, with a value such as 1.
Count The count of archive values within each calculation interval. Optional Integer, with a value such as 0.
IntervalMS Interval in milliseconds. Optional 64-bit signed integer, with a value such as 1000.
Table 13. Response Parameters
Parameter Data Type Required? Description
ErrorCode Integer Yes For example, 0.
ErrorCode String Yes For example, NULL.
Data String Yes The object container for the following parameters:
DataType
DoubleFloat, which stores decimal values up to 15 places.
ErrorCode
Value is 0, which means the operation was successful.
TagName
Example is TagName1.
Samples
Provides TimeStamp, Value and Quality for each sample. For example, TimeStamp = 2013-10-02T11:30:00.111Z, Value = 34.26155, and Quality = 3.
The Trend Data API
The Trend Data API queries the trend data for a list of tags.
Note: For the query, you can also use optional parameters such as FilterMode and StatisticsItemFilter. Unused parameters can be omitted.
METHOD: GET, POST
URI:
GET
https://<historianservername>:8443/historian-rest-api/v1/datapoints/trend
POST
https://<historianservername>:8443/historian-rest-api/v1/datapoints/trend
SAMPLE GET URI: 
https://<historianservername>:8443/historian-rest-api
/v1/datapoints/trend?tagNames=tagName1&start=2013-10-02T11:
30:00.111Z&end=2013-10-02T11:31:11.111Z&samplingMode=1&calculationMode=1
&direction=0&count=0&intervalMs=1000
SAMPLE POST URI: https://<historianservername>:8443/historian-rest-api/v1/datapoints/trend
SAMPLE cURL COMMAND (GET): curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” http://<nodename>:8443/ historian-rest-api/v1/ datapoints/trend/<tagName>/<start time>/<end time>/<samplingMode>/<calculationMode>/<direction>/<count>/<intervalMS>
SAMPLE cURL COMMAND (POST): curl -i –X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” -d “{ \”tagNames\”:\”<tagName>\”, \”start\”: \”<start>\”, \”end\”: \”<end>\”, \”samplingMode\”: <samplingMode>, \”calculationMode\”: <calculationMode>, \”direction\”: <direction>, \”count\”: <count>, \”returnDataFields\”: <returnDataFields>, \”intervalMs\”: <intervalMs>, \”queryModifier\”: <queryModifier>, \”filterMode\”: <filterMode>, \”filterExpression\”: \”<filterExpression>\”}” http://<nodename>:8443/historian-rest-api/v1/datapoints/trend
Table 14. Query Parameters
Parameter Description Required? Values
TagNames Queries the tag names specified. Yes String
Start Start time of the query, in ISO data format (such as YYYY-MM-DDTHH:mm:ss.SSSZ). Yes DateTime
End End time of the query, in ISO data format (such as YYYY-MM-DDTHH:mm:ss.SSSZ). Yes DateTime
SamplingMode Also known as SamplingModeType. Optional Integer, with a value such as 1.
CalculationMode Also known as CalculationModeType. Optional Integer, with a value such as 1.
Direction Specifies the direction (Forward or Backward from the starting time) of data sampling from the archive. The default value is Forward (1). Optional Integer, with a value such as 1.
Count The count of archive values within each calculation interval. Optional Integer, with a value such as 0.
IntervalMS Interval in milliseconds. Optional 64-bit signed integer, with a value such as 1000.
Table 15. Response Parameters
Parameter Data Type Required? Description
ErrorCode Integer Yes For example, 0.
ErrorMessage String Yes For example, NULL.
Data String Yes The object container for the following parameters:
TagName
Name of the tag, such as ahistfile.Simulation00001.
TagSource
Location where tags are being searched for.
DataType
Float, which stores decimal values up to 6 places.
Trend
Provides TimeStamp, Value and Quality for each sample. For example, TimeStamp = 2016-03-15T04:53:17.000Z, Value = 170903.6563, and Quality = True.
The Add Single Tag API

For the Add Single Tag API, you can add a new tag to Historian, and the tag name and data type must be provided in the payload (parameter) of the method. All other tags are optional. If a property is provided, the respective validation is performed at the server end. If the tag exists, then any new properties provided in the payload are applied to the existing tag.

METHOD: POST
URI: https://<historianservername>:8443/historian-rest-api/v1/tags/addtag
SAMPLE DELETE URI: 
https://<historianservername>:8443/historian-rest-api/v1/tags/addtag

Payload:

{
    "Name" : "SampleTag",
    "DataType" : 3
}
SAMPLE cURL COMMAND: curl -i -H "Accept: application/json" -i -H "Content-Type: application/json" -H "Authorization: Bearer <TOKEN>” -d “{ \”Name\”:\”Sampletag\”,\"DataType\":3}” -X POST https://<historianservername>:8443/historian-rest-api/v1/tags/addtag
Table 16. Query Parameters
Parameter Description Required? Values
Payload JSON array of PropertyName and PropertyValue. Yes. "Name" and "DataType" properties are required. All other properties are optional. Multidata types. See Payload Parameter for a list of tag properties used to update a tag configuration.
Sample Response
Parameter Data Type Required? Description
ErrorCode Integer Yes For example, 0.
ErrorMessage String Yes For example, NULL.
The Add Bulk Tags API

For the Add Bulk Tags API, you can add new tags to Historian using an array, and the tag names and data types must be provided in the payload (parameter) of the method. All other tags are optional. If a property is provided, the respective validation is performed at the server end. If the tags exist, then any new properties provided in the payload are applied to the existing tags. The payload is be an array of tags defined.

METHOD: POST
URI: https://<historianservername>:8443/historian-rest-api/v1/tags/addtags
SAMPLE DELETE URI: 
https://<historianservername>:8443/historian-rest-api/v1/tags/addtags

Payload:

[
{
    "Name" : "SampleTag1",
    "DataType" : 3
},
{
    "Name" : "SampleTag2",
    "DataType" : 3
}
]
SAMPLE cURL COMMAND: curl -i -H "Accept: application/json" -i -H "Content-Type: application/json" -H "Authorization: Bearer <TOKEN>” -d “[{ \”Name\”:\”Sampletag1\”}, { \”Name\”:\”Sampletag2\”}]” -X POST https://<historianservername>:8443/historian-rest-api/v1/tags/addtags
Table 17. Query Parameters
Parameter Description Required? Values
Payload JSON array tags with individual tags of PropertyName and PropertyValue. Yes. "Name" and "DataType" properties are required. All other properties are optional. Multidata types. See Payload Parameter for a list of tag properties used to update a tag configuration.
Table 18. Response Parameters
Parameter Data Type Exists? Description
TagName String Yes Tag name.
ErrorCode Integer Yes For example, 0.
ErrorMessage String Yes For example, NULL.
The Update Tag Configuration API

The Update Tag Configuration API allows you to set or modify any tag property values. You cannot, however, rename a tag using this API.

METHOD: PUT
URI: https://<historianservername>:8443/historian-rest-api/v1/tags/properties/tagName
SAMPLE DELETE URI: 
https://<historianservername>:8443/historian-rest-api/v1/tags/properties/tagName

Payload:
{
    "PropertyName" : "PropertyValue"
}
SAMPLE cURL COMMAND: curl -i -H "Accept: application/json" -i -H "Content-Type: application/json" -H "Authorization: Bearer <TOKEN>” -d “{ \”Description\”:\”SampleDesc\”}” -X PUT https://<historianservername>:8443/historian-rest-api/v1/tags/properties/tagName
Table 19. Query Parameters
Parameter Description Required? Values
tagName Tag name for which properties need to be set or modified. Yes String
Payload JSON array of PropertyName and PropertyValue. At least one property must be provided. Multidata types. See Payload Parameter for a list of tag properties used to update a tag configuration.
Table 20. Response Parameters
Parameter Data Type Required? Description
ErrorCode Integer Yes For example, 0.
ErrorMessage String Yes For example, NULL.
The Get Tag Properties API

You can use this API to specify which properties are required for retrieval. If no property names are provided, then all properties are retrieved. When using the Get Tag Properties method, requesting a non-existent tag name returns an error.

METHOD: GET / POST
URI: (GET) https://<historianservername>:8443/historian-rest-api/v1/tags/properties/tagName

This URI returns all tag properties.
URI: (POST) https://<historianservername>:8443/historian-rest-api/v1/tags/properties/tagName
Payload

{
"PropertyName1" : 1,
"PropertyName2" : 1
}
SAMPLE GET URI: https://<historianservername>:8443/historian-rest-api/v1/tags/properties/tagName
SAMPLE POST URI: 
https://<historianservername>:8443/historian-rest-api/v1/tags/properties/tagName

Payload:
{
    "Description" : 1
}
SAMPLE cURL GET COMMAND: curl -i -H "Accept: application/json" -i -H "Content-Type: application/json" -H "Authorization: Bearer <TOKEN>” -X GET https://<historianservername>:8443/historian-rest-api/v1/tags/properties/tagName
SAMPLE cURL POST COMMAND: curl -i -H "Accept: application/json" -i -H "Content-Type: application/json" -H "Authorization: Bearer <TOKEN>” -d “{ \”Description\”: 1}” -X POST https://<historianservername>:8443/historian-rest-api/v1/tags/properties/tagName
Table 21. Query Parameters
Parameter Description Required? Values
tagName Tag name for which properties need to be retrieved. Yes String
Payload JSON array of PropertyName and boolean (true/false). At least one property must be provided. Multi data types. See Payload Parameter for a list of tag properties used to update a tag configuration.
Note: The query payload contains all the tag properties you want returned from the server. In the Update Tag Config method, you need to provide the actual tag property value. However, in the Get Tag Properties method, you need to provide the property and a value of 1 (true), to allow it to be read from the server and returned.
Table 22. Response Parameters
Parameter Data Type Required? Description
ErrorCode Integer Yes For example, 0.
ErrorMessage String Yes For example, NULL.
Name String Optional If no error, then the tag name of query is returned and all requested parameters.
The Delete Tag API

The Delete Tag API provides the ability to delete an existing tag from the Historian server.

Its URI format supports question marks (?).

METHOD: DELETE
URI: https://<historianservername>:8443/historian-rest-api/v1/tags/tagName?{permanentDelete}
SAMPLE DELETE URI: https://<historianservername>:8443/historian-rest-api/v1/tags/tagName?permanentDelete=true
SAMPLE CURL COMMAND: curl -i -H "Authorization: Bearer <TOKEN>” -X DELETE https:// <historianservername>:8443/historian-rest-api/v1/tags/tagName?permanentDelete=<true|false>
Table 23. Query Parameters
Parameter Description Required? Values
tagName Name of the tag to be deleted. Yes String
permanentDelete Deletes the tag permanently from the Historian server if the value passed in is true. If the parameter is not provided, then permanentDelete is assumed to be false. Optional (false is default) Boolean, true or false
Table 24. Response Parameters
Parameter Data Type Required? Description
ErrorCode Number Yes For example, ErrorCode=0, which means the operation was successful.
ErrorMessage String Yes For example, NULL.
The Query Results API

The Query Results API enables you to include the number of samples required, by providing an end point to configure query results.

The minimum number of samples should be 1000.
METHOD: PUT
URI: https://<historianservername>:8443/historian-rest-api/v1/datapoints/ configuration/{maxDataQueryResultSize}
SAMPLE URI: https://<historianservername>:8443/historian-rest-api/v1/datapoints/ configuration?maxDataQueryResultSize=6000
SAMPLE CURL COMMAND: curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” https://<nodename>:8443/ historian-rest-api/v1/datapoints/configuration? maxDataQueryResultSize=<Number_Of_Query_Results>
Table 25. Query Parameters
Parameter Description Required? Values
maxDataQueryResultSize Maximum samples that should be configured as part of Query Results Yes Integer

Maximum DataQueryResultSize set to 6000

The Tag Rename API
This API allows the administrator to rename tags.
METHOD: PUT
URI https://<historianservername>:8443/historian-rest-api/v1/tags/tagrename/oldtagname/newtagname?{truerename}
SAMPLE URI https://<historianservername>:8443/historian-rest-api/v1/tags/tagrename/GDW14NV2E.Simulation0000101/GDW14NV2E.Simulation0000101newname?truerename= <true | false>
SAMPLE CURL COMMAND curl -i -H "Accept: application/json" -i -H "Content-Type: application/json"-H "Authorization: Bearer <TOKEN> -X PUT https://<historianservername>:8443/historian-rest-api/v1/tags/tagrename/<oldtagname>/<newtagname>?truerename=<true | false>
Table 26. Query Parameters
Parameter Description Required? Values
oldtagname Tag which is to be renamed. Yes String
newtagname New name for the selected tag. Yes String
truerename Renames the tag permanently if the value entered is true.

Creates an alias if the value entered is false.

Optional (false is default) Boolean (true or false)
Table 27. Response Parameters
Parameter Data Type Required? Description
Error Code Integer Yes For example, 0.
Error Message String Yes For example, NULL.
Data List Yes Returns all the properties of the tag.
The Write Tag API
Write Tag Data API enables you to create data for tags. You can write data to a tag for different data types such as integer, float, array, multifield and so on. Once created, you can view the data using other end points. Only REST API Administrator and users with write permission can perform this operation.
Method POST
URI 
https://<historianservername>:8443/historian-rest-api
                /v1/datapoints/create
SAMPLE URI 
https://<historianservername>:8443/historian-rest-api   /v1/datapoints/create

   Payload

   {
   "TagName": "GDW14NV2E.Simulation00015",
   "samples": [
                {
                   
                "TimeStamp": "2019-09-17T15:58:00.000Z",
                   
                "Value":   "1",
                   
                "Quality": 3
                }
           ]  
   }
SAMPLE RESPONSE

{

"ErrorCode": 0,

"ErrorMessage": ""

}
SAMPLE CURL COMMAND

curl -i -H "Accept: application/json" -i -H "Content-Type: application/json" -H "Authorization: Bearer <TOKEN>” -d “{ \”TagName\”:\”GDW14NV2E.Simulation00015\”,\"samples\":[{\"TimeStamp\":\ "2019-09-17T15:58:00.000Z\",\"Value\": \"1\",\"Quality\": 3}]}” -X POST https://<historianservername>:8443/historian-rest-api/v1/datapoints/create
Table 28. Query Parameters
Parameter Description Required? Values
Payload JSON format of Property Name and Property Value. Yes Multi-data types. It can have integer, float, array, multifield data types.
Table 29. Response Parameters
Parameter Data Type Required? Description
Error Code Integer Yes For example, ErrorCode = 0, which means the operation was successful.
Error Message String Yes For example, NULL.