Hyper Device Keyed Metrics API v3

This document contains an overview of the Hyper Device Keyed Metrics API that can be used to fetch metrics aggregated by key.

Authorization

All of the requests to the API must contain a valid authorization token. New API tokens can be generated in the dashboard.

Header Value

Authorization

Bearer $access_token

Get keyed metrics series

GET /sites/{site}/analytics/v3/device_keyed_metrics

This endpoint can be used to obtain aggregated metric values for a list of devices for a given time interval.

Request

The request specifies the time interval, the metrics and the devices to be included in the response. All requests are scoped by a site identifier in the path parameter.

Path Parameters

Name type Description

site

integer

The site identifier. Sites are deployments of independent devices.

Query Parameters

Name type Description

site

integer

The site identifier. Sites are deployments of independent devices.

start_time

string

The start time of the metrics timeseries. Strings mus be in the ISO8601 string format with time offset or ISO8601 requiring the tz parameter. Example:

  • 2021-12-03T09:10:02Z

  • 2021-12-03T09:10:02-12:00

  • 2022-06-30T12:45:00

end_time

string

The end time of the metrics timeseries. Same format as the start_time parameter.

tz

string

The Time Zone Identifier string for the start_time and end_time parameters. Example:

  • Europe/London

  • Australia/Lord_Howe

format

json|csv

The format of the response data.

vendor_device_ids

array[string] or none

The list of Hyper device identifiers to include in the response. The Hyper device identifiers are encoded as MAC addresses, Decimal, IMEI or Serial numbers. If none, all the devices with be shown. Examples:

  • c4:93:00:10:10:f2

  • c4:93:00:10:12:a1

metadata

bool

Determines if the metadata for the metrics and devices should be included. This field is only applicable when the json format is used.

metrics

array[string]

Comma separated list of metric identifiers to include in the response. Examples:

  • aranet_ambient_temperature

  • aranet_relative_humidity

  • aranet_co2

resolution

[0-9]+(seconds|minutes|hours) or (second|minute|hour|day|week|month|quarter|year) or none

The time resolution of the data. If none, the values will not be aggregated. Examples:

  • day

  • 5seconds

  • 15minutes

  • 5hours

  • week

statistics

array[avg|min|max|sum]

The list of deriving statistics to compute for the selected interval. Examples:

  • avg

  • min

  • max

  • sum

missing

nan|null|zero

Determines how missing values are represented.

Timezone handling

The timeseries data produced by the API will respect the timezone information provided by the combination of the start_time, end_time and tz query parameters.

It is required that the time zone information is provided in one of two possible ways:

  1. The time zone identifier information is provided in the tz query parameter as a Time Zone Identifier string. When the tz query parameter is provided the start_time and end_time values MUST NOT include the time zone offset in the ISO8601 format. The start and end time will be localised according to the tz parameter.

  2. The time zone offset is provided in both start_time and end_time query parameters in accordance with the ISO8601 format. The offset MUST be the same for both start_time and end_time, and the tq query parameter MUST NOT be provided in this case.

This ensures that the produced timeseries interval is correctly adjusted for the requested time zone.

All value aggregations performed by the API will take in consideration the provided time zone information. This means that the aggregated values that span multiple days will be computed for dates in the requested time zone.

For daylight saving time (DST) the necessary adjustments will only be performed when the tz query parameter is passed. Proper DST computation requires specific information that is country specific.

Response

Returns a JSON object containing the metric series, time labels and metadata for metrics and devices. Each series object is annotated with the metric and device it belongs too. The interval will contain JSON null values when the data is missing for any metric and device combination. In addition to computing the metrics over time, aggregated statistics for the entire time interval can be computed. The supported statistics are: average, minimum, maximum and sum.

200 Body
{
  "metadata": {
    "metrics": {
      "$metric_id": {
        "name": string,
        "quantity": string,
        "unit": string,
        "symbol": string,
      }
    },
    "devices": {
      "$device_id": {
        "name": string,
        "device_id": string,
      }
    }
  },
  "labels": array[string],
  "series": array[{
    "metric": string,
    "key": string,
    "device_id": string,
    "values": array[float]
  }]
}

Examples

$ curl -H "Authorization: Bearer ${access_token}" "https://${organization_name}.hyper.systems/api/sites/1/analytics/v3/device_keyed_metrics?start_time=2023-02-14T00:00:00&end_time=2023-02-14T23:00:00&tz=Europe/London&metadata=true&resolution=10minutes&metrics=greyparrot_weight,greyparrot_number_of_items"

{
  "metadata": {
    "metrics": {
      "greyparrot_weight": {
        "quantity": "mass",
        "unit": "kilogram",
        "device_schema_id": "39"
      },
      "greyparrot_number_of_items": {
        "quantity": "Count",
        "device_schema_id": "39"
      }
    },
    "devices": {
      "64:4B:F0:12:74:C5": {
        "device_id": "64:4B:F0:12:74:C5"
      },
      "99:AA:BB:CC:DD:11": {
        "device_id": "99:AA:BB:CC:DD:11"
      }
    }
  },
  "labels": [
    "2023-02-08T09:50:00.000+01:00"
  ],
  "series": [
    {
      "metric": "greyparrot_number_of_items",
      "key": "aluminium_can",
      "device_id": "64:4B:F0:12:74:C5",
      "values": [
        2
      ]
    },
    {
      "metric": "greyparrot_number_of_items",
      "key": "aluminium_other",
      "device_id": "64:4B:F0:12:74:C5",
      "values": [
        8
      ]
    },
    {
      "metric": "greyparrot_number_of_items",
      "key": "paper_glossygraphic_coloured",
      "device_id": "64:4B:F0:12:74:C5",
      "values": [
        448
      ]
    },
    {
      "metric": "greyparrot_number_of_items",
      "key": "paper_kraft_brown",
      "device_id": "64:4B:F0:12:74:C5",
      "values": [
        152
      ]
    },
    {
      "metric": "greyparrot_number_of_items",
      "key": "paper_office_white",
      "device_id": "64:4B:F0:12:74:C5",
      "values": [
        416
      ]
    },
    {
      "metric": "greyparrot_number_of_items",
      "key": "aluminium_can",
      "device_id": "99:AA:BB:CC:DD:11",
      "values": [
        1
      ]
    },
    {
      "metric": "greyparrot_weight",
      "key": "paper_kraft_brown",
      "device_id": "64:4B:F0:12:74:C5",
      "values": [
        0.2016
      ]
    },
    {
      "metric": "greyparrot_weight",
      "key": "paper_office_white",
      "device_id": "99:AA:BB:CC:DD:11",
      "values": [
        0.3214
      ]
    }
  ]
}