Telemetry API

Telemetry API provides HTTP API to request telemetry.

Get Current Telemetry Values

GET /telemetry/v1/now

Return the latest values of specified telemetry attributes.

Request

Sample request via cURL

$ curl http://enapter-gateway.local/api/telemetry/v1/now -X GET -G \
  -H 'X-Enapter-Auth-Token: {ACCESS_TOKEN}' \
  -d 'devices[123e4567-e89b-12d3-a456-426614174000]=voltage,uptime'

Path Parameters

devicesobjectrequired

The object whose keys are device IDs and values are comma-separated telemetry attributes list.

Response

devicesobject

Object containing successfully requested telemetry attributes. Object keys are the requested device IDs, and values are DeviceTelemetry objects.

DeviceTelemetry is an object whose keys are names of telemetry attributes, and values are the Snapshot objects.

Snapshot.valuestring,number,boolean

Telemetry attribute value.

Snapshot.timestampnumber

Unix timestamp.

errorsarray of errors

Array of errors. See common error format for more details.

Sample response (200 OK)

{
  "devices": {
    "123e4567-e89b-12d3-a456-426614174000": {
      "voltage": {
        "value": 12,
        "timestamp": 1662593249
      },
      "uptime": {
        "value": 12345,
        "timestamp": 1662593249
      }
    }
  }
}

Get Time Series

POST /telemetry/v1/timeseries

Return the time series — a sequence of measurements, ordered in time.

Request

Sample request via cURL

$ curl http://enapter-gateway.local/api/telemetry/v1/timeseries -X POST \
  -H 'X-Enapter-Auth-Token: {ACCESS_TOKEN}' \
  -H 'Accept: text/csv' \
  -d '{
    "from": "2022-10-11T00:00:00Z",
    "to": "2022-10-11T00:01:00Z",
    "granularity": "1s",
    "telemetry": [{
      "device": "123e4567-e89b-12d3-a456-426614174000",
      "attribute": "voltage",
      "aggregation": "avg"
    }]
  }'

Body Parameters

Request body is written in query language based on JSON according to the the schema.

fromnumber, stringrequired

Begin of time frame. Either a number containing Unix timestamp or a string in RFC 3339 format.

tonumber, stringrequired

End of time frame. Either a number containing Unix timestamp or a string in RFC 3339 format.

aggregationstring

Time bucket aggregation function. Can be overridden for each individual telemetry attribute.

Currently supported functions:

• auto — select either avg or last depending on the data type;
• avg — calculate arithmetic mean;
• last — use last known value.

granularityduration string

Time bucket interval. Can be overridden for each individual telemetry attribute.

gap_fillingobject

Gap filling settings, instance of GapFilling object. Can be overridden for each individual telemetry attribute.

GapFilling.methodstring

Gap filling method. Currently the only supported gap filling method is locf — last observation carried forward.

GapFilling.look_aroundduration string

Interval in the past to look for values outside of the time range specified.

telemetryarrayrequired

List of TelemetryAttribute objects, one for each requested telemetry attribute.

Currently, the maximum number of telemetry attributes per request is 10.

TelemetryAttribute.devicestring

Device ID.

TelemetryAttribute.attributestring

Telemetry attribute name, same as specified in the blueprint manifest for this device.

TelemetryAttribute.aggregationstring

Time bucket aggregation function. Overrides global aggregation settings. Required if global aggregation settings are not set.

TelemetryAttribute.granularityduration string

Time bucket interval. Overrides global granularity settings. Required if global granularity settings are not set.

TelemetryAttribute.gap_fillingobject

Gap filling settings. Overrides global gap_filling settings.

Response

Sample response (200 OK)

ts,telemetry=voltage device=123e4567-e89b-12d3-a456-426614174000 aggregation=auto granularity=1s gap_filling_method=none gap_filling_look_around=0s
1665446400,4.3087
1665446410,4.3556
1665446419,4.3712

Successful response is a telemetry data in CSV format. The first row of response is CSV header. The first column is always ts — a Unix timestamp. Other columns contain space-separated list of key=value pairs describing the parameters used to calculate the time series in the column.

Possible header keys:

• telemetry — telemetry attribute name;
• device — device ID;
• aggregation — time bucket aggregation function;
• granularity — time bucket interval;
• gap_filling_method — gap filling method;
• gap_filling_look_around — gap filling interval.

Each row after the first one represents one time series measurement at a specific time from the first column.

The HTTP header Content-Type is text/csv. The HTTP header X-Enapter-Timeseries-Data-Types contains comma-separated list of types for each data column. The first column is always timestamp, so this header describes types starting from the second. Possible types are float, integer, string, boolean.

Sample telemetry data types list (200 OK)

X-Enapter-Timeseries-Data-Types: float,integer,boolean

If error occurred, response contains an array of errors in JSON format, HTTP header Content-Type is application/json. See common error format for more details.

Sample response (400 Bad Request)

{
  "errors": [...]
}

Duration String Format

A duration string is a sequence of decimal numbers, each with optional fraction and a unit suffix, such as 1s, 1.5m or 2h45m. Valid time units are ns (nanosecond), us (microsecond), ms (millisecond), s (second), m (minute), h (hour), d (day), y (year).