Historian REST APIs© 2016 General Electric Company.
GE, the GE Monogram, and Predix are either registered trademarks or trademarks of General Electric Company.All other trademarks are the property of their respective owners.
This documentmay contain Confidential/Proprietary information of General Electric Company and/or its suppliersor vendors. Distribution or reproduction is prohibited without permission.
THIS DOCUMENT AND ITS CONTENTS ARE PROVIDED "AS IS," WITH NO REPRESENTATION ORWARRANTIES OF ANYKIND,WHETHEREXPRESSOR IMPLIED, INCLUDINGBUTNOTLIMITEDTOWARRANTIESOFDESIGN,MERCHANTABILITY,OR FITNESS FORAPARTICULARPURPOSE. ALLOTHER LIABILITY ARISING FROMRELIANCEUPONANY INFORMATIONCONTAINED HEREIN IS EXPRESSLY DISCLAIMED.
Access to and use of the software described in this document is conditioned on acceptance of the End UserLicense Agreement and compliance with its terms.
Contents
Historian APIs Overview 5
Historian APIs Overview 5About Security and Authentication 5Standards 7API Methods 7API Status Messages 7
General API Information 9
Overview of Commonly Used API Parameters 9TagNames Parameter 9Start and End Timestamps Parameter 9TagSamples Parameter 10DataSample Parameter 11SamplingModeType Parameter 12Direction Parameter 13CalculationModeType Parameter 14FilterModeType Parameter 18ReturnDataFields Parameter 18Payload Parameter 19Error Code Definitions 24
Historian REST APIs 26
Overview of the Historian REST APIs 26Tags List API 26Raw Data API 28Interpolated Data API 31Current Value API 33Calculated Data API 34Sampled Data API 37Trend Data API 39Add Single Tag API 41Add Bulk Tags API 42Update Tag Configuration API 44
iiiHistorian REST APIs
Historian APIs Overview
Historian APIs Overview
Historian is a high performance data archiving system designed to collect, store, and retrieve time-basedinformation at extremely high speed efficiently. The Historian environment provides a set of REST APIs toquery data from the archives.
This document provides links for setting up your development environment, aswell as information for gettingstarted with the Historian services and their associated APIs.
Important: Port 8443 is used in examples and sample code throughout the e-book. If you copy andpaste the sample code from this document, you must change this port to your installed port.
See the following topics for more information:
• About Security and Authentication on page 5• Standards on page 7• API Methods on page 7• API Status Messages on page 7
About Security and Authentication
For security purposes, Historian uses the User Account and Authentication (UAA) service as a trusted sourceof tokens issued for authentication. The UAA is a multi-tenant identity management service, used in CloudFoundry, but also available as a standalone OAuth2 server. Its primary role is as an OAuth2 provider, issuingtokens for client applications to usewhen they act on behalf of Cloud Foundry users. It can also authenticateusers with Cloud Foundry credentials, and can act as an SSO service using those credentials, or others. Itcontains endpoints formanaginguser accounts, registeringOAuth2 clients, andothermanagement functions.
The following diagram shows how the UAA Server functions with a Python REST client:
5© 2016 General Electric Company.
Figure 1: UAA Server and Python REST Client
Authorization
For exchanging data between the client-server system, user authentication is required. Once you haveprovided your client credentials, an access or bearer token is generated. This token is used for the RESTAPIs.
cURL command format for generating an oauth token:curl -u <Client-Id>:<Client-secret>https://<nodename>:8443/uaa/oauth/token -d 'grant_type=client_credentials'
Sample cURL command: curl -u admin:adminsecret https://<nodename>:8443/uaa/oauth/token -d 'grant_type=client_credentials'
Note: In the following image, the actual token text is blurred for security concerns.
Figure 2: OAuth Access Token Sample
Client applications can access data using service REST API endpoints. Your application makes an HTTPrequest and parses the response. You can use any web-development language to access the APIs.
© 2016 General Electric Company.6
Standards
Historian APIs use a REST application architecture constrained by Hypermedia as the Engine of ApplicationState (HATEOAS) that distinguishes it frommost other network application architectures. Therefore, a clientinteracts with a network application entirely through hypermedia provided dynamically by applicationservers. The REST client doesn't need prior knowledge about how to interact with a particular applicationor server beyond a basic understanding of hypermedia.
As defined by the query parameters, the Historian APIs use "search" functions to access raw data usingcURL and HTTP, while responses are in JSON format.
cURL is a command-line utility used to transfer data fromor to a server, using one of the supported protocols,such as DICT, FILE, FTP, FTPS, GOPHER, HTTP, HTTPS, IMAP, IMAPS, LDAP,LDAPS, POP3, POP3S, RTMP, RTSP,SCP, SFTP, SMTP, SMTPS, TELNET and TFTP. The command is designed to work without user interaction.
cURL offers many useful functions such as proxy support, user authentication, FTP upload, HTTP post, SSLconnections, cookies, file transfer resume, user and password authentication, and more.
You can run the sample commands provided in this document from Bash on Windows in the Windowsoperating system, and also in Linux Shell in the Linux operating system.
As a prerequisite, make sure you install cURL on your system, if it is not already installed. Run the curl --version command on Windows Bash or Linux shell to check if cURL is installed on your system.
Important: Do not create your own URIs. Instead, use the links in this document and in the responsesto navigate between resources.
API Methods
The Historian APIs use GET, POST, PUT, and DELETE methods.
UsageMethod
Retrieves a resource.GET
Creates (or adds) a resource.POST
Updates a resource.PUT
Removes a resource.DELETE
API Status Messages
In its use of the following HTTP status codes, the Historian API services adhere as closely as possible tostandard HTTP and REST conventions.
UsageStatus Code
Success message. The request has completed.200 OK
7© 2016 General Electric Company.
UsageStatus Code
Success message. A new resource has been created. The resource URI isavailable from the location header in the response.
201 Created
Success message. An update to an existing resource has been applied.204 No Content
Error message. The request was malformed. The response body providesadditional information.
400 Bad Request
Error message. Either you are not authenticated, or the authentication isincorrect. You must re-authenticate and try again.
401 Unauthorized
Error message. You do not have permission to access this resource.403 Forbidden
Error message. The requested resource does not exist.404 Not Found
Error message. The server encountered an unexpected condition thatprevented it from fulfilling the request.
500 Internal Error
© 2016 General Electric Company.8
General API Information
Overview of Commonly Used API Parameters
The Historian REST service provides various REST API calls to retrieve the current tags list and query datawith different sampling modes. Most of these API calls use the following common parameters:
• TagNames Parameter on page 9• Start and End Timestamps Parameter on page 9• TagSamples Parameter on page 10• DataSample Parameter on page 11• SamplingModeType Parameter on page 12• Direction Parameter on page 13• CalculationModeType Parameter on page 14• FilterModeType Parameter on page 18• ReturnDataFields Parameter on page 18• Payload Parameter on page 19• Error Code Definitions on page 24
TagNames Parameter
By default, the Historian REST service provides support to read samples formultiple tags. Multiple tag namesare separated by semicolons (;). For example, "tagname1;tagname2;tagname3".
https://<historianservername>:8443/historian-rest-api/v1/datapoints/currentvalue?tagNames=tagName1;tagname2;tagname3
Encode the semicolon as%3B if using theURI format, as the semicolon is also a valid character for aHistorianname, and the web service parses the tag names incorrectly if a tag name contains a semicolon.
Start and End Timestamps Parameter
For the Start and End Timestamps parameter, the Timestamp format in the URI must be in ISO data format,such as YYYY-MM-DDTHH:mm:ss.SSSZ.
EPOCH time (standard base time) is only valid in the JSON-format request body or response body, such as\/Date(928167600000-0500)\/. If you use the same timestamp for start and end timestamps, therequest returns a single result.
All timestamps passed to the REST service must be formatted as UTC timestamps.
9© 2016 General Electric Company.
DescriptionObject Name
Start time of the query. This represents the earliesttimestamp for any tag contained in the query.
If no StartTime is specified, the start time is two hoursprior to running the query.
StartTime
End time of the query. This represents the latesttimestamp for any tag contained in the query.
If no EndTime is specified, the end time is the timethat the query runs.
EndTime
TagSamples Parameter
The TagSamples parameter is the output from the REST API calls.
DescriptionPropertyType
PropertyName
Name of the tag.StringTagName
Tag Data Type Value:StringDataType
• Blob – Stores tags as binary large objects. The Blob datatype generallyrefers to undeterminedbinary data types, such as an Excel spreadsheet,a PDF file, or a Word file.
• Boolean (one byte) – Stores boolean values. Valid values for the booleandata type are 0=FALSE and 1=TRUE. If the user sends zero, the value istaken as zero. Anything other than zero, the value is treated as one.
• Byte (one byte) – Stores integer values. Valid values for the byte datatype are -128 to +127.
• SingleFloat (four bytes) – Stores decimal values up to six places. Validranges for the single float data type are 1.175494351e-38F to3.402823466e+38F
• DoubleFloat (eight bytes) – Stores decimal values up to 15 places. Validvalues for the double float data type are 2.2250738585072014e-308to 1.7976931348623158e+308.
• SingleInteger (two bytes) – Stores whole numbers, without decimalplaces. Valid values for the single integer data type are -32767 to+32767.
• DoubleInteger (four bytes) – Stores whole numbers, without decimalplaces. Valid values for the double integer data type are -2147483648to +2147483648.
• FixedString (Configured by user) – Stores string data of a fixed size.Valid values are between 0 and 255 bytes.
• Float – Single float.• Integer – Single integer.• MultiField – Stores string data that has multiple words.
© 2016 General Electric Company.10
DescriptionPropertyType
PropertyName
• QuadInteger (eight bytes) – Stores whole numbers without decimalplaces. Valid values for the quad integer data type are-9,223,372,036,854,775,808 (negative nine quintillion) to+9,223,372,036,854,775,807 (positive nine quintillion).
• Scaled (two bytes) – Lets you store a four-byte float as a twobyte integerin the Historian archive. The scaled data type saves disk space butsacrifices data precision as a result.
• Time – Returns or sets the type of time stamping applied to data atcollection time.
• UDoubleInteger (UnsignedDouble Integer) (four bytes) – Storeswholenumbers without decimal places. Valid values for the unsigned doubleinteger data type are 0 to 4,294,967, 295 (4.2 billion).
• Undefined – Data type is not defined.• UQuadInteger (Unsigned Quad Integer) (eight bytes) – Stores whole
numbers without decimal places. Valid values for the unsigned quadinteger data type are 0 to 18,446,744,073,709,551,615 (19 quintillion).
• USingleInteger (Unsigned Single Integer) (two bytes) – Stores wholenumbers without decimal places. Valid values for the unsigned singleinteger data type are 0 to 65535.
• VariableString (No fixed size) – Stores string values of undeterminedsize. This data type is useful if you cannot rely on a constant stringlength from your data source.
• Array – Returns an array of tags fromyour data source. You can specifyorientation, size, and number of rows returned in the array.
Error Code Definition
See Error Code Definitions on page 24 for more information.
Error CodeErrorCode
See DataSample Parameter on page 11 for more information.DataSample
Samples
DataSample Parameter
The DataSample Parameter specifies the number of data samples to retrieve from the archive. Samples areevenly spaced within the time range defined by start time and end time for most sampling modes.
DescriptionProperty TypeProperty Name
Format for a multi-field tag like {"field1":"1","field2":"1000.0"} (user-defined type tag).
JavaScript code can parse the valuestring as a JSON object. All field valuesare string.
StringValue
11© 2016 General Electric Company.
DescriptionProperty TypeProperty Name
Start and end times of the query. If nostart time is specified, the start time is
DateTimeTimeStamp
two hours prior to running the query. Ifno EndTime is specified, the end time isthe time the query runs.
Data type consisting of a set of namedvalues called elements, members or
Integer
(Enumerated value ofDataQuality.StatusType)
Quality
enumerators of the type. Property valuesreflect quality as "quality is good" or "quality is bad".
Value andStatus • 0 – Bad
• 1 – Uncertain• 2 – NA• 3 – Good
SamplingModeType Parameter
The SamplingModeType parameter is the mode of sampling data from the archive. The default setting forthe Sampling Mode is Calculated.
ValueDescriptionProperties
0Sampling mode is not defined.Undefined
1Retrieves the current value. The time-interval criteria are ignored.
CurrentValue
2Retrieves evenly-spaced, interpolatedvalues based on interval or
Interpolated
NumberOfSamples and the time-framecriteria.
3Returns the raw minimum and rawmaximum value for each specified
Trend
interval. Use the Trend samplingmode tomaximize performance when retrievingdata points for plotting. For the Trendsampling mode, if the sampling intervaldoes not evenly divide by the intervallength, Historian ignores any leftovervalues at the end, rather than puttingthem into a smaller interval.
4Retrieves raw archive values based ontime-frame criteria.
RawByTime
© 2016 General Electric Company.12
ValueDescriptionProperties
5Retrieves rawarchive values based on theStartTime criteria, theNumberOfSamples,
RawByNumber
andDirection criteria. The EndTimecriteriais ignored for this sampling mode.
6Retrieves evenly spaced calculated valuesbased onNumberOfSamples, interval, the
Calculated
time frame criteria, and theCalculationMode criteria.
7Returns actual collected values withoutinterpolation.
Lab
8Provides rawdata in place of interpolateddata when the number of samples arefewer than the available samples.
InterpolatedtoRaw
9The TrendtoRaw sampling mode almostalways produces the same results as the
TrendtoRaw
Trend sampling mode. However, whenmore samples are requested than thereare raw data points, the TrendtoRawsampling mode returns all available rawdata points with no further processing.Use TrendtoRaw in place of Trend whenthis condition exists.
10Provides raw data for the selectedcalculateddata,whenNumberOfSamplesis less than the available samples.
LabtoRaw
11Returns filtered time ranges using thefollowing values:
RawByFilterToggle
• 1 – true• 0 – false
This samplingmode is used with the timerange and filter tag conditions. Theresponse string starts with a starting timestamp and ends with an endingtimestamp.
Direction Parameter
TheDirection Parameter specifies the direction (Forward or Backward from the starting time) of data samplingfrom the archive. The default value is Forward.
ValueDirection
0Forward
13© 2016 General Electric Company.
ValueDirection
1Backward
CalculationModeType Parameter
The CalculationModeType parameter is only applied if the Sampling Mode is set to Calculated. It representsthe type of calculation to use on the archive data. The default Calculation Mode, if none is specified, isAverage.
ValueDescriptionCalculation Mode Type
0Calculation mode is not defined.Undefined
1Retrieves the time-weighted average for eachcalculation interval.
Average
2Retrieves the time-weighted standarddeviation for each calculation interval.
StandardDeviation
3Retrieves the time-weighted rate total for eachcalculation interval.
Use rate totals when working with acontinuous measurement. Time weighting
Total
takes into account that compressed data isnot evenly spaced in time. A factor must beapplied to the total value to convert intoappropriate engineering units. As a rate total,the default is Units/Day. If the actual units ofthe continuous measurement areUnits/Minute, you would multiply the resultsby 1440 (minutes per day) to convert the totalinto appropriate engineering units.
4Retrieves the minimum value for eachcalculation interval.
Minimum
5Retrieves the maximum value for eachcalculation interval.
Maximum
6Counts the number of raw samples foundwithgood quality in the interval.
Value is the count of raw samples with goodquality in the interval. The values of each
Count
sample are ignored. The Count does notinclude any samples of bad quality, includingthe start and end of collection markers.
For Quality, the percentage of good samplesis always 100, even if the interval does notcontain any raw samples, or contains only badquality samples.
© 2016 General Electric Company.14
ValueDescriptionCalculation Mode Type
Count is useful for analyzing the distributionof the raw data samples to determine theeffect of compression deadbands. It is alsouseful to determinewhich tags are consumingthe most archive space.
7Retrieves the arithmetic average of all goodquality raw samples for each calculationinterval.
Value is the sum of all good quality samplesin the interval, divided by the number of good
RawAverage
quality samples in the interval. All bad qualitysamples are ignored. That is RawAverage isequivalent to RawTotal divided by the Count.
For Quality, if there are no raw samples in theinterval or if they all are bad quality, then thepercentage of good is 0. Otherwise, thepercentage of good is always 100, even if theinterval contains bad quality samples.
RawAverage is useful for calculating anaccurate average when a sufficient numberof raw samples are collected.
8Retrieves the arithmetic standard deviation ofraw values for each calculation interval.
For Value, any raw point of bad data qualityis ignored.
RawStandardDeviation
For Quality, if there are no raw samples in theinterval or they all have bad quality, then thepercentage of good is 0. Otherwise, thepercentage of good is always 100, even if theinterval contains bad quality samples.
RawStandardDeviation is useful for calculatingan accurate standard deviation when asufficient number of raw samples arecollected.
9Retrieves the arithmetic total (sum) of sampledvalues for each interval.
Value is the sum of the good quality values ofall raw samples in the interval. All bad qualitysamples are ignored.
RawTotal
For Quality, the percentage of good samplesis always 100, even if the interval does notcontain any raw samples or it contains onlybad quality samples.
15© 2016 General Electric Company.
ValueDescriptionCalculation Mode Type
If the same start and end times are used, andthe time span is treated as a single interval,then all values are added together.
RawTotal is useful for calculating an accuratetotalwhena sufficient number of raw samplesare collected. Note that unlike ihTotal, this isa simple sum with no assumption that thevalues are rate values.
10Retrieves the timestampof theminimumvaluefound within each calculation interval. It can
MinimumTime
be a raw or an interpolated value. Theminimummust be agooddata quality sample.
11Retrieves the timestamp of the maximumvalue found within each calculation interval.
MaximumTime
It can be a raw or an interpolated value. Themaximummust be a good data qualitysample.
12Retrieves the amount of time (milliseconds)during the interval when the data is of goodquality and the filter condition is met.
TimeGood
13Retrieves the amount of time a tag uses totransition to another state from a previousstate during a time interval.
StateCount
14Retrieves the duration that a tag stayed in agiven state within an interval.
StateTime
15Retrieves the OPCQAND, bit-wise ANDoperation of all the 16-bit OPC qualities of theraw samples stored in the specified interval.
Note that OPC Quality is a subfield forQuality-Value-Timestamp (QVT), so when this
OPCQAnd
calculation mode is used, OPC Quality isconsidered for calculation.
16Retrieves the OPCQOR, bit-wise OR operationof all the 16-bit OPC qualities of the rawsamples stored in the specified interval.
Note that OPC Quality is a subfield forQuality-Value-Timestamp (QVT), so when this
OPCQOr
calculation mode is used, OPC Quality isconsidered for calculation.
17Retrieves the first good raw sample value fora given interval.
Value is the value of the raw sample, or zeroif there are no good raw samples in theinterval.
FirstRawValue
© 2016 General Electric Company.16
ValueDescriptionCalculation Mode Type
For Quality, if there are not good raw samplesin the interval, then the percentage of good is0. Otherwise, the percentageof good is always100, even if the interval contains bad qualitysamples. Note that Quality is the same forFirstRawValue and FirstRawTime.
The Raw sample has a quality of Good, Bad,or Uncertain, and that is converted to a 0 or100 percent.
18Retrieves the first good raw timestamp for agiven interval.
Value is the timestamp of the sample or theyear 1969 if there are no good raw samplesin the interval.
FirstRawTime
For Quality, if there are not good raw samplesin the interval, then the percentage of good is0. Otherwise, the percentageof good is always100, even if the interval contains bad qualitysamples. Note that Quality is the same forFirstRawValue and FirstRawTime.
The Raw sample has a quality of Good, Bad,or Uncertain, and that is converted to a 0 or100 percent.
19Retrieves the last good raw sample value fora given time interval.
Value is the value of the raw sample or zero ifthere are no good raw samples in the interval.
LastRawValue
For Quality, if there are no good raw samplesin the interval, the the percentage of goodsamples is 0. Otherwise, the percentage ofgood is always 100, even if the intervalcontains bad samples. Note that Quality is thesame for LastRawValue and LastRawTime.
The Raw sample has a quality of Good, Bad,or Uncertain, and that is converted to a 0 or100 percent.
20Retrieves the last good timestamp of the lastvalue for a given time interval.
Value is the timestamp of the sample or theyear 1969 if there are no good raw samplesin the interval.
LastRawTime
For Quality, if there are no good raw samplesin the interval, the percentage of goodsamples is 0. Otherwise, the percentage of
17© 2016 General Electric Company.
ValueDescriptionCalculation Mode Type
good is always 100, even if the intervalcontains bad samples. Note that Quality is thesame for LastRawValue and LastRawTime.
The Raw sample has a quality of Good, Bad,or Uncertain, and that is converted to a 0 or100 percent.
21Retrieves the statistics for a tag from thearchive stored in the specified interval.
TagStats
FilterModeType Parameter
The FilterModeType parameter defines how time periods before and after transitions in the filter conditionshould be handled.
When the FilterModeType parameter is applied, then the Start time and End time are specified as:
• ExactTime• BeforeTime• AfterTime• BeforeAndAfterTime
For example, AfterTime indicates that the filter condition should be True starting at the timestamp of thearchive value that triggered the True condition, and leading up to the timestamp of the archive value thattriggered the False condition.
ValueDescriptionProperties
1Retrieves data for the exact times thatthe filter condition is True.
ExactTime
2Retrieves data from the timestamp ofthe last False filter condition to thetimestamp of the next True condition.
BeforeTime
3Retrieves data from the timestamp ofthe True filter condition to thetimestamp of the next False condition.
AfterTime
4Retrieves data from the timestamp ofthe last False filter condition to thetimestamp of the next False condition.
BeforeAndAfterTime
ReturnDataFields Parameter
The ReturnDataFields bitwise parameter specifies which data fields are returned in a query. Using it in aquery returns data such as TimeStamp, and each field returns a Boolean value.
© 2016 General Electric Company.18
Each time-series data sample contains QVT (quality, value, and timestamp) values. If ReturnDataFields isnot provided, then the default value of 0 is considered, and all QVT values are returned for each data sample.To return one of the data field properties, such as TimeStamp, use the TimeStamp option as shown in thetable.
Field value (Boolean)DescriptionProperties
0 (0000)Specifies that all data fieldsare returned in the query.
All Fields
1 (0001)The time stamp of thecollected sample or an interval
TimeStamp
time stamp.When specified inthe query, returns theTimeStamp property.
2 (0010)The collected value orsampled value; the data type
Value
of the value will be the samedata type as the tag's rawdata.
4 (0100)When specified in the query,returns the Quality property.
Quality
Each sample in Current Valueand Raw query retrieval has aquality of:
• Good (3)• Not Available (2)• Uncertain (1)• Bad (0)
Interpolated and Lab Retrievalexpress quality as "percentgood".
Payload ParameterThis parameter queries for the tag properties requested from the server.
Use the Payload parameter to query for all the tag properties to return from the server. In the Update TagConfiguration API, you must provide the actual tag property value. However, in the Get Tag Properties API,you must provide the property name and value of 1 (true), so the property can be read from the server andreturned.
The properties listed in the following table are valid in APIs that use the Payload parameter, unless otherwisespecified. For Property Names used in the Get Tag Properties API, the property name is always a Boolean(true/false) value, while it can be a string or integer for other APIs.
DescriptionPropertyType
Property Name
Used for Get Tag Properties API.BooleanAllFields
19© 2016 General Electric Company.
DescriptionPropertyType
Property Name
Used for the Get Tag Properties API, Add Single TagAPI, and Add Bulk Tags API.
Boolean,String
Name
StringDescription
StringEngineeringUnits
StringComment
Type definition is an enumerated type "ihDataType".
{ihDataTypeUndefined = 0,
SignedIntegralDataType : ihDataType
ihScaled,ihFloat,ihDoubleFloat,ihInteger,ihDoubleInteger,ihFixedString,ihVariableString,ihBlob,ihTime,ihInt64,ihUInt64,ihUInt32,ihUInt16,ihByte,ihBool,ihMultiField,ihArray,ihMaxDataType} ihDataType;
UnsignedCharFixedStringLength
StringCollectorName
StringSourceAddress
Type definition is an enumerated type"ihCollectionType".
{ihUnsolicited = 1,
SignedIntegralCollectionType : ihCollectionType
ihPolled} ihCollectionType;
SignedIntegralCollectionInterval
UnsignedLongCollectionOffset
BooleanLoadBalancing
© 2016 General Electric Company.20
DescriptionPropertyType
Property Name
Type definition is an enumerated type"ihTimeStampType".
{ihSource = 1,
SignedIntegralTimeStampType : ihTimeStampType
ihInterface,} ihTimeStampType;
DoubleHiEngineeringUnits
DoubleLoEngineeringUnits
BooleanInputScaling
DoubleHiScale
DoubleLoScale
BooleanCollectorCompression
FloatCollectorDeadbandPercentRange
BooleanArchiveCompression
FloatArchiveDeadbandPercentRange
StringGeneral1
StringGeneral2
StringGeneral3
StringGeneral4
StringGeneral5
StringReadSecurityGroup
StringWriteSecurityGroup
StringAdministratorSecurityGroup
Used for Get Tag Properties API.BooleanLastModified
Used for Get Tag Properties API.BooleanLastModifiedUser
Used for Get Tag Properties API.BooleanInterfaceType
Type definition is an enumerated type"ihInterfaceType".
{ihInterfaceUndefined = 0,
SignedIntegralCollectorType : ihInterfaceType
ihIFix,ihRandom,ihOPC,ihFile,ihIFixLabData,ihManualEntry,
21© 2016 General Electric Company.
DescriptionPropertyType
Property Name
ihOther,ihCalcEngine,ihServerToServer,ihPI,ihOPCAE,ihCIMPE,ihPIDistributor,ihCIMME,ihPerfTag,ihCustom,ihServerToServerDistributor,ihWindowsPerfMon,} ihInterfaceType;
SignedIntegralUTCBias
Used for Get Tag Properties API.BooleanAverageCollectionTime
StringArrayCalculationDependencies
BooleanCollectionDisabled
UnsignedLongArchiveCompressionTimeout
UnsignedLongCollectorCompressionTimeout
BooleanSpikeLogic
BooleanSpikeLogicOverride
BooleanCollectorAbsoluteDeadbanding
DoubleCollectorAbsoluteDeadband
BooleanArchiveAbsoluteDeadbanding
DoubleArchiveAbsoluteDeadband
BooleanStepValue
Type definition is an enumerated type"ihTimeResolution".
{ihSeconds = 0,
SignedIntegralTimeResolution : ihTimeResolution
ihMilliseconds,ihMicroseconds,ihNanoseconds} ihTimeResolution;
BooleanConditionCollectionEnabled
StringConditionCollectionTriggerTag
© 2016 General Electric Company.22
DescriptionPropertyType
Property Name
Type definition is an enumerated type"ihConditionCollectionComparison".
{ihConditionComparisonUndefined = 0,
SignedIntegralConditionCollectionComparison :ihConditionCollectionComparison
ihConditionComparisonEqual,ihConditionComparisonLessThan,ihConditionComparisonLessThanEqual,ihConditionComparisonGreaterThan,ihConditionComparisonGreaterThanEqual,ihConditionComparisonNotEqual} ihConditionCollectionComparison;
StringConditionCollectionCompareValue
BooleanConditionCollectionMarkers
When the Calculation field is used, then two moreconditions are required. Calculation is not a specific
StringCalculation
field for a tag property. If the tag's collector orinterface type is Server-to-server and the Calculationfield is set (not Null), then the field value is set to thesource address.
Used for Get Tag Properties API.BooleanTagId
StringEnumeratedSetName
StringDataStoreName
Long LongDefaultQueryModifiers
StringUserDefinedTypeName
SignedIntegralNumberOfElements
Type definition is an enumerated type"ihTagDataDensity".
{ihDataDensityUndefined = 0,
SignedIntegralDataDensity : ihTagDataDensity
ihDataDensityMinimum = 1,ihDataDensityMedium = 4,ihDataDensityMaximum = 7} ihTagDataDensity;
Type definition is an enumerated type "ihCalcType".
{ihRawTag = 0,
SignedIntegralCalcType : ihTagCalcType
ihAnalyticTag = 1,ihPythonExprTag = 2} ihTagCalcType;
Used for Get Tag Properties API.BooleanHasAlias
23© 2016 General Electric Company.
DescriptionPropertyType
Property Name
Used for Get Tag Properties API.BooleanIsStale
Error Code Definitions
The following table provides the values and definitions for the ErrorCode parameter.
Table 1: Error Code Definitions
Error Code DefinitionError Code Value:
Operation successful.Success = 0
Operation failed.Failed = -1
Operation failed due to timeout.Timeout = -2
Not connected to Historian server.NotConnected = -3
The given collector does not exist on the server.CollectorNotFound = -4
Operation not supported.NotSupported = -5
Attempt to overwrite an existing data sample.DuplicateData = -6
Bad user name or password.InvalidUsername = -7
Insufficient permissions for operation.AccessDenied = -8
Attempted data write too far in the future.WriteInFuture = -9
Attempted data write to an offline archive.WriteArchiveOffline = -10
Attempted data write to a read-only archive.WriteArchiveReadonly = -11
Attempted data write beyond the configured activerange.
WriteOutsideActiveRange = -12
Attempted data write with no available archives.WriteNoArchiveAvailable = -13
The requested tag was not found.InvalidTagname = -14
Number of licensed tags exceeded.LicensedTagCountExceeded = -15
Number of licensed server connections exceeded.LicensedConnectionCountExceeded = -16
Internal license error.InternalLicenseError = -17
No available tag data.NoValue = -18
The given collector namealready exists on the server.DuplicateCollector = -19
Server or feature is not licensed.NotLicensed = -20
Circular reference detected in calculation.CircularReference = -21
Insufficient disk space to perform backup.BackupInsufficientSpace = -22
© 2016 General Electric Company.24
Error Code DefinitionError Code Value:
Operation unsupported due to server version.InvalidServerVersion = -23
Upper limit on query results exceeded.QueryResultSizeExceeded = -24
Attempted data delete outside allowedmodificationinterval.
DeleteOutsideActiveRange = -25
Alarm and Event subsystem unreachable.AlarmArchiverUnavailable = -26
A supplied argument is invalid.ArgumentException = -27
A supplied argument is NULL.ArgumentNullException = -28
A supplied argument is outside the valid range.ArgumentOutOfRangeException = -29
The requested Enumerated Set was not found.InvalidEnumeratedSet = -30
The requested data store was not found.InvalidDataStore = -31
Operation not permitted.NotPermitted = -32
The Custom data type is not supported.InvalidCustomDataType = -33
N/AihSTATUS_EXISTING_USERDEF_REFERENCES = -34
N/AihSTATUS_INVALID_TAGNAME_DELETEDTAG = -35
N/AihSTATUS_INVALID_DHS_NODENAME = -36
N/AihSTATUS_DHS_SERVICE_IN_USE = -37
N/AihSTATUS_DHS_STORAGE_IN_USE = -38
N/AihSTATUS_DHS_TOO_MANY_NODES_IN_MIRROR =-39
N/AihSTATUS_ARCHIVE_IN_SYNC = -40
N/AInvalidArchiveName= -41
Session id is invalid.InvalidSession = 1
Session has expired.SessionExpired = 2
Unknown error, please check server log.UnknownError = 3
No valid client buffer manager.NoValidClientBufferManager= 4
No value in returned data set.NoValueInDataSet = 5
Tag doesn't exist.TagNotExisting = 6
Service call to central buffer server fail.ClientBufferManagerCommunicationError = 7
Tag type is not supported.TagTypeNotSupported=8
Value type doesn't match tag data type.ValueTypeNotMatchTagDataType = 9
Invalid query parameter.InvalidParameter=10
Tag Search Criteria result was more than 5000.TagSearchResultIsHuge = 11
No valid server or historian server name isn't in theserver list.
InvalidHistorianServer=12
25© 2016 General Electric Company.
Historian REST APIs
Overview of the Historian REST APIs
Historian provides the following APIs, which use REST calls to retrieve data and tag information from theHistorian archives.
Important: Port 8443 is used in examples and sample code throughout the e-book. If you copy andpaste the sample code from this document, you must change this port to your installed port.
• Tags List API on page 26: Provides a list of the current tags.• Raw Data API on page 28: Queries raw data using a number of samples or a time range for a list of tags.• Interpolated Data API on page 31: Queries interpolated data for a list of tags.• Current Value API on page 33: Queries the current value data for a list of tags.• Calculated Data API on page 34: Queries calculated data for a list of tags, using a number of samples
or a time range for those tags.• Sampled Data API on page 37: Queries sampled data using a number of samples or a time range for a
list of tags.• Trend Data API on page 39: Queries trend data for a list of tags.• Add Single Tag API on page 41• Add Bulk Tags API on page 42• Update Tag Configuration API on page 44• Get Tag Properties API on page 45• Delete Tag API on page 48
Tags List API
The Tags List API retrieves the qualified tag name list by a given nameMask.
Note: URI format supports asterisks (*) and question marks (?).
GETMETHOD:
https://<historianservername>:8443/historian-rest-api /v1/tags/{nameMask}/{maxNumber}
URI:
https://<historianservername>:8443/historian-rest-api /v1/tags?nameMask=*&maxNumber=100
SAMPLE URI:
curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” https://<nodename>:8443/
SAMPLE cURL COMMAND:
historian-rest-api/v1/tags?nameMask=*&maxNumber=<Number_Of_Tags>
© 2016 General Electric Company.26
Query Parameters
ValuesRequired?DescriptionParameter
StringOptionalTagmask that searches for all tags thatmatch the mask and applies the
nameMask
remaining criteria to retrieve data. Themask can include wildcards, such asasterisks (*).
Integer
0 by default
OptionalMaximumtagnumberprovides the limitwhile 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 isused for the maxNumber.
maxNumber
If a positive number is used, then thatnumber of tags is returned. In addition,an error number of +14 notifies the userthat there aremore than the requestednumber of tags in the system.
Response Parameters
DescriptionRequired?Data TypeParameter
For example, ErrorCode = 0, which means theoperation was successful.
YesNumberErrorCode
For example, NULL.YesStringErrorMessage
Includes the following:YesStringtags
• ALT_SENSOR• tagName1• tagName2
Sample Response
{"ErrorCode":0,"ErrorMessage": null,"tags": [
"ALT_SENSOR","tagName1","tagName2"
]}
27© 2016 General Electric Company.
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 thecount is not zero, then the API service returns the number of raw samples taken beginning from the starttime. If the count is zero, then the service returns the raw samples taken between the start time and theend time.
GET, POSTMETHOD:
URI:https://<historianservername>:8443/historian-rest-api/v1/datapoints/raw/{tagNames}/{start}/{end}/{direction}/{count}
GET
https://<historianservername>:8443/historian-rest-api/v1/datapoints/raw/{start}/{end}/{direction}/{count}
POST
SAMPLE GET URI:Count value is a non-zero positive number, and end time is greaterthan start time.
Raw ByNumber
https://<historianservername>:8443/historian-rest-api/datapoints/raw/tagName1/2013-10-02T11:30:00.111Z/2013-10-02T11:31:11.111Z/0/100
https://<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
The count value equals 0.Raw ByTime
https://<historianservername>:8443/historian-rest-api/datapoints/raw/tagName1/2013-10-02T11:30:00.111Z/2013-10-02T11:31:11.111Z/0/0
https://<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:Count value is a non-zero positive number, and end time is greaterthan start time.
Raw ByNumber
https://<historianservername>:8443/historian-rest-api/datapoints/raw/2013-10-02T11:30:00.111Z/2013-10-02T11:31:11.111Z/0/100
© 2016 General Electric Company.28
https://<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
The count value equals 0.Raw ByTime
https://<historianservername>:8443/historian-rest-api/datapoints/raw/2013-10-02T11:30:00.111Z/2013-10-02T11:31:11.111Z/0/0
https://<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
curl -i -H "Accept: application/json" -H "Authorization:Bearer <TOKEN>” http://<nodename>:8443/ historian-rest-
SAMPLE cURLCOMMAND (GET):[Raw By Number] api/v1/ datapoints/raw/<tagName>/<start time>/<end
time>/<direction>/<count>
curl -i -H "Accept: application/json" -H "Authorization:Bearer <TOKEN>” http://<nodename>:8443/ historian-rest-
SAMPLE cURLCOMMAND (GET):[Raw By Time] api/v1/ datapoints/raw/<tagName>/<start time>/<end
time>/<direction>/0
curl –X POST -i -H "Content-Type: application/json" -H"Accept: application/json" -H "Authorization: Bearer <TO
SAMPLE cURLCOMMAND (POST):[Raw By Number] KEN>” -d “{\”tagNames\”=\”<tagName>\”}” http://<node
name>:8443/ historian-rest-api/v1/ datapoints/raw/<starttime>/<end time>/<direction>/<count>
curl –X POST -i -H "Content-Type: application/json" -H"Accept: application/json" -H "Authorization: Bearer <TO
SAMPLE cURLCOMMAND (POST):[Raw By Time] KEN>” -d “{\”tagNames\”=\”<tagName>\”}” ‘ http://<node
name>:8443/ historian-rest-api/v1/ datapoints/raw?start=<start time>&end=<end time>&direction=<direction>&count=<count>’
Query Parameters
ValuesRequired?DescriptionParameter
StringYesQueries the specified tagnames.
TagNames
DateTimeYesStart time of the query, in ISOdata format (such asYYYY-MM-DDTHH:mm:ss.SSSZ).
Start
DateTimeYesEnd time of the query, in ISOdata format (such asYYYY-MM-DDTHH:mm:ss.SSSZ).
End
29© 2016 General Electric Company.
ValuesRequired?DescriptionParameter
Integer, with a value such as 0.YesSpecifies the direction(Forward or Backward from
Direction
the starting time) of datasampling from the archive.The default value is Forward(0).
Integer, with a value such as 100.YesCount of archive valueswithineach calculation interval.
Count
Response Parameters
DescriptionRequired?Data TypeParameter
For example, 0.YesIntegerErrorCode
For example, NULL.YesStringErrorMessage
The object container for the followingparameters:
YesStringData
DoubleFloat,whichstoresdecimalvalues up to 15 places.
DataType
Value is 0, which means theoperation was successful.
ErrorCode
Example: TagName1.TagName
Provides TimeStamp, Value andQuality for each sample. For
Samples
example, TimeStamp =2013-10-02T11:30:00.111Z, Value= 34.26155, and Quality = 3.
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 }
]
© 2016 General Electric Company.30
}]}
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.
GET, POSTMETHOD:
URI:https://<historianservername>:8443/historian-rest-api/v1/datapoints/interpolated/{tagNames}/{start}/{end}/{count}/{intervalMs}
GET
https://<historianservername>:8443/historian-rest-api/v1/datapoints/interpolated/{start}/{end}/{count}/{intervalMs}
POST
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 GET 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 POST URI:
curl -i -H "Accept: application/json" -H "Authorization:Bearer <TOKEN>” http://<nodename>:8443/ historian-rest-
SAMPLEcURLCOMMAND(GET):
api/v1/ datapoints/interpolated/<tagName>/<starttime>/<end time>/<count>/<intervalMS>
curl -i –X POST -H "Content-Type: application/json" -H"Accept: application/json" -H "Authorization: Bearer
SAMPLEcURLCOMMAND(POST):
<TOKEN>” -d “{\”tagNames\”:\”<tagName>\”}”http://<nodename>:8443/ historian-rest-api/v1/ datapoints/interpolated/<start time>/<endtime>/<count>/<intervalMS>
Query Parameters
ValuesRequired?DescriptionParameter
StringYesQueries the tag namesspecified.
TagName
DateTimeYesStart time of the query, in ISOdata format (such asYYYY-MM-DDTHH:mm:ss.SSSZ).
Start
31© 2016 General Electric Company.
ValuesRequired?DescriptionParameter
DateTimeYesEnd time of the query, in ISOdata format (such asYYYY-MM-DDTHH:mm:ss.SSSZ).
End
Integer, with a value such as 100.YesCount of archive valueswithineach calculation interval.
Count
64-bit signed integer, with a value such as10000.
YesInterval in milliseconds.intervalMS
Response Parameters
DescriptionRequired?Data TypeParameter
For example, 0.YesIntegerErrorCode
For example, NULL.YesStringErrorMessage
The object container for the followingparameters:
YesStringData
DoubleFloat,whichstoresdecimalvalues up to 15 places.
DataType
Value is 0, which means theoperation was successful.
ErrorCode
Example is TagName1.TagName
Provides TimeStamp, Value andQuality for each sample. For
Samples
example, TimeStamp =2013-10-02T11:30:00.111Z, Value= 34.26155, and Quality = 3.
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 }
]
© 2016 General Electric Company.32
}]}
Current Value API
The Current Value API queries the current value data and reads the current values for a list of tags. If thestart time is equal to end time, the requiest returns one sample.
GET, POSTMETHOD:
URI:https://<historianservername>:8443/historian-rest-api/v1/datapoints/raw/{tagNames}/{start}/{end}/{direction}/{count}
GET
https://<historianservername>:8443/historian-rest-api/v1/datapoints/currentvalue
POST
https://<historianservername>:8443/historian-rest-api/v1/datapoints/currentvalue?tagNames=tagName1
SAMPLE GET URI:
https://<historianservername>:8443/historian-rest-api/v1/datapoints/currentvalue
SAMPLE POST URI:
curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” http://<nodename>:8443/ historian-rest-api/v1/ datapoints/currentvalue/<tagName>
SAMPLE cURL COMMAND(GET):
curl -i –X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer
SAMPLE cURL COMMAND(POST):
<TOKEN>” -d “{\”tagNames\”:\”<tagName>\”}”http://<nodename>:8443/ historian-rest-api/v1/ datapoints/currentvalue
Query Parameters
ValuesRequired?DescriptionParameter
StringYesQueries the specified tagnames.
TagNames
Response Parameters
DescriptionRequired?Data TypeParameter
For example, 0.YesIntegerErrorCode
For example, NULL.YesStringErrorMessage
33© 2016 General Electric Company.
DescriptionRequired?Data TypeParameter
The object container for the followingparameters:
YesStringData
DoubleFloat, which storesdecimal values up to 15 places.
DataType
Value is 0, which means theoperation was successful.
ErrorCode
Example is TagName1.TagName
Provides TimeStamp, Value andQuality for each sample. For
Samples
example, TimeStamp =2014-01-01T12:00:00Z, Value =34.26155, and Quality = 3.
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 } ]}]
}
Calculated Data API
The CalculatedData API queries the calculated data for a list of tags. Data can be requested using a numberof samples or a time range for a list of tags. If the count is not zero, the service returns the number of rawsamples beginning from the start time. If the count is zero, the services uses the interval, start time, andend time to calculate the required sample number.
GET, POSTMETHOD:
URI:https://<historianservername>:8443/historian-rest-api/v1/datapoints/calculated/{tag
GET
Names}/{start}/{end}/{calculationMode}/{count}/{intervalMs}
https://<historianservername>:8443/historian-rest-api/v1/datapoints/calculated/{start}/{end}/{calculationMode}/{count}/{intervalMs}
POST
© 2016 General Electric Company.34
SAMPLE GET URI:https://<historianservername>:8443/historian-rest-api/v1/datapoints/calculated/tag
NumberofSamples
Name1/2013-10-02T11:30:00.111Z/2013-10-02T11:31:11.111Z/1/100/1000
https://<historianservername>:8443/historian-rest-api/v1/datapoints/calculated?tag
TimeRange for Listof Tags
Names=tagName1&start=2013-10-02T11:30:00.111Z&end=2013-10-02T11:31:11.111Z&count=100&calculationMode=1&intervalMs=1000
SAMPLE POST URI:https://<historianservername>:8443/historian-rest-api/v1/datapoints/calculated/2013-
Number of Samples
10-02T11:30:00.111Z/2013-10-02T11:31:11.111Z/1/100/1000
https://<historianservername>:8443/historian-rest-api/v1/datapoints/calculat
Time Range for Listof Tags
ed?start=2013-10-02T11:30:00.111Z&end=2013-10-02T11:31:11.111Z&count=100&calculationMode=1&intervalMs=1000
curl -i -H "Accept: application/json" -H "Authorization:Bearer <TOKEN>” http://<nodename>:8843/ historian-rest-
SAMPLE cURLCOMMAND (GET):
api/v1/ datapoints/calculated/<tagName>/<start time>/<endtime>/<count>/<calculation mode>/<intervalMS>
curl -i –X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>”
SAMPLE cURLCOMMAND (POST):
-d “{\”tagNames\”:\”<tagName>\”}” http://<nodename>:8843/historian-rest-api/v1/ datapoints/calculated/<starttime>/<end time>/<count>/<calculationmode>/<intervalMS>
Query Parameters
ValuesRequired?DescriptionParameter
1000000106YesGE identifier for a location.TagNames
DateTimeYesStart time of the query, in ISOdata format (such asYYYY-MM-DDTHH:mm:ss.SSSZ).
Start
DateTimeYesEnd time of the query, in ISOdata format (such asYYYY-MM-DDTHH:mm:ss.SSSZ).
End
Integer, with a value such as 100.YesCount of archive valueswithineach calculation interval.
Count
35© 2016 General Electric Company.
ValuesRequired?DescriptionParameter
Integer, with a value such as 1.YesEnd time in milliseconds.CalculationMode
64-bit signed integer, with a value such as1000.
Interval in milliseconds.IntervalMS
Response Parameters
DescriptionRequired?Data TypeParameter
For example, 0.YesIntegerErrorCode
For example, NULL.YesStringErrorCode
The object container for the followingparameters:
YesStringData
DoubleFloat,whichstoresdecimalvalues up to 15 places.
DataType
Value is 0, which means theoperation was successful.
ErrorCode
Example is TagName1.TagName
Provides TimeStamp, Value andQuality for each sample. For
Samples
example, TimeStamp =2013-10-02T11:30:00.111Z, Value= 34.26155, and Quality = 3.
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 }
]}]
}
© 2016 General Electric Company.36
Sampled Data API
The Sampled Data API queries the sampled data for a list of tags. Data can be requested using a numberof samples or a time range for a list of tags. If the count is not zero, the service returns the number of rawsamples beginning from the start time. If the count is zero, the services uses the interval, start time, andend 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.
GET, POSTMETHOD:
URI:https://<historianservername>:8443/historian-rest-api/v1/datapoints/sampled
GET
https://<historianservername>:8443/historian-rest-api/v1/datapoints/sampled
POST
https://<historianservername>:8443/historian-rest-api/v1/datapoints/sampled?tagNames=tagName1&start=2013-
SAMPLE GET URI:
10-02T11:30:00.111Z&end=2013-10-02T11:31:11.111Z&samplingMode=1&calculationMode=1&direction=0&count=0&intervalMs=1000
https://<historianservername>:8443/historian-rest-api/v1/datapoints/sampled
SAMPLE POST URI:
curl -i -H "Accept: application/json" -H "Authorization:Bearer <TOKEN>” http://<nodename>:8443/ historian-rest-
SAMPLEcURLCOMMAND(GET):
api/v1/ datapoints/sampled/<tagName>/<start time>/<endtime>/<direction>/<count>/<intervalMS>
curl -i –X POST -H "Content-Type: application/json" -H"Accept: application/json" -H "Authorization: Bearer
SAMPLEcURLCOMMAND(POST):
<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
Query Parameters
ValuesRequired?DescriptionParameter
StringYesQueries the tag namesspecified.
TagNames
37© 2016 General Electric Company.
ValuesRequired?DescriptionParameter
DateTimeYesStart time of the query, in ISOdata format (such asYYYY-MM-DDTHH:mm:ss.SSSZ).
Start
DateTimeYesEnd time of the query, in ISOdata format (such asYYYY-MM-DDTHH:mm:ss.SSSZ).
End
Integer, with a value such as 1.OptionalAlso known asSamplingModeType.
SamplingMode
Integer, with a value such as 1.OptionalAlso known asCalculationModeType.
CalculationMode
Integer, with a value such as 0.OptionalSpecifies the direction(Forward or Backward from
Direction
the starting time) of datasampling from the archive.The default value is Forward(0).
Integer, with a value such as 0.OptionalThe count of archive valueswithin each calculationinterval.
Count
64-bit signed integer, with a value such as1000.
OptionalInterval in milliseconds.IntervalMS
Response Parameters
DescriptionRequired?Data TypeParameter
For example, 0.YesIntegerErrorCode
For example, NULL.YesStringErrorCode
The object container for the followingparameters:
YesStringData
DoubleFloat,whichstoresdecimalvalues up to 15 places.
DataType
Value is 0, which means theoperation was successful.
ErrorCode
Example is TagName1.TagName
Provides TimeStamp, Value andQuality for each sample. For
Samples
example, TimeStamp =2013-10-02T11:30:00.111Z, Value= 34.26155, and Quality = 3.
© 2016 General Electric Company.38
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 }
]}]
}
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.
GET, POSTMETHOD:
URI:https://<historianservername>:8443/historian-rest-api /v1/datapoints/trend
GET
https://<historianservername>:8443/historian-rest-api /v1/datapoints/trend
POST
https://<historianservername>:8443/historian-rest-api/v1/datapoints/trend?tagNames=tagName1&start=2013-10-
SAMPLE GET URI:
02T11:30:00.111Z&end=2013-10-02T11:31:11.111Z&samplingMode=1&calculationMode=1&direction=0&count=0&intervalMs=1000
https://<historianservername>:8443/historian-rest-api/v1/datapoints/trend
SAMPLE POST URI:
curl -i -H "Accept: application/json" -H "Authorization:Bearer <TOKEN>” http://<nodename>:8443/ historian-rest-
SAMPLEcURLCOMMAND(GET):
api/v1/ datapoints/trend/<tagName>/<start time>/<endtime>/<samplingMode>/<calculationMode>/<direction>/<count>/<intervalMS>
39© 2016 General Electric Company.
curl -i –X POST -H "Content-Type: application/json" -H"Accept: application/json" -H "Authorization: Bearer
SAMPLEcURLCOMMAND(POST):
<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
Query Parameters
ValuesRequired?DescriptionParameter
StringYesQueries the tag namesspecified.
TagNames
DateTimeYesStart time of the query, in ISOdata format (such asYYYY-MM-DDTHH:mm:ss.SSSZ).
Start
DateTimeYesEnd time of the query, in ISOdata format (such asYYYY-MM-DDTHH:mm:ss.SSSZ).
End
Integer, with a value such as 1.OptionalAlso known asSamplingModeType.
SamplingMode
Integer, with a value such as 1.OptionalAlso known asCalculationModeType.
CalculationMode
Integer, with a value such as 0.OptionalSpecifies the direction(Forward or Backward from
Direction
the starting time) of datasampling from the archive.The default value is Forward(0).
Integer, with a value such as 0.OptionalThe count of archive valueswithin each calculationinterval.
Count
64-bit signed integer, with a value such as1000.
OptionalInterval in milliseconds.IntervalMS
Response Parameters
DescriptionRequired?Data TypeParameter
For example, 0.YesIntegerErrorCode
For example, NULL.YesStringErrorMessage
© 2016 General Electric Company.40
DescriptionRequired?Data TypeParameter
The object container for the followingparameters:
YesStringData
Name of the tag, such asahistfile.Simulation00001.
TagName
Location where tags are beingsearched for.
TagSource
Float, which stores decimal valuesup to 6 places.
DataType
Provides TimeStamp, Value andQuality for each sample. For
Trend
example, TimeStamp =2016-03-15T04:53:17.000Z, Value= 170903.6563, andQuality = True.
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}]}}
Add Single Tag APIThe Add Single Tag API provides the ability to add a new tag to Historian.
For the Add Single Tag API, you can add a new tag to Historian, and the tag name and data type must beprovided in the payload (parameter) of the method. All other tags are optional. If a property is provided, therespective validation is performed at the server end. If the tag exists, then any new properties provided inthe payload are applied to the existing tag.
POSTMETHOD:
https://<historianservername>:8443/historian-rest-api/v1/tags/addtag
URI:
41© 2016 General Electric Company.
https://<historianservername>:8443/historian-rest-api/v1/tags/addtagSAMPLE DELETEURI:
Payload:
{"Name" : "SampleTag","DataType" : 3
}
curl -i -H "Accept: application/json" -i -H "Content-Type:application/json" -H "Authorization: Bearer <TOKEN>” -d “{
SAMPLE cURLCOMMAND:
\”Name\”:\”Sampletag\”,\"DataType\":3}” -X POSThttps://<historianservername>:8443/historian-rest-api/v1/tags/addtag
Query Parameters
ValuesRequired?DescriptionParameter
Multidata types. See PayloadParameter on page 19 for a list of
Yes. "Name" and"DataType" properties
JSONarrayof PropertyNameand PropertyValue.
Payload
tag properties used to update atag configuration.
are required. All otherproperties are optional.
Response Parameters
DescriptionRequired?Data TypeParameter
For example, 0.YesIntegerErrorCode
For example, NULL.YesStringErrorMessage
Sample Payload
{"Name" : "tag1","DataType" : 3 ,"Id": "F34CFE80-7428-41A1-AC67-DB0F3D2E1146"}
Sample Response
{"ErrorCode": 0,"ErrorMessage": null}
Add Bulk Tags APIThe Add Bulk Tags API provides the ability to add new tags to Historian using an array.
© 2016 General Electric Company.42
For the Add Bulk Tags API, you can add new tags to Historian using an array, and the tag names and datatypes must be provided in the payload (parameter) of the method. All other tags are optional. If a propertyis provided, the respective validation is performed at the server end. If the tags exist, then any newpropertiesprovided in the payload are applied to the existing tags. The payload is be an array of tags defined.
POSTMETHOD:
https://<historianservername>:8443/historian-rest-api/v1/tags/addtags
URI:
https://<historianservername>:8443/historian-rest-api/v1/tags/addtagsSAMPLE DELETEURI:
Payload:
[{
"Name" : "SampleTag1","DataType" : 3
},{
"Name" : "SampleTag2","DataType" : 3
}]
curl -i -H "Accept: application/json" -i -H "Content-Type:application/json" -H "Authorization: Bearer <TOKEN>” -d “[{
SAMPLE cURLCOMMAND:
\”Name\”:\”Sampletag1\”}, { \”Name\”:\”Sampletag2\”}]” -XPOST https://<historianservername>:8443/historian-rest-api/v1/tags/addtags
Query Parameters
ValuesRequired?DescriptionParameter
Multidata types. See PayloadParameter on page 19 for a list of
Yes. "Name" and"DataType" properties
JSON array tags withindividual tags of
Payload
tag properties used to update atag configuration.
are required. All otherproperties are optional.
PropertyName andPropertyValue.
Response Parameters
DescriptionExists?Data TypeParameter
Tag name.YesStringTagName
For example, 0.YesIntegerErrorCode
For example, NULL.YesStringErrorMessage
Sample Payload
[{"Name": "tag1",
43© 2016 General Electric Company.
"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": ""
}]
Update Tag Configuration APIYou can use this API to update tag properties.
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.
PUTMETHOD:
https://<historianservername>:8443/historian-rest-api/v1/tags/properties/tagName
URI:
https://<historianservername>:8443/historian-rest-api/v1/tags/properties/tagNameSAMPLE DELETEURI:
Payload:{
"PropertyName" : "PropertyValue"}
curl -i -H "Accept: application/json" -i -H "Content-Type:application/json" -H "Authorization: Bearer <TOKEN>” -d “{
SAMPLE cURLCOMMAND:
\”Description\”:\”SampleDesc\”}” -X PUT https://<historianservername>:8443/historian-rest-api/v1/tags/properties/tagName
© 2016 General Electric Company.44
Query Parameters
ValuesRequired?DescriptionParameter
StringYesTag name for whichproperties need to be set ormodified.
tagName
Multidata types. See Payload Parameter onpage 19 for a list of tag properties used toupdate a tag configuration.
At least onepropertymust beprovided.
JSON array of PropertyNameand PropertyValue.
Payload
Response Parameters
DescriptionRequired?Data TypeParameter
For example, 0.YesIntegerErrorCode
For example, NULL.YesStringErrorMessage
Sample Payload
{"Description" : "Test desc"."CollectionOffset" : 4294967295}
Sample Response
{"ErrorCode": 0,"ErrorMessage": null}
Get Tag Properties APIUse the Get Tags API to retrieve existing tag properties.
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 tagname returns an error.
GET / POSTMETHOD:
https://<historianservername>:8443/historian-rest-api/v1/tags/properties/tagName
This URI returns all tag properties.
URI: (GET)
45© 2016 General Electric Company.
https://<historianservername>:8443/historian-rest-api/v1/tags/properties/tagName
Payload
URI: (POST)
{"PropertyName1" : 1,"PropertyName2" : 1}
https://<historianservername>:8443/historian-rest-api/v1/tags/properties/tagName
SAMPLE GET URI:
https://<historianservername>:8443/historian-rest-api/v1/tags/properties/tagNameSAMPLE POST URI:
Payload:{
"Description" : 1}
curl -i -H "Accept: application/json" -i -H "Content-Type:application/json" -H "Authorization: Bearer <TOKEN>” -X GET
SAMPLE cURL GETCOMMAND:
https://<historianservername>:8443/historian-rest-api/v1/tags/properties/tagName
curl -i -H "Accept: application/json" -i -H "Content-Type:application/json" -H "Authorization: Bearer <TOKEN>” -d “{
SAMPLEcURLPOSTCOMMAND:
\”Description\”: 1}” -X POST https://<historianservername>:8443/historian-rest-api/v1/tags/properties/tagName
Query Parameters
ValuesRequired?DescriptionParameter
StringYesTag name for whichproperties need to beretrieved.
tagName
Multi data types. See Payload Parameteron page 19 for a list of tag properties usedto update a tag configuration.
At least onepropertymust beprovided.
JSON array of PropertyNameand bool (true/false).
Payload
Note: The query payload contains all the tag properties you want returned from the server. In theUpdate Tag Config method, you need to provide the actual tag property value. However, in the Get TagProperties method, you need to provide the property and a value of 1 (true), to allow it to be read fromthe server and returned.
© 2016 General Electric Company.46
Response Parameters
DescriptionRequired?Data TypeParameter
For example, 0.YesIntegerErrorCode
For example, NULL.YesStringErrorMessage
If no error, then the tag name of query isreturned and all requested parameters.
OptionalStringName
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,
47© 2016 General Electric Company.
"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 tagsinterface type is 9 (S2S Collector type) tag.
Delete Tag APIThis API allows a user to remove an existing tag from the Historian server.
The Delete Tag API provides the ability to delete an existing tag from the Historian server.
Its URI format supports question marks (?).
DELETEMETHOD:
https://<historianservername>:8443/historian-rest-api/v1/tags/tagName?{permanentDelete}
URI:
https://<historianservername>:8443/historian-rest-api/v1/tags/tagName?permanentDelete=true
SAMPLE DELETEURI:
curl -i -H "Authorization: Bearer <TOKEN>” -X DELETE https://<historianservername>:8443/historian-rest-api/v1/tags/tagName?permanentDelete=<true|false>
SAMPLE cURLCOMMAND:
Query Parameters
ValuesRequired?DescriptionParameter
StringYesNameof the tag to be deleted.tagName
Boolean, true or falseOptional(false isdefault)
Deletes the tag permanentlyfrom theHistorian server if thevalue passed in is true. If theparameter is not provided,
permanentDelete
© 2016 General Electric Company.48
ValuesRequired?DescriptionParameter
then permanentDelete isassumed to be false.
Response Parameters
DescriptionRequired?Data TypeParameter
For example, ErrorCode=0, which means theoperation was successful.
YesNumberErrorCode
For example, NULL.YesStringErrorMessage
Sample Response
{"ErrorCode": 0,"ErrorMessage": null,}
49© 2016 General Electric Company.