Historian REST APIs

Query Parameters

Response Parameters

Sample Response

{
    "ErrorCode":0,
    "ErrorMessage": null,
    "tags": [
        "ALT_SENSOR",
        "tagName1",
        "tagName2"
    ]
}

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

Tags List 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: dogpattern will match dog1, dog2,dogs, dogx, dog12, dogs are faithful, 1dog1and 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, dogxand so on but not dog12or dogs are faithful

Eg2: dog*pattern will match dog1, dog2,dogs, dogx, dog12, dogs are faithfuland so on but not 1dog1

Tags List Pagination Parameters

Sample cURL commands

Example Queries

<baseurl>/v1/tagslist

<baseurl>/v1/tagslist?lastmodified=2017-05-01T00:00:00.00Z

Example Results

{
	"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 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.

Query Parameters

Response Parameters

Sample Response

{
     "ErrorCode" : 0,
     "ErrorMessage": null,
     "Data":[{
      "DataType":"DoubleFloat",
      "ErrorCode":0,
      "TagName":"TagName1",
      "Samples":[ { "TimeStamp":"2013-10-02T11:30:00.111Z","Value":"34.26155","Quality":3 },
                  {  "TimeStamp":"2013-10-02T11:30:10.111Z", "Value":"37.26155", "Quality":3  }, 
                  {  "TimeStamp":"2013-10-02T11:31:00.111Z", "Value":"33.26155", "Quality":3  }
                ]
     }]
}

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.

Query Parameters

Response Parameters

Sample Response

{
     "ErrorCode" : 0,
     "ErrorMessage": null,
     "Data":[{
      "DataType":"DoubleFloat",
      "ErrorCode":0,
      "TagName":"TagName1",
      "Samples":[ { "TimeStamp":"2013-10-02T11:30:00.111Z","Value":"34.26155","Quality":3 },
                  {  "TimeStamp":"2013-10-02T11:30:10.111Z", "Value":"37.26155", "Quality":3  }, 
                                        
                  {  "TimeStamp":"2013-10-02T11:31:00.111Z", "Value":"33.26155", "Quality":3  }                 
                ]
     }]
}

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 requiest returns one sample.

Query Parameters

Response Parameters

Sample Response

{
     "ErrorCode" : 0,
     "ErrorMessage": null,
     "Data":[{
      "DataType":"DoubleFloat",
      "ErrorCode":0,
      "TagName":"TagName1",
      "Samples":[ { "TimeStamp":"2014-01-01T12:00:00Z","Value":"34.26155","Quality":3 } ]
      }]
}

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.

Query Parameters

Response Parameters

Sample Response

{
     "ErrorCode" : 0,
     "ErrorMessage": null,
     "Data":[{
      "DataType":"DoubleFloat",
      "ErrorCode":0,
      "TagName":"TagName1",
      "Samples":[ { "TimeStamp":"2013-10-02T11:30:00.111Z","Value":"34.26155","Quality":3 },
                  {  "TimeStamp":"2013-10-02T11:30:10.111Z", "Value":"37.26155", "Quality":3  }, 
                  {  "TimeStamp":"2013-10-02T11:31:00.111Z", "Value":"33.26155", "Quality":3  } 
                ]
     }]
}

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.

Query Parameters

Response Parameters

Sample Response

{
     "ErrorCode" : 0,
     "ErrorMessage": null,
     "Data":[{
      "DataType":"DoubleFloat",
      "ErrorCode":0,
      "TagName":"TagName1",
      "Samples":[ { "TimeStamp":"2013-10-02T11:30:00.111Z","Value":"34.26155","Quality":3 },
                  {  "TimeStamp":"2013-10-02T11:30:10.111Z", "Value":"37.26155", "Quality":3  }, 
                  {  "TimeStamp":"2013-10-02T11:31:00.111Z", "Value":"33.26155", "Quality":3  } 
                ]
     }]
}

The Trend Data API queries the trend data for a list of tags.

Query Parameters

Response Parameters

Sample Response

{
	"ErrorCode": 0,
	"ErrorMessage": null,
	"Data":  {
		"TagName": "ahistfile.Simulation00001",
		"TagSource": "localhost",
		"DataType": "Float",
		"Trend":[
		        { "Timestamp":"2016-03-15T04:53:17.000Z","Value":"170903.6563","Quality":true }
	]}
}

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.

Query Parameters

Response Parameters

Sample Payload

{
"Name" : "tag1",
"DataType" : 3 ,
"Id": "F34CFE80-7428-41A1-AC67-DB0F3D2E1146"
}

Sample Response

{
"ErrorCode": 0,
"ErrorMessage": null
}

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.

Query Parameters

Response Parameters

Sample Payload

[
  {
    "Name": "tag1",
    "Description": 1
  },
  {
    "Name": "tag2",
    "DataType": 3,
    "Description": 3
  }
]

Sample Response

[
  {
    "TagName": "Tag1",
    "ErrorCode": 10,
    "ErrorMessage": "Fail to validate the tag Tag1 error is 'Invalid data type'"
  },
  {
    "TagName": "Tag2",
    "ErrorCode": 0,
    "ErrorMessage": ""
  }
]

The Update Tag Configuration API allows you to set or modify any tag property values.

A Rename cannot be done using the Update Tag Configuration properties.

Query Parameters

Response Parameters

Sample Payload

{
     "Description" : "Test desc".
     "CollectionOffset" : 4294967295 
     }

Sample Response

{
"ErrorCode": 0,
"ErrorMessage": null
}

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.

Query Parameters

Response Parameters

The response always includes these parameters.

Sample Response

{
  ErrorCode: 0,
  ErrorMessage: NULL,
    "Name": "AnilGH7-1.Simulation00001",
    "Description": "AnilGH7-1.Simulation00001",
    "EngineeringUnits": null,
    "Comment": null,
    "CollectorName": "ANILGH7-1_Simulation",
    "SourceAddress": "Simulation00001",
    "CollectionType": 2,
    "DataType": 2,
    "FixedStringLength": 8,
    "CollectionInterval": 1000,
    "CollectionOffset": 0,
    "LoadBalancing": false,
    "TimeStampType": 2,
    "HiEngineeringUnits": 200000,
    "LoEngineeringUnits": 0,
    "InputScaling": true,
    "HiScale": 32767,
    "LoScale": 0,
    "CollectorCompression": false,
    "CollectorDeadbandPercentRange": 0,
    "ArchiveCompression": false,
    "ArchiveDeadbandPercentRange": 0,
    "General1": null,
    "General2": null,
    "General3": null,
    "General4": null,
    "General5": null,
    "ReadSecurityGroup": null,
    "WriteSecurityGroup": null,
    "AdministratorSecurityGroup": null,
    "LastModified": "2016-08-31T10:34:37.749Z",
    "LastModifiedUser": "\\admin",
    "CollectorType": 2,
    "UTCBias": 0,
    "CalculationDependencies": [],
    "CollectionDisabled": false,
    "ArchiveCompressionTimeout": 0,
    "CollectorCompressionTimeout": 0,
    "SpikeLogic": true,
    "SpikeLogicOverride": false,
    "CollectorAbsoluteDeadbanding": false,
    "CollectorAbsoluteDeadband": 0,
    "ArchiveAbsoluteDeadbanding": false,
    "ArchiveAbsoluteDeadband": 0,
    "StepValue": false,
    "TimeResolution": 0,
    "ConditionCollectionEnabled": false,
    "ConditionCollectionTriggerTag": null,
    "ConditionCollectionComparison": 1,
    "ConditionCollectionCompareValue": null,
    "ConditionCollectionMarkers": true,
    "Calculation": "Simulation00001",
    "Id": "A4FD6A00-BE45-463F-93C9-F287F3220B31",
    "EnumeratedSetName": null,
    "DataStoreName": "User",
    "DefaultQueryModifiers": 0,
    "UserDefinedTypeName": null,
    "NumberOfElements": 0,
    "DataDensity": 4,
    "CalcType": 0,
    "HasAlias": false,
    "IsStale": false
}

The response always includes the Name field. The Calculation property is returned only when the tags interface type is 9 (S2S Collector type) tag.

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

Its URI format supports question marks (?).

Query Parameters

Response Parameters

Sample Response

{
     "ErrorCode": 0,
     "ErrorMessage": null, 
     }