VoltStorage API (1.22.0)

Download OpenAPI specification:Download

REST-API for reading and/or manipulating data related to VoltStorage batteries

Authentication

BearerAuth

The bearer token needs to the sent with most requests. A token can be obtained through a login request to /rest/login/password. The token must be passed in the following format:

Authorization: Bearer <token>

Security Scheme Type	HTTP
HTTP Authorization Scheme	bearer
Bearer format	"JWT"

QueryAuth

Fallback authentication scheme if bearer authorization is not possible due to some client requriements. Pass the authorization token in the query string using the key token:

...&token=<token>

Security Scheme Type	API Key
Query parameter name:	token

Password Login

Logs a user in by verifying their email/password combination. Returns a JWT (JSON WebToken, https://jwt.io/) used to authenticate the user to other endpoints.

Authorizations:

Request Body schema: application/json

email required	string <email> User E-Mail address. Case insensitive.
password required	string <password> The password to test. Will never be saved.
validity	number <int64> [ 0 .. 31622400‬ ] Default: 86400 Duration of validity of the token in seconds. Defaults to one day. Maximum: One year

Responses

200

OK - Login successful

400

Bad request - missing parameters or invalid credentials

post /login/password

https://api.voltstorage.com/rest/login/password

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"email": "anybody@example.com",
"password": "Password123!",
"validity": 86400
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

List Products

Fetches a list of products. Only products the authenticated user has access to will be returned.

Authorizations:

BearerAuthQueryAuth

query Parameters

count	integer >= 1 Maximum number of products to return. Useful for pagination.
page	integer >= 1 The page to displayed. The first page is `1`. The page size is specified by `count`. Skips over `count * page` entries before returning data.
q	string Free-text search. Filters the product list by several product attributes, such as the ID, the serial number, the type name, ...
groupId	integer Filters the product list, only returning products belonging to the specified group
installationDate	boolean Filters the product list by only returning installed products (`true`) or non-installed products (`false`)
ids	integer or Array of integers
ownerId	integer Filters the product list by only returning products with a specified owner
sort	string Comma-separated list of product fields to sort the output by. Defaults to ascending sort order, prepend a `-` (minus) sign to a field to sort in descending order. Example: `installationDate,-id` Sorts products by their installationDate (ascending). If two products have been installed on the same day, these products will be returned in descending ID order.

Responses

200

400

Bad Request - Invalid parameters. The response body will contain a more detailed description of what went wrong.

401

Unauthorized - No authorization token was provided. Please send your login token with every request as described in BearerAuth.

403

Forbidden - You lack the appropriate permissions to perform this action or read this data.

get /products

https://api.voltstorage.com/rest/products

Response samples

Content type

application/json

Copy

Expand all Collapse all


[
{"id": 77,
"ownerName": null,
"serialNumber": "AA0024",
"hardwareVersion": "5.4",
"manufacturingDate": "2019-05-21",
"installationDate": null,
"timezone": "Europe/Berlin",
"createdAt": "2019-05-21T08:24:43.357Z",
"updatedAt": "2020-03-23T10:18:37.065Z",
"typeId": 6,
"groupId": 64,
"type": 
{"id": 6,
"name": "VoltStorage SMART",
"startOfProduction": "2018-08-20",
"baseType": "storage"
},
"group": 
{"id": 64,
"ownerId": 1,
"name": "Clustering Test",
"latitude": null,
"longitude": null,
"owner": 
{"id": 1,
"name": "David Bauske",
"email": "david.bauske@voltstorage.com",
"demo": false
}
},
"errors": 
["nonDefaultStrategy"
],
"online": true
}
]

Product Statistics

Provides aggregated statistical data for a product

Authorizations:

BearerAuthQueryAuth

path Parameters

productId

required

integer

ID of the product to export data of

query Parameters

tstart	integer Start of the time range to return statistics for
tend	integer End of the time range to return statistics for
timespan	string Enum: "month" "day" "hour" "year" "lifetime" The time span for each object in the result set

Responses

200

400

Bad Request - Invalid parameters. The response body will contain a more detailed description of what went wrong.

401

Unauthorized - No authorization token was provided. Please send your login token with every request as described in BearerAuth.

403

Forbidden - You lack the appropriate permissions to perform this action or read this data.

get /products/{productId}/stats

https://api.voltstorage.com/rest/products/{productId}/stats

Response samples

Content type

application/json

Copy

Expand all Collapse all


[
{"timespan_start": 1584835200,
"pv-total": 0,
"pv-activity": 0,
"consumption-total": 1538060,
"storage-total-released": 22079844,
"storage-total-stored": 21982919,
"max-temperature": 35.9471,
"own-consumption": 
{"nSamples": 1438,
"value": 0
},
"electrolyte-temp": 
{"nSamples": 1438,
"value": 34.1388342837275
},
"pump-temp": 
{"nSamples": 1438,
"value": 38.67160097357442
},
"dc-capacity": 
{"nSamples": 1438,
"value": 18154876.06536853
},
"ac-capacity": 
{"nSamples": 1438,
"value": 15697997.574408904
},
"dc-efficiency": 
{"nSamples": 1438,
"value": 0.9184715034770791
},
"ac-efficiency": 
{"nSamples": 1438,
"value": 0.7138800556328048
},
"self-sufficiency": 
{"totalWeight": 1538060,
"value": 0.455623577171242
}
}
]

Data Export

Export product data to common data exchange formats - the omnipresent comma-separated values (CSV) format or JavaScript Object Notation (JSON)

Authorizations:

BearerAuthQueryAuth

path Parameters

format

required

string

Enum: "csv" "json"

Selects the data type for the export

query Parameters

productId	integer Database ID of the product to export the data of. Must be provided if `componentId` is omitted.
componentId	integer Database ID of the component to export the data of. Must be provided if `productId` is omitted.
from required	number <double> UNIX-Timestamp (seconds since 1970-01-01T00:00:00Z) of the first data point to return
to	number <double> Default: "The current timestamp" UNIX-Timestamp (seconds since 1970-01-01T00:00:00Z) of the last data point to return
fields	string Comma-separated list of fields to include in the data export. All fields are returned if omitted.
tz	integer UTC-offset in minutes for the exported date format
precision	integer Default: 6 Number of significant digits for all numeric data in the export
tolerance	number <float> Default: 0 Relative tolerance value for data pre-export data processing. Can be used to shrink the export size by omitting small changes in value for all fields. The Ramer-Douglas-Peucker algorithm is used for this simplification. Rule of thumb: `0` - no compression `2` - light compression (~33% data reduction) `5` - normal compression (data still precise enough for most applications, ~45% data reduction) `10` - high compression (~55% data reduction) `20` - aggressive compression (~66% data reduction)
separator	string Default: "," Separation character(s) to use for the exported file. Only relevant for `csv` export format.

Responses

200

400

Bad Request - Invalid parameters. The response body will contain a more detailed description of what went wrong.

401

Unauthorized - No authorization token was provided. Please send your login token with every request as described in BearerAuth.

403

Forbidden - You lack the appropriate permissions to perform this action or read this data.

get /data/export.{format}

https://api.voltstorage.com/rest/data/export.{format}

Response samples

Content type

Copy

sep=,
Time,Power_Grid,Power_Household,inverterPower,Power_PV,Power_Power Electronics,SOC_State of Charge
2020-03-25T12:20:41.562+00:00,-49.8754,815.662,433.105,432.432,433.105,0.611868
2020-03-25T12:20:42.556+00:00,-71.7332,,,,,
2020-03-25T12:20:43.568+00:00,-55.5049,,395.02,,395.02,
2020-03-25T12:20:44.556+00:00,-115.449,,433.105,,433.105,
2020-03-25T12:20:45.556+00:00,-59.1815,,354.98,,354.98,
2020-03-25T12:20:46.556+00:00,-159.164,,433.105,,433.105,
2020-03-25T12:20:47.556+00:00,-63.8346,,315.918,,315.918,
2020-03-25T12:20:48.558+00:00,-43.7003,,273.926,,273.926,0.611709
2020-03-25T12:20:49.556+00:00,-107.55,,315.918,,315.918,0.611693
2020-03-25T12:20:50.556+00:00,-50.5506,,237.061,,237.061,
2020-03-25T12:20:51.556+00:00,-149.313,,313.965,,313.965,
2020-03-25T12:20:52.556+00:00,-53.2505,,196.045,,196.045,
2020-03-25T12:20:53.556+00:00,-152.989,,273.926,,273.926,
2020-03-25T12:20:54.556+00:00,99.0787,,0,,0,
2020-03-25T12:20:55.556+00:00,77.2209,,,,,0.611629
2020-03-25T12:20:56.558+00:00,,,,,,0.611628
2020-03-25T12:21:00.556+00:00,-32.068,404.35,,,,
2020-03-25T12:21:01.556+00:00,-32.3131,404.315,,,,
2020-03-25T12:21:17.556+00:00,-36.2353,,0,,0,
2020-03-25T12:21:18.558+00:00,-14.4772,,,,,
2020-03-25T12:21:19.556+00:00,9.2645,,-45.99,,-45.99,
2020-03-25T12:21:20.556+00:00,-36.9706,,0,,0,
2020-03-25T12:21:27.556+00:00,-38.6866,403.396,,,,
2020-03-25T12:21:28.556+00:00,-78.9317,363.361,,,,
2020-03-25T12:21:29.556+00:00,-79.1768,363.325,,,,
2020-03-25T12:25:06.564+00:00,-139.382,351.129,,490.511,,0.611472