Download a CSV file

GET

/download/csv

This endpoint returns data as a CSV file from one or multiple sensors, or sums of sensors for different granularities and time frames.

Using the parameters, the different granularities, time frames, selected fields and sensor IDs can be specified. Additionally, instead of a simple sensor ID, an operation object can be specified to perform calculations with power values. Operation objects can be used to compute sums of power values over multiple sensors. Sums are only calculated over active power (only field "p"). Each sensor in an operation object requires a sign ("POS" / "NEG") allowing for subtraction of individual sensor's power values.

An example operation object looks as follows:

{
  "operation": "SUM",
  "label": "my label",
  "sensor_ids": [
    {
      "sign": "POS",
      "sensor_id": "_id1_"
    },
    {
      "sign": "NEG",
      "sensor_id": "_id2_"
    }
  ]
}

Note that for ten-second values (i.e. granularity="t"), only the fields p, q, and pf are available.

Example Requests:

/download/csv?sensor_ids=["_id1_","_id2_"]&granularity=d&start_time=2023-01-01T00:00:00Z&end_time=2023-01-02T00:00:00Z&fields=["p","i"]

/download/csv?sensor_ids=["_id1_","_id2_",{"operation": "SUM", "label": "my label", "sensor_ids": [{"sign": "POS", "sensor_id": "_id1_"}, {"sign": "NEG", "sensor_id": "_id2_"}]}]&granularity=d&start_time=2021-11-20 00:00:00&end_time=2021-11-21 00:00:00&fields=["u","i","p"]

Limit

The result size is limited depending on the granularity. Note that the limit values apply to the total number of returned lines, not per sensor.

Granularity	Limit
d	3'650 (10 y)
h	4'320 (6 mo)
q	2'880 (1 mo)
m	2'880 (2 d)
ts	4'320 (12 h)

Query Parameters

sensor_idsstringrequired

Example

[
  "_id1_",
  "_id2_",
  {
    "operation": "SUM",
    "label": "My sum",
    "sensor_ids": [
      {
        "sign": "NEG",
        "sensor_id": "_id1_"
      },
      {
        "sign": "NEG",
        "sensor_id": "_id2_"
      }
    ]
  }
]

Description

Array of sensor ids or objects to calculate a sum of power values of different sensors.

granularitystringrequired
Example
h
Description
Specifies the time granularity of the data. Must be one of ["d", "h", "q", "m", "ts"] for day, hour, quarter-hour, minute, or ten-second values.
start_timestringrequired
Example
2023-01-01T00:00:00.000Z
Description
Specify a time frame starting point.
end_timestringrequired
Example
2023-01-02T00:00:00.000Z
Description
Specify a time frame ending point.
fieldsstringrequired
Example
```
[
  "p",
  "u",
  "i"
]
```
Description
Specify the returned fields. Must be in ["p", "q", "s", "u", "i", "pf"] for active power, reactive power, apparent power, voltage, current, and power factor.
utc_offsetnumber
Example
2
Description
Integer specifying the offset from UTC in hours, i.e. specifying the timezone used in start_time and end_time. If not provided, UTC is used. Offsets between -16 and 16 are valid. Shifts due to daylight saving time are not considered. E.g. CEST: utc_offset=2

Header Parameters

Authorizationstringrequired
Example
```
{
  "Authorization": "Bearer {jwt token}"
}
```
Description
Auth header

Responses

200

400Bad Request

object
- namestring
  Example
  BadRequest
  Description
  Error name
- messagestring
  Example
  Data does not match schema
  Description
  Error message
- codenumber
  Example
  400
  Description
  HTTP status code
- classNamestring
  Example
  bad-request
  Description
  Error class name
- datastring
  Description
  Error data
- errorsobject[]
  Example
```
[
  "detailed description of error"
]
```
  Description
  Description of errors

401Unauthorized

object
- namestring
  Example
  NotAuthenticated
  Description
  Error name
- messagestring
  Example
  Not authenticated
  Description
  Error message
- codenumber
  Example
  401
  Description
  HTTP status code
- classNamestring
  Example
  not-authenticated
  Description
  Error class name
- errorsobject
  Description
  Description of errors

