Historic¶

Historic data can be extracted or inserted into one or more nodes in a single request. You can also use the Nodes resource to extract or insert data for a single node. Data can be extracted or inserted in JSON (JTS) format.

We recommend you limit the size of requests to 1000 records or less and use HTTP compression whenever possible. If the request or response is too large or exceeds our processing time threshold, the 413 Request Too Large error response will be returned.

Successful extraction requests will result in a 200 OK response with the data returned in the body of the response. Successful insertion requests always result in a 202 Accepted response.

Quick Links

Retrieve historic data from multiple nodes
Retrieve historic chart with multiple nodes
Update historic data for multiple nodes

Retrieve historic data from multiple nodes ¶

Retrieve historic data from multiple nodes in a single request using node id’s. You can use the automatically assigned _id’s or your own customId’s prepended with ‘@’.

Note

Only available for Location and Parameter nodes.

Arguments¶

Argument	Example	Description
format	JSON	Optional - Default is JSON. Data format to return: [JSON, CSV]
startTime	2014-08-16T02:00:00Z	Required. [1] ISO8601 url encoded timestamp
endTime	2014-08-16T02:20:43Z	Required. [1] ISO8601 url encoded timestamp
limit	100	Optional. Maximum number of historic records to be returned
timezone	Etc/UTC	Optional - Default is Etc/UTC. Timezone applied to timestamps. Aggregate interval and baseTime calculations will also use this zone.
timezoneAdjustForDst	FALSE	Optional - Default is FALSE. Flag to indicate if timestamps should be adjusted for DST in selected timezone.
timeQuery	RECORD	Optional - Default is RECORD. Timestamp to query by. MODIFIED will query by modified timestamp (typically used to obtain records changed since a specific timestamp): [RECORD, MODIFIED]
timeFormat	YYYY-MM-DD HH:mm:ss	Optional. Time format to use when format is ‘CSV’.
header	TRUE	Optional - Default is TRUE. Flag to include header
delimiter	,	Optional - Default is ‘,’. Delimiter character to use (in CSV format).
textQualifier	“	Optional - Default is ‘”’. Text qualifier character to use (in CSV format).
quality	NONE	Optional - Default is NONE. Specify how quality should be output (in CSV format): [NONE, DELIMITED_WITH_VALUE, SEPARATE_VALUE]
qualityDelimiter	:	Optional - Default is ‘:’. Delimiter to use when quality is ‘DELIMITED_WITH_VALUE’.
qualityExcluded	BAD,UNCERTAIN	Optional - Default uses account settings Exclude quality. Comma separated list of data point quality types to be excluded: [GOOD, BAD, UNCERTAIN or NONE]
annotation	NONE	Optional - Default is NONE. Specify how annotations should be output (in CSV format): [NONE, DELIMITED_WITH_VALUE, SEPARATE_VALUE]
annotationDelimiter	;	Optional - Default is ‘;’. Delimiter to use when annotation is ‘DELIMITED_WITH_VALUE’.
params	541a5a129bc9b4035f906d70 @sensor_254	Required. Comma delimited list of parameter id’s to include in extraction. Individual parameter options are specified in parentheses.
renderType	VALUE	Optional - Default is parameter displayType. Rendering of value: [VALUE, STATE]
renderFormat	0.000	Optional - Default is node format. Format to apply when renderType is VALUE. ‘#’ must be Url Encoded as ‘%23’.
aggregate	AVERAGE	Optional - Default is NONE (raw). Historic aggregate to apply to extracted data.
baseTime	D	Optional. OPC Base Time required for aggregation.
interval	3H	Optional. OPC Interval required for aggregation.
intervalInclude	PARTIAL	Optional - Default is PARTIAL. COMPLETE will include aggregated values for complete intervals only. PARTIAL will also include values for non-complete intervals: [PARTIAL, COMPLETE]
baselineType	RELATIVE	Optional - Default is ABSOLUTE. Absolute will return data point values unmodified. Relative will subtract the first data point value from all subsequent data point values: [ABSOLUTE, RELATIVE]

[1]	(1, 2) startTime or endTime can be omitted when `limit` is specified.

Include individual parameter arguments in parentheses with key/value separated by colons and multiple arguments semicolon delimited:

params=:id(key:value;key:value),:id

Example with optional parameter arguments:

params=541a5a129bc9b4035f906d71(aggregate:AVERAGE;baseTime:D;interval:3H),@sensor_254

Request¶

GET /api/v1/historic

Response¶

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "docType": "jts",
    "version": "1.0",
    "header": {
        "startTime": "2014-08-16T02:00:00.000Z",
        "endTime": "2014-08-16T02:20:43.000Z",
        "recordCount": 5,
        "columns": {
            "0": {
                "id": "541a5a129bc9b4035f906d70",
                "name": "Temperature",
                "dataType": "NUMBER",
                "aggregate": "NONE"
            }
        }
    },
    "data": [
        {
            "ts": "2014-08-16T02:00:39.000Z",
            "f": { "0": {"v": 28.21 } }
        },
        {
            "ts": "2014-08-16T02:05:40.000Z",
            "f": { "0": {"v": 28.22 } }
        },
        {
            "ts": "2014-08-16T02:10:41.000Z",
            "f": { "0": {"v": 28.7 } }
        },
        {
            "ts": "2014-08-16T02:15:42.000Z",
            "f": { "0": {"v": 29.2 } }
        },
        {
            "ts": "2014-08-16T02:20:43.000Z",
            "f": { "0": {"v": 29.18 } }
        }
    ]
}

