Hyper Device Attribute Metrics API v3

This document contains an overview of the Hyper Device Attribute Metrics API that can be used to fetch device attribute metrics.

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 attribute metrics series

GET /sites/{site}/analytics/v3/device_attribute_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 (ISO8601)

The start time of the metrics timeseries. Example:

  • 2022-06-30T12:45:00Z

end_time

string (ISO8601)

The end time of the metrics timeseries.

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]+(m|h|d) or none

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

  • 5s

  • 15m

  • 5h

  • 30d

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.

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,
        "vendor_device_id": string,
      }
    }
  },
  "labels": array[string],
  "series": array[{
    "metric": string,
    "device_id": string,
    "attribute_index": int,
    "values": array[float]
  }]
}

Examples

$ curl -H "Authorization: Bearer ${access_token}" "https://${organization_name}.hyper.systems/api/sites/1/analytics/v3/device_attribute_metrics?start_time=2023-02-13T00:00:00.000Z&end_time=2023-02-17T23:59:59.154Z&metrics=hyper_ambient_temperature,hyper_relative_humidity,hyper_ph&resolution=10d&format=json&metadata=true" | jq

{
  "metadata": {
    "metrics": {
      "hyper_relative_humidity": {
        "unit": "percent",
        "symbol": "%",
        "quantity": "Temperature",
        "name": "Hyper relative humidity"
      },
      "hyper_ph": {
        "name": "Hyper pH"
      },
      "hyper_ambient_temperature": {
        "unit": "degrees Celsius",
        "symbol": "°C",
        "quantity": "Temperature",
        "name": "Hyper ambient temperature"
      }
    },
    "devices": {
      "E8:EB:1B:32:31:B4": {
        "name": "",
        "vendor_device_id": "E8:EB:1B:32:31:B4"
      },
      "36:08:94:9A:04:D4": {
        "name": "",
        "vendor_device_id": "36:08:94:9A:04:D4"
      }
    }
  },
  "labels": [
    "2023-02-12T00:00:00-00:00"
  ],
  "series": [
    {
      "metric": "hyper_ambient_temperature",
      "device_id": "36:08:94:9A:04:D4",
      "attribute_index": 0,
      "values": [
        8.6534505
      ]
    },
    {
      "metric": "hyper_ph",
      "device_id": "E8:EB:1B:32:31:B4",
      "attribute_index": 0,
      "values": [
        0.9595640419060487
      ]
    },
    {
      "metric": "hyper_relative_humidity",
      "device_id": "36:08:94:9A:04:D4",
      "attribute_index": 1,
      "values": [
        22.213393500000006
      ]
    }
  ]
}