3. Retrieving samples for a channel

3. Retrieving samples for a channel
Prev	Appendix B. JSON archive access protocol 1.0	Next

Request

The request URL for retrieving samples for a specific channel has the following form:

          /archive/
          <archive key>
          /samples/
          <channel name>
          ?start=
          <start time-stamp>
          &
          ↪end=
          <end time-stamp>[&count=
          <desired number of samples>][&prettyPrint]

The archive key is the numeric key of the archive as specified in the list of archives (typically 1 ).

The channel name is the name of the channel for which samples are requested. The channel name must be URL encoded so that all special characters (in particular those that have a special meaning in a URL, like the question mark) are encoded with %xx where xx is the hexadecimal character code. When the channel name contains non-ASCII characters, those characters are expected to be specified in UTF-8 encoding.

The start time-stamp specifies the start of the interval for which samples are requested. The time stamp is specified as the number of nanoseconds since epoch (January 1 ^st , 1970, 00:00:00 UTC).

The end time-stamp specifies the end of the interval for which samples are requested. The time stamp is specified as the number of nanoseconds since epoch (January 1 ^st , 1970, 00:00:00 UTC).

The count parameter is optional. If specified, the desired number of samples is a strictly positive number that specifies the number of samples that should be returned. The number of samples returned will usually not match this number exactly. However, if samples with various densities are available, the density which will result in the number of samples closest to the requested number is chosen. If this parameter is not specified, raw samples are used.

If the optional prettyPrint parameter is present, the output is formatted nicely, which can be useful for debugging. Usually, this parameter should be omitted because this will result in a more compact representation, saving bandwidth.

Response

The response is a JSON array, each element being one sample (JSON object). In addition to the samples between the start and the end time-stamp, one sample at or before the start time-stamp and one sample at or after the end time-stamp is returned (if such samples exist at all). This way, the returned data is sufficient for creating a plot covering the whole interval, even if the specified time stamps do not exactly match the time stamps of samples.

Each of the sample objects can have the following fields:

Field name	Internal data type	JSON data type	Description
time	big integer	number (must be in integer format)	time-stamp in nanoseconds since epoch (January 1 ^st , 1970, 00:00:00 UTC)
severity	see below	object	alarm severity
status	string	string	alarm status (might contain additional information about the severity)
quality	string	string	sample quality - one of “Original” or “Interpolated” (not case-sensitive)
metaData	see below	object	meta-data of the sample
type	string	string	sample type - must be one of “double”, “enum”, “long”, “minMaxDouble”, or “string” (not case-sensitive)
value	depends on sample type	array	array of values making up the sample
minimum	double	number or string	minimum value – must be in number format unless it cannot be expressed as a JSON number (e.g. infinity)
maximum	double	number or string	maximum value – must be in number format unless it cannot be expressed as a JSON number (e.g. infinity)

The type , time , severity , status , quality , and value fields are always present. The minimum and maximum fields are only present if the type is minMaxDouble . The type field must always come before the value field.

The quality field indicates whether the sample is a raw sample (“Original”) or a decimated sample (“Interpolated”).

The metaData field may be present for all types except the string type. The format of the meta-data depends on the type (see below).

At places where a number may also be expressed as a JSON string, the use of a string is reserved to cases where the number cannot be represented as a JSON number (infinity and not-a-number). Valid strings are inf , infinity , +inf , +infinity , -inf , -infinity , and nan (all not case-sensitive).

The value is always represented as a JSON array. The type of the array elements depends on the sample type:

Sample type	Element JSON type	Remarks
double	number or string	must be in number format unless it cannot be expressed as a JSON number (e.g. infinity)
enum	number	must be in integer format, numbers outside the interval [-2 ³¹ , 2 ³¹ -1] may be truncated
long	number	must be in integer format, numbers outside the interval [-2 ⁶³ , 2 ⁶³ -1] may be truncated
minMaxDouble	number or string	must be in number format unless it cannot be expressed as a JSON number (e.g. infinity)
string	string

The minMaxDouble type is used for samples that have been aggregates from several raw samples and the minimum and maximum represent the least and the greatest value of any of the original samples. Sample of type minMaxDouble typically have a quality of “Interpolated” because they represent decimated samples.

The severity is a JSON object with the following fields (all mandatory):

Field name	Internal data type	JSON data type	Description
level	string	string	sample severity - one of “OK”, “MINOR”, “MAJOR”, or “INVALID” (all not case-sensitive)
hasValue	boolean	boolean	tells whether the sample has a value (or just signals a condition with a certain severity)

The meta-data is a JSON object. The format depends on the sample type. Samples that are of the string type do not have meta data. Samples that are of the enum type can have meta data in the following format (all fields are mandatory):

Field name	Internal data type	JSON data type	Description
type	string	string	value is always “enum” (not case-sensitive)
states	array of strings	array of strings	labels for the enum states

Samples that are of the double , long , or minMaxDouble type can have meta data in the following format (all fields are mandatory):

Field name	Internal data type	JSON data type	Description
type	string	string	value is always “numeric” (not case-sensitive)
precision	integer	number	number of fractional digits to be displayed, must be in integer format
unit	string	string	engineering units of the value
displayLow	double	number or string	lower display limit – must be in number format unless it cannot be expressed as a JSON number (e.g. infinity)
displayHigh	double	number or string	upper display limit – must be in number format unless it cannot be expressed as a JSON number (e.g. infinity)
warnLow	double	number or string	lower warning limit – must be in number format unless it cannot be expressed as a JSON number (e.g. infinity)
warnHigh	double	number or string	upper warning limit – must be in number format unless it cannot be expressed as a JSON number (e.g. infinity)
alarmLow	double	number or string	lower alarm limit – must be in number format unless it cannot be expressed as a JSON number (e.g. infinity)
alarmHigh	double	number or string	upper alarm limit – must be in number format unless it cannot be expressed as a JSON number (e.g. infinity)

Example

Request:

GET /archive-access/api/1.0/archive/1/samples/testCalc?start=0&
  ↪end=1500000000000000000&prettyPrint HTTP/1.0

Response:

[ {
  "time" : 1468429059824011000,
  "severity" : {
    "level" : "OK",
    "hasValue" : true
  },
  "status" : "NO_ALARM",
  "quality" : "Original",
  "metaData" : {
    "type" : "numeric",
    "precision" : 2,
    "units" : "V",
    "displayLow" : 0.0,
    "displayHigh" : 0.0,
    "warnLow" : "NaN",
    "warnHigh" : 12.0,
    "alarmLow" : "NaN",
    "alarmHigh" : 15.0
  },
  "type" : "double",
  "value" : [ 7.0 ]
}, {
  "time" : 1468429060825564000,
  "severity" : {
    "level" : "MINOR",
    "hasValue" : true
  },
  "status" : "HIGH",
  "quality" : "Original",
  "metaData" : {
    "type" : "numeric",
    "precision" : 2,
    "units" : "V",
    "displayLow" : 0.0,
    "displayHigh" : 0.0,
    "warnLow" : "NaN",
    "warnHigh" : 12.0,
    "alarmLow" : "NaN",
    "alarmHigh" : 15.0
  },
  "type" : "double",
  "value" : [ 12.0 ]
} ]

Prev	Up	Next
2. Searching for channels	Home	Appendix C. Administrative API