Overview

The format of the Point Values endpoints has changed in v2, this guide has been created to help developers migrate to the new format.

Content types

Both "text/csv" and "application/json" content types are supported.

URL Parameters

Dates

Dates are IOS formatted strings using the pattern yyyy-MM-dd'T'HH:mm:ss.SSSZ. If no date is supplied for the parameter a time and date of the request's submission will be used.

Example 1: 1994-11-05T08:15:30-05:00 corresponds to November 5, 1994, 8:15:30 am, US Eastern Standard Time.

Example 2: 1994-11-05T13:15:30Z corresponds to the same instant.

More on the pattern here: https://www.w3.org/TR/NOTE-datetime

Timezones

Timezones can be set in 2 ways, by supplying a timezone parameter or by applying an offset to the Date parameter(s). Timezones can be supplied in 3 formats:

1. Offset such as +/-00:00 to 23:59 or Z
2. Zone Offset such as GMT+2, GMT-2, etc
3. Region ID such as US/Hawaii see here for more info

The timezone for the request is set using the following precedence.

1. timezone parameter
2. before or from parameter if supplied
3. to parameter if supplied
4. If no dates are supplied the server timezone is used

Date Format

The dateFormat parameter allows returning dates formatted as strings. By default times are returned as millisecond instants. As above one example is the ISO format yyyy-MM-dd'T'HH:mm:ss.SSSZ. But any format can be used that is supported by the Java DateTimeFormatter.

More on the format here: https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html

Cache

Point values are cached in Mango's memory for a variety of reasons and the size of the cache can be controlled in the data point's settings. Cached values are not necessarily saved to disk but can be duplicated in both places. To access cached values the useCache parameter is supported on all non-rollup endpoints. When using the cache to return values note that saved (non-cache) values override values at the same timestamp.

Bookends

Bookends are only available on time range requests, they are useful when charting data. When bookend=true the value at the from query time and to query times are returned. The first bookend is either the value exactly at from or the value before it. The ending bookend is the last value within the time range. The resulting data will be supplied as the bookend boolean field in the data. If not used or the value is not a bookend, the field is not returned.

Limits

When using limits the results vary based on the endpoint. As a general rule single array responses are limited based on the size of the single array. Multiple array results are limited on each array. So requesting a single array of latest values for many data points with a limit of 10 will return a single array of up to 10 values and these may not necessarily contain values for every point. When requesting the same latest 10 values for the same points as multiple arrays you will get an array of up to 10 values for every point in the request.

Simplify

Simplify is only available on Numeric data points and reduces the number of values returned without losing the peaks and valleys of the data. It uses an enhanced implementation of the Ramer–Douglas–Peucker algorithm. Simplify control works by using 2 parameters on non-rollup endpoints. Simplify can be used to process the data once with a known tolerance level or to auto detect the tolerance based on a desired number of values to be returned. By not providing either of the parameters Simplify will not be done on the values. Auto detection will take a little longer but using a tolerance requries knowing the data better.

Rendering

Point values can be rendered using the data point's renderer settings by setting useRendered=true. The resulting data will be supplied as the rendered String field in the data. If not used the field is not returned.

Rollups

Rollups work with a time period and a time period type. For example you can rollup the data into 30 Day average values. The rollups available for a data point depend on the data type.

Rollup Axioms

1. A starting time is inclusive, an ending time is exclusive
2. Every period starts with the value that existed prior to the period as though timestamped at the start of the period and not before, unless there is a value at the exact start time of the period.
3. Periods with no value prior to the start time have a NULL startValue
4. No value prior or within the period all statistics are NaN except count and sum which are 0 and First (value and time) and Last (value and time) which are NULL
5. No statistic will ever require a value in the next time period
6. The last value added to the statistics (currently the done method) is the last value within the period.
7. The end value is the last value unless it doesn’t exist, in which case it’s the start value
8. Previous value is the latest value prior to the period

Date Truncation

Rollup queries can have thier from and to times truncated to round date/time values using the trucate=true parameter. When truncating a date/time all smaller period types are set to 0. Truncation by the various period types is as follows.

