JSON Time Series

JSON Time Series (JTS) is a lightweight data-interchange format for time series data. The specification is provided with an MIT license for free use. It has been designed to be highly readable, parsable and extendable.

The JTS document format is natively supported by eagle.io which can be easily imported and exported via the HTTP API.

Note

The Time Series JavaScript library is provided for free and can easily output time series data in JTS format.

Example JTS document:

{
    "docType": "jts",
    "version": "1.0",
    "header": {
        "startTime": "2018-08-16T02:00:00.000Z",
        "endTime": "2018-08-16T02:20:43.000Z",
        "recordCount": 5,
        "columns": {
            "0": {
                "id": "541a5a129bc9b4035f906d70",
                "name": "Temperature",
                "dataType": "NUMBER",
                "renderType": "VALUE",
                "format": "0.###",
                "aggregate": "NONE"
            }
        }
    },
    "data": [
        {
            "ts": "2018-08-16T02:00:39.000Z",
            "f": { "0": {"v": 99, "q": 100, "a": "site maintenance"} }
        },
        {
            "ts": "2018-08-16T02:05:40.000Z",
            "f": { "0": {"v": 28.22 } }
        },
        {
            "ts": "2018-08-16T02:10:41.000Z",
            "f": { "0": {"a": "sensor recalibrated" } }
        },
        {
            "ts": "2018-08-16T02:15:42.000Z",
            "f": { "0": {"v": 29.2, "q": 100 } }
        },
        {
            "ts": "2018-08-16T02:20:43.000Z",
            "f": { "0": {"v": 29.18 } }
        }
    ]
}

JTS Document specification

Attribute Example Description
docType jts Required. Must be ‘jts’
version 1.0 Required. Version ‘1.0’ supported
header   Optional. Object describing document data
data   Required. Array of historic records in chronological order
{
    "docType": "jts",
    "version": "<version>",
    "header": {},
    "data": []
}

Data

The data attribute contains an array of records. Each record contains a ‘ts’ ISO8601 timestamp and an ‘f’ fields object which can contain value, quality and annotation attributes for one or more columns (using column index as key). The records should be sorted chronologically by timestamp.

Record Attribute Example Description
ts 2018-08-16T02:00:00.000Z Required. ISO8601 timestamp of data point(s)
f   Required. Object containing data for 1 or more columns (using column index as key)
v
10.4 Optional. Value of column for the corresponding record timestamp Data type should match dataType option in header
q
100 Optional. Quality code associated with data value for this column
a
site maintenance Optional. Annotation text associated with data point
[
    {
        "ts": "<ts>",
        "f": {
            "0": {"v": 10.4, "q": 100, "a": "site maintenance"},
            "1": {"v": 55}
            "2": {"a": "sensor recalibrated"}
        }
    },
    {
        "ts": "<ts>",
        "f": { "0": {"v": 12, "q": 100}, "1": {"v": 55, "q": 100} }
    }
]

Note

The ‘f’ fields object can be sparsley populated by only including columns that have data for the associated record timestamp.

Data Types

JTS supports both simple and complex data types. Complex data types are always encapsulated in a JSON object with its key prefixed with ‘$’.

When inserting historic data, the data type MUST match the parameter type. For example, TIME data is only accepted on Time parameters. Data that has been exported using renderType ‘STATE’ will always have a String format.

The following data types are supported in the ‘v’ value field of a record column:

Data Type Accepted Parameter Type Format Example
NUMBER Number parameters Number 24.5
TEXT Text parameters String “valve open”
TIME Time parameters {“$time”: “ISO8601”} {“$time”: “2014-08-16T02:00:00Z”}
COORDINATES Locations {“$coords”: [<latitude>, <longitude>]} {“$coords”: [-33.86785, 151.20732]}

Note

The record ‘ts’ field can be expressed as a simple ISO8601 timestamp instead of the complex TIME data type.

PDF HTML Epub Powered by Read The Docs