Skip to main content

Device Data

Our Partner API offers the ability to request device information and measurements. We have three endpoints for this purpose. One to request a single measurement, and two to request multiple measurements (different formats).

Getting started​

To get started, you need to have a device reference. You can get this by using the Get Devices endpoint. In the response, you will see a deviceReference for each device, but also the properties (and the associated measurement unit) that are available to request.

Once you have a device reference and the property (or properties) you want to request, you can construct the request.

Requesting a single measurement​

To request a single measurement, you can use the Single Device Measurement endpoint.

// GET /devices/dvc_19RnB3Lyjv2T/measurement?property=soc
{
  "timestamp": 1719474475595,
  "property": "soc",
  "value": 65,
  "unit": "%",
  "reference": "dvc_19RnB3Lyjv2T"
}

Requesting multiple device measurements​

There are two endpoints to request multiple device measurements. One returns the measurements in a list, and the other returns the measurements as a map. You can choose depending on your use case.

As a map

// GET /devices/dvc_19RnB3Lyjv2T/measurements/map?properties=soc,totalEnergyConsumed,totalEnergyProduced
{
  "reference": "dvc_19RnB3Lyjv2T",
  "measurements": {
    "soc": {
      "value": 65,
      "unit": "%"
    },
    "totalEnergyConsumed": {
      "value": 500000,
      "unit": "Wh"
    },
    "totalEnergyProduced": {
      "value": 500000,
      "unit": "Wh"
    }
  }
}

As a list

// GET /devices/dvc_19RnB3Lyjv2T/measurements?properties=soc,totalEnergyConsumed,totalEnergyProduced
{
  "reference": "dvc_19RnB3Lyjv2T",
  "measurements": [
    {
      "timestamp": 1719474475595,
      "property": "soc",
      "value": 65,
      "unit": "%"
    },
    {
      "timestamp": 1719474475595,
      "property": "totalEnergyConsumed",
      "value": 500000,
      "unit": "Wh"
    },
    {
      "timestamp": 1719474475595,
      "property": "totalEnergyProduced",
      "value": 500000,
      "unit": "Wh"
    }
  ]
}

Requesting a time series​

It is also possible to request device measurements as a time series, using the Time Series endpoint. We currently limit the time series request to a single property and only to a maximum of 30 days of data.

The data is returned as an array of timestamps and the corresponding values for the property requested.

// POST /devices/dvc_19RnB3Lyjv2T/measurements/time-series

// Body
{
  "property": "soc",
  "range": {
    "type": "absolute",
    "start": "2024-06-01T00:00:00Z",
    "end": "2024-06-01T23:59:59Z"
  },
  "resolution": {
    "value": 1,
    "unit": "h"
  }
}


// Response
{
  "time": [2024-06-01T00:00:00Z, 2024-06-01T01:00:00Z, 2024-06-01T02:00:00Z, ...],
  "data": [65, 66, 67, ...]
}