Numeric Rollups

Non Numeric Rollups

Latest Values Endpoints

Latest values for a single point

GET rest/v2/point-values/latest/{xid}

Returns point values in time descending order starting at the first value before the 'before' time.

GET Url Parameters

JSON Response Format

[{
  "timestamp" : 915184800000,
  "value" : 1.0600244013244962,
  "annotation" : "John set this value",
  "rendered" : "1.06 V",
  "cached": true
}]

CSV Response Format

timestamp,value,cached,rendered,annotation
915184800000,1.0600244013244962,true,"1.06 V","John set this value"

Latest values for multiple points as a single array

GET rest/v2/point-values/single-array/latest/{xids}

POST rest/v2/point-values/single-array/latest

Returns point values in time descending order starting at the first value before the 'before' time. The returned values are in a single array with the value field being the xid of the point the value belongs to.

GET Url Parameters

POST Body

{
    "xids": ["point1","point2"],
    "useRendered": true,
    "dateTimeFormat": null,
    "timezone": "US/Hawaii",
    "before": null,
    "limit": 5000,
    "useCache": "BOTH",
    "simplifyTolerance": 0,
    "simplifyTarget": 1000,
}

JSON Response Format

[{
  "timestamp" : 915184800000,
  "point1": {
      "cached": true,
      "value": 1.0,
      "rendered": "1.0V",
      "annotation": "Point1 annotation"
  },
  "point2": {
      "cached": true,
      "value": 2.0,
      "rendered": "2.0V",
      "annotation": "Point2 annotation"
  } 
}]

CSV Response Format

timestamp,point1,point1.cached,point1.rendered,point1.annotation,point2,point2.cached,point2.rendered,point2.annotation
915184800000,1.0,true,"1.0V","Point1 annotation",2.0,true,"2.0V","Point2 annotation"

Latest values for multiple points as a multiple arrays

GET rest/v2/point-values/multiple-arrays/latest/{xids} POST rest/v2/point-values/multiple-arrays/latest/

Returns point values in time descending order starting at the first value before the 'before' time. The returned values for each point are in separate arrays.

GET Url Parameters

POST Body

{
    "xids": ["point1", "point2"],
    "useRendered": true,
    "dateTimeFormat": "yyyy-MM-dd'T'HH:mm:ss.SSSxxx",
    "timezone": "US/Hawaii",
    "before": null,
    "limit": 5,
    "useCache": "BOTH"
}

JSON Response Format

{
    "point1": [{
        "timestamp" : "2017-12-01T05:57:21.969-10:00",
        "cached": true,
        "value": 1.0,
        "rendered": "1.0V",
        "annotation": "Point1 annotation"
    }, ...],
    "point2": [{
        "timestamp" : "2017-12-01T05:57:21.969-10:00",
        "cached": true,
        "value": 2.0,
        "rendered": "2.0V",
        "annotation": "Point2 annotation"
    }, ...] 
}

CSV Response Format

timestamp,xid,value,cached,rendered,annotation
"2017-12-01T05:57:21.969-10:00","point1",1.0,true,"1.0V","Point1 annotation"
"2017-12-01T05:57:21.969-10:00","point2",2.0,true,"2.0V","Point2 annotation"

Time Range Endpoints

Time range queries for values returned in time order. All queries return values in the range from <= timestamps < to.

Time range for single point

GET rest/v2/point-values/time-range/{xid}

GET Url Parameters

JSON Response Format

[{
  "timestamp" : 915184800000,
  "value" : 1.0600244013244962,
  "annotation" : "John set this value",
  "rendered" : "1.06 V",
  "cached": true,
  "bookend": true
}]

CSV Response Format

timestamp,value,bookend,cached,rendered,annotation
915184800000,1.0600244013244962,true,true,"1.06 V","John set this value"

Time range for multiple points as single array

TBD

Time range for multiple points as multiple arrays

TBD

Rollup Endpoints

Rollup endpoints are time range requests that rollup the data.

Rollup values for a single point