403Forbidden

object
- namestring
  Example
  Forbidden
  Description
  Error name
- messagestring
  Example
  Access Forbidden
  Description
  Error message
- codenumber
  Example
  403
  Description
  HTTP status code
- classNamestring
  Example
  forbidden
  Description
  Error class name
- errorsobject
  Description
  Description of errors

curl

curl --request GET \
     --url '/download/csv?sensor_ids=[%22_id1_%22%2C%22_id2_%22%2C{%22operation%22%3A%20%22SUM%22%2C%20%22label%22%3A%20%22My%20sum%22%2C%20%22sensor_ids%22%3A%20[{%22sign%22%3A%20%22NEG%22%2C%20%22sensor_id%22%3A%20%22_id1_%22}%2C%20{%22sign%22%3A%20%22NEG%22%2C%20%22sensor_id%22%3A%20%22_id2_%22}]}]&granularity=h&start_time=2023-01-01T00%3A00%3A00.000Z&end_time=2023-01-02T00%3A00%3A00.000Z&fields=[%22p%22%2C%20%22u%22%2C%20%22i%22]' \
     --header 'accept: application/json' \
     --header 'authorization: {"Authorization":"Bearer {jwt token}"}'

javascript

var myHeaders = new Headers();
myHeaders.append("accept", "application/json");
myHeaders.append("content-type", "application/json");
myHeaders.append("authorization", "{\"Authorization\":\"Bearer {jwt token}\"}");

var requestOptions = {
   method: 'GET',
   headers: myHeaders,
   redirect: 'follow'
};

fetch("/download/csv?sensor_ids=[\"_id1_\",\"_id2_\",{\"operation\": \"SUM\", \"label\": \"My sum\", \"sensor_ids\": [{\"sign\": \"NEG\", \"sensor_id\": \"_id1_\"}, {\"sign\": \"NEG\", \"sensor_id\": \"_id2_\"}]}]&granularity=h&start_time=2023-01-01T00:00:00.000Z&end_time=2023-01-02T00:00:00.000Z&fields=[\"p\", \"u\", \"i\"]", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

ruby

require "uri"
require "json"
require "net/http"

url = URI("/download/csv?sensor_ids=[\"_id1_\",\"_id2_\",{\"operation\": \"SUM\", \"label\": \"My sum\", \"sensor_ids\": [{\"sign\": \"NEG\", \"sensor_id\": \"_id1_\"}, {\"sign\": \"NEG\", \"sensor_id\": \"_id2_\"}]}]&granularity=h&start_time=2023-01-01T00:00:00.000Z&end_time=2023-01-02T00:00:00.000Z&fields=[\"p\", \"u\", \"i\"]")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Get.new(url)
request["accept"] = "application/json"
request["content-type"] = "application/json"
request["authorization"] = "{\"Authorization\":\"Bearer {jwt token}\"}"

response = http.request(request)
puts response.read_body

python

import requests
import json

url = "/download/csv?sensor_ids=[\"_id1_\",\"_id2_\",{\"operation\": \"SUM\", \"label\": \"My sum\", \"sensor_ids\": [{\"sign\": \"NEG\", \"sensor_id\": \"_id1_\"}, {\"sign\": \"NEG\", \"sensor_id\": \"_id2_\"}]}]&granularity=h&start_time=2023-01-01T00:00:00.000Z&end_time=2023-01-02T00:00:00.000Z&fields=[\"p\", \"u\", \"i\"]"

payload = {}
headers = {
   'accept': 'application/json',
   'content-type': 'application/json',
   'authorization': '{"Authorization":"Bearer {jwt token}"}'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

200

400

// Bad Request
{
  "name": "BadRequest",
  "message": "Data does not match schema",
  "code": 400,
  "className": "bad-request",
  "data": "",
  "errors": [
    {}
  ]
}

401

// Unauthorized
{
  "name": "NotAuthenticated",
  "message": "Not authenticated",
  "code": 401,
  "className": "not-authenticated",
  "errors": {}
}

403

// Forbidden
{
  "name": "Forbidden",
  "message": "Access Forbidden",
  "code": 403,
  "className": "forbidden",
  "errors": {}
}