Retrieve historic chart with multiple nodes ¶

Retrieve historic chart image with multiple nodes in a single request using node id’s. You can use the automatically assigned _id’s or your own customId’s prepended with ‘@’. Chart images can be returned in PNG, JPG, SVG and PDF format.

The node’s pre-configured (or default) chart settings will be used but you can optionally specify any of the arguments below.

Alternatively use the Nodes resource historic chart endpoint for generating an image from a chart node.

Note

Only available for Parameter nodes.

Arguments¶

Argument	Example	Description
format	PNG	Optional - Default is PNG. Image format to return: [PNG, JPG, SVG, PDF]
width	1200	Optional - Default is 1200. Width of image (png, jpg) in pixels
height	800	Optional - Default is 800. Height of image (png, jpg) in pixels
scale	2	Optional - Default is 1. Multiplier to adjust image dimensions (png, jpg) for higher resolution output: 1-4.
title	My Chart	Optional. Title to display on chart
subtitle	Generated by eagle.io	Optional. Subtitle to display on chart
startTime	2014-08-16T02:00:00Z	Optional. ISO8601 url encoded timestamp
endTime	2014-08-16T02:20:43Z	Optional. ISO8601 url encoded timestamp
timezone	Etc/UTC	Optional - Default is Etc/UTC. Timezone applied to timestamps. Aggregate interval and baseTime calculations will also use this zone
timezoneAdjustForDst	FALSE	Optional - Default is FALSE. Flag to indicate if timestamps should be adjusted for DST in selected timezone
params	541a5a129bc9b4035f906d70 @sensor_254	Required. Comma delimited list of parameter id’s to include in extraction. Individual parameter options are specified in parentheses
renderType	VALUE	Optional - Default is parameter displayType. Rendering of value: [VALUE, STATE]
aggregate	AVERAGE	Optional. Historic aggregate to apply to extracted data
baseTime	D	Optional. OPC Base Time required for aggregation
interval	3H	Optional. OPC Interval required for aggregation
baselineType	RELATIVE	Optional. Absolute will return data point values unmodified. Relative will subtract the first data point value from all subsequent data point values: [ABSOLUTE, RELATIVE]

Include individual parameter arguments in parentheses with key/value separated by colons and multiple arguments semicolon delimited:

params=:id(key:value;key:value),:id

Example with optional parameter arguments:

params=541a5a129bc9b4035f906d71(aggregate:AVERAGE;baseTime:D;interval:3H),@sensor_254,@sensor_255

Request¶

GET /api/v1/historic/chart

Response¶

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

../../_images/api_resources_historic_chart.jpg

Update historic data for multiple nodes ¶

Update historic data for one or more nodes by id’s. You can use the automatically assigned _id’s or your own customId’s prepended with ‘@’.

Note

Only available for Location and Parameter nodes. Required API key permission: Modify

Arguments¶

Argument	Example	Description
format	JSON	Optional - Default is JSON. Data format being inserted: [JSON]. (CSV support coming soon)
writeMode	MERGE_OVERWRITE_EXISTING	Optional - Default is MERGE_OVERWRITE_EXISTING. See all available write mode options.
notifyOn	LATEST_ONLY	Optional - Default is LATEST_ONLY. When to generate events, raise alarms and send notifications: [ALL_NEWER, LATEST_ONLY, NONE]. ALL_NEWER: All events newer than parameter current value. LATEST_ONLY: Latest event newer than parameter current value.
params	541a5a129bc9b4035f906d70 @sensor_254	Required. [2] Comma delimited list of parameter _id’s to include in extraction. Individual parameter options are specified in parentheses.
columnIndex	0	Required. [2] Index of column in data to be associated with this parameter.

[2]	(1, 2) params argument can be omitted if JTS Document contains headers

Include individual parameter arguments in parentheses with key/value separated by colons and multiple arguments semicolon delimited:

params=:id(key:value;key:value),:id

Example with required parameter arguments:

params=541a5a129bc9b4035f906d70(columnIndex:0),@sensor_254(columnIndex:1)

Request¶

PUT /api/v1/historic

{
    "docType": "jts",
    "version": "1.0",
    "data": [
        {
            "ts": "2014-09-17T07:30:00Z",
            "f": { "0": {"v": 25.05 }, "1": {"v": 44.6 } }
        },
        {
            "ts": "2014-09-17T07:40:00Z",
            "f": { "0": {"v": 25.20 } }
        },
        {
            "ts": "2014-09-17T07:50:00Z",
            "f": { "0": {"v": 25.14 }, "1": {"v": 45.21 } }
        }
    ]
}

Response¶

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8

{
    "status": {
        "code": 202,
        "message": "Operation accepted but not yet complete"
    }
}

Historic¶

Retrieve historic data from multiple nodes¶

Arguments¶

Request¶

Response¶

Retrieve historic chart with multiple nodes¶

Arguments¶

Request¶

Response¶

Update historic data for multiple nodes¶

Arguments¶

Request¶

Response¶

Retrieve historic data from multiple nodes ¶

Retrieve historic chart with multiple nodes ¶

Update historic data for multiple nodes ¶