Query Timeseries

In this page you will find the documentation for our IoT platform's timeseries data querying feature. In this resource, we delve into the mechanics of querying timeseries data generated primarily by field devices, such as sensors and meters, but also custom data generated by applications and other sources, such as weather data or forecasts output.

See Data Exchange for information about how to write timeseries data.

Querying data

The default HTTP endpoint for querying timeseries data is

GEThttps://api.apio.network/projects/{`{projectId}`}/telemetry/query?q=JSON_QUERY

Where JSON_QUERY is in the following form:

[{
  "query": {
    "series": [
      "devices/my-device-uuid/temperature",
      "devices/my-device-uuid/humidity"
      ],
    "timeFrom": "2023-01-01T12:00:00.000Z",
    "timeTo": "2023-01-01T14:00:00.000Z"
  }
}]

This payload will query the API for two timeseries, representing the measurements of temperature and humidity generated by the same device, in a two hour period.

The response will be in the following form:

{
    "status": true,
    "data": [
        [
            {
                "name": "devices/my-device-uuid/temperature",
                "data": [
                    [
                        "2023-01-02T12:00:00.000Z",
                        12.14
                    ],
                    [
                        "2023-01-02T12:01:00.000Z",
                        12.98
                    ],
                   ...
                ]
            },
              {
                "name": "devices/my-device-uuid/humidity",
                "data": [
                    [
                        "2023-01-02T12:00:00.000Z",
                        31.4
                    ],
                    [
                        "2023-01-02T12:01:00.000Z",
                        32.5
                    ],
                    ...
                ]
            }
        ]
    ]
}
        
        

With this api we can also combine results from multiple devices:

[{
  "query": {
    "series": [
      "devices/my-device-uuid-1/temperature",
      "devices/my-device-uuid-2/temperature",
      "devices/my-device-uuid-3/humidity"
      ],
    "timeFrom": "2023-01-01T12:00:00.000Z",
    "timeTo": "2023-01-01T14:00:00.000Z"
  }
}]

Multiple queries

We can also run multiple queries across different time intervals:

[{
  "query": {
    "series": [
      "devices/my-device-uuid-1/temperature_avg_quarter",
      "devices/my-device-uuid-2/temperature_avg_quarter"
      ],
    "timeFrom": "2023-01-01T12:00:00.000Z",
    "timeTo": "2023-01-01T14:00:00.000Z"
  }
}, {
  "query": {
    "series": [
      "devices/my-device-uuid-1/temperature_avg_quarter"
      ],
    "timeFrom": "2023-01-02T12:00:00.000Z",
    "timeTo": "2023-01-02T14:00:00.000Z"
  }
}]

The response from the previous query will have one response item for each query item in the input:

{
    "status": true,
    "data": [
        [
            {
                "name": "devices/my-device-uuid-1/temperature_avg_quarter",
                "data": [
                    [
                        "2023-01-02T12:00:00.000Z",
                        12.14
                    ],
                    [
                        "2023-01-02T12:15:00.000Z",
                        12.98
                    ],
                    [
                        "2023-01-02T12:30:00.000Z",
                        13.01
                    ],
                    ...
                ]
            }
        ],
        [
            {
                "name": "devices/my-device-uuid-1/temperature_avg_quarter",
                "data": [
                    [
                        "2023-01-02T12:00:00.000Z",
                        13.54
                    ],
                    [
                        "2023-01-02T12:15:00.000Z",
                        13.90
                    ],
                    [
                        "2023-01-02T12:30:00.000Z",
                        14.01
                    ],
                    ...
                ]
            }
        ]
    ]
}

Other Endpoints

If your client struggles with complex query strings containing JSON, you can use the following POST endpoint and provide the query in the body of the HTTP request.

POSThttps://api.apio.network/projects/{`{projectId}`}/telemetry/query

Retention

Every project will have a data retention policy, that is defined at project setup. When timeseries data points are too old for the retention period, are phased out to cold storage.

These data points can still be queried using the unified api, which reads both hot storage and cold storage.

GEThttps://api.apio.network/projects/{`{projectId}`}/unified/query?q=JSON_QUERY

This group of endpoints has the same behaviour as the default endpoint, but allows to query older data.