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.

Mode Description
NONE No cache used
BOTH Cache and historical interleaved
CACHE_ONLY Only cached values

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.

Parameter Description Default Value
simplifyTolerance Tolerance for use in Simplify algorithm null
simplifyTarget Target number of values to return per data point, auto tolerance null

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.

Period Description
Years date - (periods % year of century)
Months date - (periods % month of year)
Weeks date - (periods % aligned week of year) Where the aligned week of year represents concept of the count of weeks within the period of a year where the weeks are aligned to the start of the year. For example, in a calendar systems with a seven day week, the first aligned-week-of-year starts on day-of-year 1, the second aligned-week starts on day-of-year 8, and so on. Thus, day-of-year values 1 to 7 are in aligned-week 1, while day-of-year values 8 to 14 are in aligned-week 2, and so on.
Days date - (day of year % periods)
Hours date - (hour of day % periods)
Minutes date - (minute of hour % periods)
Seconds date - (second of minute % periods)
Milliseconds date - (millisecond of second % periods)

Numeric Rollups

Rollup Description
NONE No rollup, return raw values
ACCUMULATOR The last value minus the previous value
AVERAGE The start value and all values in the period weighted by time
COUNT The number of sampled or logged values within the period
DELTA The change in point value within the period. 0 values and no start value: NaN, 0 values w/ start value: 0, 1 value with start value could be anything, 1 value with no start value is 0
FIRST The first logged value within the period
INTEGRAL The integral of the values during the period, taking into consideration the start value. The weighted sum of values by their durations
LAST The last logged value within the period
MINIMUM The largest value of any values within the period
MAXIMUM The smallest value of any values within the period
START The value before or exactly at the start of the period
SUM The total of all values within the period, doesn’t count the start value unless the start value occurred exactly at period start

Non Numeric Rollups

Rollup Description
NONE No rollup, return raw values
COUNT The number of sampled or logged values within the period
FIRST The first logged value within the period
LAST The last logged value within the period
START The value before or exactly at the start of the period

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

Parameter Description Default Value
useRendered return value as 'rendered' member false
dateTimeFormat returned timestamp format null
before return values before this time now
timezone java timezone name timezone to use
limit limit the results no limit
useCache interleave cached values into results NONE
simplifyTolerance tolerance for use in Simplify algorithm null
simplifyTarget target number of values to return null

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

Parameter Description Default Value
useRendered return value as 'rendered' member false
dateTimeFormat returned timestamp format null
before return values before this time now
timezone java timezone name timezone to use
limit limit the results no limit
useCache interleave cached values into results NONE
simplifyTolerance tolerance for use in Simplify algorithm null
simplifyTarget target number of values to return null

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

Parameter Description Default Value
useRendered return value as 'rendered' member false
dateTimeFormat returned timestamp format null
before return values before this time now
timezone java timezone name timezone to use
limit limit the results no limit
useCache interleave cached values into results NONE
simplifyTolerance tolerance for use in Simplify algorithm null
simplifyTarget target number of values to return null

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

Parameter Description Default Value
useRendered return value as 'rendered' member false
dateTimeFormat returned timestamp format null
from return values at and after this time now
to return values before this time now
timezone java timezone name timezone to use
limit limit the results no limit
bookend always return values at the to and from times false
useCache interleave cached values into results NONE
simplifyTolerance tolerance for use in Simplify algorithm null
simplifyTarget target number of values to return null

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