Time Series Historian REST API

The Historian REST API provides access to create and configure Datasets, create and configure Tags, and read and write Tag data.

API Documentation

GET Datasets API Call

GET Dataset API Call

POST Dataset API Call

GET Tags API Call

POST Tags API Call

GET Tag Data API Call

POST Tag Data API Call

POST Dataset Status API Call

---

 

API Documentation

The REST API documentation is available at:

http://<HistorianHostnameOrIPAddress>:4511/api/help

Authentication

API Calls

The following REST API calls are available:

GET Datasets

Returns an array of the configured datasets in the Real Time Historian with its purging rules.

Return Schema:

[ 
 { 
   "n": "MQTT Data",
   "pa": 7,
   "ps": 0 
 }, 
 {
   "n": "The Juice Factory",
   "pa": 7,
   "ps": 0 
 } 
]

• n - Name of the dataset (String)
• pa - Purge Age. Set in Days (Int 32)
• ps - Purge Size. Set in Gigs (Int 32)
  
  

GET Dataset

Returns an object of the configured dataset in the Real Time Historian with its purging rules.

Return Schema:

{ 
 "n": "The Juice Factory", 
 "pa": 7, 
 "ps": 0 
}

• n - Name of the dataset (String)
• pa - Purge Age. Set in Days (Int 32)
• ps - Purge Size. Set in Gigs (Int 32)

POST Dataset

Updates / Creates a dataset in the Real Time Historian

Request Body:

{   
 "n": "The Juice Factory",
 "pa": 14,
 "ps": 0 
}

• n - Name of the dataset (String) *required
• pa - Purge Age. Set in Days (Int 32) *required
• ps - Purge Size. Set in Gigs (Int 32) *required
  
  

GET Tags

Returns an array of tags stored within the particular dataset. Tags will be classified between System generated diagnostics tags and user generated tags in the response.

Optional URL parameter:

contains - Filter criteria for tags to be returned (String)

Return Schema:

{ 
 "n": "FL001.State",
 "d": "Filler 1 State",
 "u": 
 {
  "0": "Idle",
  "10": "Startup",
  "20": "Running",
  "21": "Bottle starvation",
  "22": "Bottle jam",
  "23": "Downstream bottleneck",
  "30": "Cleaning"
 },
 "fl": 
 {
  "Measure": "State",
  "Product": "Juice",
  "Area Code": "131",
  "Equipment": "Filler",
  "Equipment Number": "1"
 },
"t": "System.Integer"
}

• n - Name of the tag (String)
• d - Description of the tag (String)
• f - Format of the value (String)
• u - Unit of Measure or State Enumeration (dictionary <Int32,String>)
• fl- Fields. Metadata associated with a tag (dictionary <String,String>)
• t - Data Type of the tag

POST Tags

Updates or creates an array of tags stored within the particular dataset. 

Request Body:

[
 {
  "n": "string",
  "d": "string",
  "f": "string",
  "u": 
  {
   "additionalProp1": "string",
   "additionalProp2": "string",
   "additionalProp3": "string"
  },
  "fl": 
  {
   "additionalProp1": "string",
   "additionalProp2": "string",
   "additionalProp3": "string"
  },
 "t": "string"
 }
]

• n - Name of the tag (String) *required
• d - Description of the tag (String)
• f - Format of the value (String)
• u - Unit of Measure or State Enumeration (dictionary <Int32,String>)
• fl- Fields. Metadata associated with a tag (dictionary <String,String>
  
  

POST Tag

Updates or creates a tag stored within the particular dataset. 

Request Body:

{
 "n": "string",
 "d": "string",
 "f": "string",
 "u": 
  {
   "additionalProp1": "string",
   "additionalProp2": "string",
   "additionalProp3": "string"
  },
 "fl": 
  {
   "additionalProp1": "string",
   "additionalProp2": "string",
   "additionalProp3": "string"
  },
 "t": "string"
}

• n - Name of the tag (String) *required
• d - Description of the tag (String)
• f - Format of the value (String)
• u - Unit of Measure or State Enumeration (dictionary <Int32,String>)
• fl- Fields. Metadata associated with a tag (dictionary <String,String>)
• t - Data Type of the tag
  
  

GET Tag Data

Returns the requested tags' Data stored in the particular dataset. Start and end time can either be supplied in standard ISO notation or UNIX format. Relative time can also be specified for either start or end times.

If no times are specified in the request, the latest point will be returned. If no end time is specified, it will default to "now".

Optional URL parameter:

start - Start timestamp to return data. ISO format

end - End timestamp to return data. ISO format

unixStart - Start timestamp to return data. UNIX Format

unixEnd - End timestamp to return data. UNIX Format

relativeStart - Relative start time i.e -2h

relativeEnd - Relative end time i.e -1h

Relative time periods include:

y - Years

M - Months

d - Days

h - Hours

m - Minutes

Return Schema:

{
 "t": 
  {
   "n": "Process.Memory",
   "d": "Process memory usage",
   "f": "0.0",
   "u": 
    {
     "1": "MB"
    }
  },
 "s": "2024-10-02T16:12:58.716699Z",
 "e": "2024-10-02T16:12:58.716699Z",
 "d": 
  [
   {
    "t": "2024-10-02T16:12:53.643451Z",
    "v": 615.0390625,
    "q": 192
   }
  ]
}

• t - tag object
• s - start time
• e - end time
• d - TVQ array of data

POST Tag Data

Post array of TVQ values to a tag in a particular dataset.

Request Body:

[
 {
  "t": "2024-10-02T16:16:50.989Z",
  "v": "string",
  "q": 0
 }
]

• t - timestamp
• v - value
• q - quality
  
  

POST Dataset Status

Post a TVQ value to mark the current status of a dataset. To be used to handle loss of comms etc.

Request Body:

[
 {
  "t": "2024-10-02T16:16:50.989Z",
  "v": "string",
  "q": 0
 }
]

• t - timestamp
• v - value
• q - quality

Standard quality codes and values to be used include:

• null value and 64 quality, collector's heartbeat has not been detected for 10 seconds, all collector's tags set to Store Forward
• null value and 28 quality, collector has shutdown
• null value and 24 quality, collector is communicating with the Historian, but the collector has lost communication with its data source