--- title: Download a CSV file slug: dev/download-a-csv-file docTags: createdAt: 2023-02-23T17:07:09.000Z --- { "id": "TRsEYQyXyUyOKrZR1lhQ0", "type": "api-oas-v2", "data": { "method": "GET", "url": "/download/csv", "name": "Download a CSV file", "description": "

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

\n

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

\n

An example operation object looks as follows:

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

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

\n

Example Requests:

\n

/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\"]

\n

/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\"]

\n

Limit

\n

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

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
GranularityLimit
d3'650 (10 y)
h4'320 (6 mo)
q2'880 (1 mo)
m2'880 (2 d)
ts4'320 (12 h)
", "contentType": "application/json", "request": { "pathParameters": [], "headerParameters": [ { "kind": "required", "name": "Authorization", "type": "string", "description": "Auth header", "example": "{\"Authorization\":\"Bearer {jwt token}\"}" } ], "queryParameters": [ { "kind": "required", "name": "sensor_ids", "type": "string", "description": "Array of sensor ids or objects to calculate a sum of power values of different sensors.", "example": "[\"_id1_\",\"_id2_\",{\"operation\": \"SUM\", \"label\": \"My sum\", \"sensor_ids\": [{\"sign\": \"NEG\", \"sensor_id\": \"_id1_\"}, {\"sign\": \"NEG\", \"sensor_id\": \"_id2_\"}]}]" }, { "kind": "required", "name": "granularity", "type": "string", "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.

", "example": "h" }, { "kind": "required", "name": "start_time", "type": "string", "description": "Specify a time frame starting point.", "example": "2023-01-01T00:00:00.000Z" }, { "kind": "required", "name": "end_time", "type": "string", "description": "Specify a time frame ending point.", "example": "2023-01-02T00:00:00.000Z" }, { "kind": "required", "name": "fields", "type": "string", "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.

", "example": "[\"p\", \"u\", \"i\"]" }, { "kind": "optional", "name": "utc_offset", "type": "number", "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

", "example": 2 } ], "bodyDataParameters": [], "formDataParameters": [], "oAuthParameters": [] }, "responses": [ { "statusCode": "200", "description": "", "jsonExample": "", "isExpanded": true }, { "statusCode": "400", "description": "Bad Request", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "schema": [ { "name": "name", "kind": "optional", "type": "string", "description": "Error name", "example": "BadRequest" }, { "name": "message", "kind": "optional", "type": "string", "description": "Error message", "example": "Data does not match schema" }, { "name": "code", "kind": "optional", "type": "number", "description": "HTTP status code", "example": 400 }, { "name": "className", "kind": "optional", "type": "string", "description": "Error class name", "example": "bad-request" }, { "name": "data", "kind": "optional", "type": "string", "description": "Error data", "example": "" }, { "name": "errors", "kind": "optional", "type": "array", "description": "Description of errors", "example": "[\"detailed description of error\"]", "itemType": "object", "customType": "object[]", "itemExample": "" } ], "isExpanded": true } ] }, { "statusCode": "401", "description": "Unauthorized", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "schema": [ { "name": "name", "kind": "optional", "type": "string", "description": "Error name", "example": "NotAuthenticated" }, { "name": "message", "kind": "optional", "type": "string", "description": "Error message", "example": "Not authenticated" }, { "name": "code", "kind": "optional", "type": "number", "description": "HTTP status code", "example": 401 }, { "name": "className", "kind": "optional", "type": "string", "description": "Error class name", "example": "not-authenticated" }, { "name": "errors", "kind": "optional", "type": "object", "description": "Description of errors", "example": "", "schema": [] } ], "isExpanded": true } ] }, { "statusCode": "403", "description": "Forbidden", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "schema": [ { "name": "name", "kind": "optional", "type": "string", "description": "Error name", "example": "Forbidden" }, { "name": "message", "kind": "optional", "type": "string", "description": "Error message", "example": "Access Forbidden" }, { "name": "code", "kind": "optional", "type": "number", "description": "HTTP status code", "example": 403 }, { "name": "className", "kind": "optional", "type": "string", "description": "Error class name", "example": "forbidden" }, { "name": "errors", "kind": "optional", "type": "object", "description": "Description of errors", "example": "", "schema": [] } ], "isExpanded": true } ] } ], "examples": { "languages": [ { "id": "O0xjOdFqWSX9ma7Uh4uzB", "language": "curl", "label": "cURL", "code": "curl --request GET \\\n --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]' \\\n --header 'accept: application/json' \\\n --header 'authorization: {\"Authorization\":\"Bearer {jwt token}\"}'" }, { "id": "z7zh1BQZGPJN3ehc3lldT", "language": "javascript", "label": "javascript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\nmyHeaders.append(\"authorization\", \"{\\\"Authorization\\\":\\\"Bearer {jwt token}\\\"}\");\n\nvar requestOptions = {\n method: 'GET',\n headers: myHeaders,\n redirect: 'follow'\n};\n\nfetch(\"/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)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "u47lwppRYEMCpcEQtUE6F", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = 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\\\"]\")\n\nhttp = Net::HTTP.new(url.host, url.port);\nrequest = Net::HTTP::Get.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest[\"authorization\"] = \"{\\\"Authorization\\\":\\\"Bearer {jwt token}\\\"}\"\n\nresponse = http.request(request)\nputs response.read_body\n" }, { "id": "JPR00SjBxZmC9Q_XAK-bK", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"/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\\\"]\"\n\npayload = {}\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json',\n 'authorization': '{\"Authorization\":\"Bearer {jwt token}\"}'\n}\n\nresponse = requests.request(\"GET\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "O0xjOdFqWSX9ma7Uh4uzB" }, "results": { "languages": [ { "id": "response-0-200", "language": "200", "code": "" }, { "id": "response-1-400", "language": "400", "code": "// Bad Request\n{\n \"name\": \"BadRequest\",\n \"message\": \"Data does not match schema\",\n \"code\": 400,\n \"className\": \"bad-request\",\n \"data\": \"\",\n \"errors\": [\n {}\n ]\n}" }, { "id": "response-2-401", "language": "401", "code": "// Unauthorized\n{\n \"name\": \"NotAuthenticated\",\n \"message\": \"Not authenticated\",\n \"code\": 401,\n \"className\": \"not-authenticated\",\n \"errors\": {}\n}" }, { "id": "response-3-403", "language": "403", "code": "// Forbidden\n{\n \"name\": \"Forbidden\",\n \"message\": \"Access Forbidden\",\n \"code\": 403,\n \"className\": \"forbidden\",\n \"errors\": {}\n}" } ], "selectedLanguageId": "response-0-200" } }, "children": [ { "id": "3egmZX5QK5Pw9LLnmDK41", "type": "paragraph", "children": [ { "text": "This endpoint returns data as a CSV file from one or multiple sensors, or sums of sensors for different\ngranularities and time frames." } ] }, { "id": "JsR11TP6EsVpxISBXnBjj", "type": "paragraph", "children": [ { "text": "Using the parameters, the different granularities, time frames, selected fields and sensor IDs can be specified.\nAdditionally, instead of a simple sensor ID, an operation object can be specified to perform calculations with power values.\nOperation objects can be used to compute sums of power values over multiple sensors. Sums are only calculated over active power (only field \"p\").\nEach sensor in an operation object requires a sign (\"POS\" / \"NEG\") allowing for subtraction of individual sensor's power values." } ] }, { "id": "kh4n8SAErEbjn5ZKbab23", "type": "paragraph", "children": [ { "text": "An example operation object looks as follows:" } ] }, { "id": "rogxJSXlGuzvkRnVsYPZK", "type": "code-editor-v2", "data": { "selectedLanguageId": "-l9IX7GBAD6frRSL7qjyi", "languages": [ { "id": "-l9IX7GBAD6frRSL7qjyi", "language": "json", "code": "{\n \"operation\": \"SUM\",\n \"label\": \"my label\",\n \"sensor_ids\": [\n {\n \"sign\": \"POS\",\n \"sensor_id\": \"_id1_\"\n },\n {\n \"sign\": \"NEG\",\n \"sensor_id\": \"_id2_\"\n }\n ]\n}\n" } ] }, "children": [ { "text": "" } ] }, { "id": "yk7tAT18GUWhfSp5PXZAa", "type": "paragraph", "children": [ { "text": "Note that for ten-second values (i.e. granularity=\"t\"), only the fields p, q, and pf are available." } ] }, { "id": "DBdIdd1RBCveXMiJ2z-1F", "type": "h3", "children": [ { "text": "Example Requests:" } ], "data": { "autoGeneratedAnchorSlug": "example-requests", "legacyHash": "DBdId" } }, { "id": "O2UfmAeqTlNTnHBGpI83V", "type": "paragraph", "children": [ { "text": "/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\"]", "highlight": true } ] }, { "id": "7RawrMvCyB17Zsaa01h4K", "type": "paragraph", "children": [ { "text": "/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\"]", "highlight": true } ] }, { "id": "TXdvtcxgOjS9taxRBCNL4", "type": "h3", "children": [ { "text": "Limit" } ], "data": { "autoGeneratedAnchorSlug": "limit", "legacyHash": "TXdvt" } }, { "id": "r2xDQhA0jAP2VUHCSHkKR", "type": "paragraph", "children": [ { "text": "The result size is limited depending on the granularity.\nNote that the limit values apply to the total number of returned lines, not per sensor." } ] }, { "id": "ivVb3p41RBYKlO6AL7M_t", "type": "table", "data": { "isTableHeaderOn": true }, "children": [ { "id": "Jiqym0NtvWU1dnrj4wDmU", "type": "table-row", "children": [ { "id": "QqW7RMexAh3QACPsMG-LA", "type": "table-cell", "data": { "align": "left" }, "children": [ { "id": "4wMPqMKfiLd4iTKtw77C2", "type": "paragraph", "children": [ { "text": "Granularity" } ] } ] }, { "id": "abVuiGVDfWRDcMJTvNI8i", "type": "table-cell", "data": { "align": "left" }, "children": [ { "id": "NyUBtPWESVsMK4w-6hsGq", "type": "paragraph", "children": [ { "text": "Limit" } ] } ] } ] }, { "id": "ODc9JRxgdxOa1NZJwjhzU", "type": "table-row", "children": [ { "id": "rji8p02SgpZBsnQqiasit", "type": "table-cell", "data": { "align": "left" }, "children": [ { "id": "1psfy0fTFzB_yCZkWzrnc", "type": "paragraph", "children": [ { "text": "d" } ] } ] }, { "id": "8S381tFKADKl7ELOf-WuL", "type": "table-cell", "data": { "align": "left" }, "children": [ { "id": "FOZtd2GM4K2Hl6WI-UJZu", "type": "paragraph", "children": [ { "text": "3'650 (10 y)" } ] } ] } ] }, { "id": "StfEzbX3iKh-wH1Mjlz28", "type": "table-row", "children": [ { "id": "LSRXNG9nYHK1J3Ac084LI", "type": "table-cell", "data": { "align": "left" }, "children": [ { "id": "6IM89nklWCI22wmQCXl8d", "type": "paragraph", "children": [ { "text": "h" } ] } ] }, { "id": "I1MphV3xSFQQv_uWwfrg1", "type": "table-cell", "data": { "align": "left" }, "children": [ { "id": "prI5XRo2z84bn6BqMtFcn", "type": "paragraph", "children": [ { "text": "4'320 (6 mo)" } ] } ] } ] }, { "id": "PtHBwxDmgbG-JxDzrPJpT", "type": "table-row", "children": [ { "id": "EEb-MheCkyofieTudUHYa", "type": "table-cell", "data": { "align": "left" }, "children": [ { "id": "4td7_0gOkGIO6Nf88mFuY", "type": "paragraph", "children": [ { "text": "q" } ] } ] }, { "id": "7e9aT024vgxppm0OYkBuI", "type": "table-cell", "data": { "align": "left" }, "children": [ { "id": "XleGBk03j_UGy8BOUI5ga", "type": "paragraph", "children": [ { "text": "2'880 (1 mo)" } ] } ] } ] }, { "id": "aP90Gks36q8P9UeYvZ6Qf", "type": "table-row", "children": [ { "id": "lyTk0iCU_Bq-K_wvC8R5n", "type": "table-cell", "data": { "align": "left" }, "children": [ { "id": "zx-PGttx4ea5wVdV5q9WN", "type": "paragraph", "children": [ { "text": "m" } ] } ] }, { "id": "w-MNE5NyLMTRRBt3oDXqW", "type": "table-cell", "data": { "align": "left" }, "children": [ { "id": "wDFEufpltRxPwcTp_nAHx", "type": "paragraph", "children": [ { "text": "2'880 (2 d)" } ] } ] } ] }, { "id": "CRVckmZ8qx319ckgfzKi7", "type": "table-row", "children": [ { "id": "Y-mtSYJ4VllwZtB8D4zQP", "type": "table-cell", "data": { "align": "left" }, "children": [ { "id": "GoR-OT5O_h3O3jLaLtWiH", "type": "paragraph", "children": [ { "text": "ts" } ] } ] }, { "id": "TRvu3naHjd1-BLAZbjnEf", "type": "table-cell", "data": { "align": "left" }, "children": [ { "id": "zeQI4Otj1sgzzg0LAegtB", "type": "paragraph", "children": [ { "text": "4'320 (12 h)" } ] } ] } ] } ] } ] }