# VRM API v2 Documentation - Victron Energy

[Pages:34]vrmapi/overview

# VRM API v2 Documentation

This document provides an brief overview of available endpoints and their parameters. The API is a basic REST API. The API accepts JSON as request body (not form data, just plain JSON). Use something like Postman to fiddle around with it.

Introduction Base URL Design considerations Rate limiting and error 429 Authentication endpoints

Login Login as demo Logout Installation endpoints About installation timezones Get all installations/sites of a given user Retrieve connected devices (e.g. to get device instance) Retrieve diagnostic data / all current installation data Retrieve tags Download installation data in XLS / CSV format Retrieve energy readings Introduction Get the energy readings for a given site/installation Retrieving aggregated statistics Personal access token endpoints

1. # Introduction

To be able to authenticate to the Victron VRM API it is required you have an active account (the same account can be used as you would normally use for the VRM-dashboard). To login you need a valid email address and password. When the credentials are valid, a web-token will be generated which will then be required for subsequent calls to the api. If the token expires, an error message will be returned, which therefore means you have to request a new token with the original login-credentials.

2. # Base URL

The base URL of the API is:



3. # Design considerations

There are two use cases that you could have in mind when implementing a system that calls this API:

1. To build your own front-end; that uses our database & API as a backend. 2. To replicate the data into your own backend.

1 / 34

vrmapi/overview

The API is not suitable for that last use case; and there is no support offered for such implementations by us either. One of the issues is that you can never know what data you have replicated, and what data not yet. Combined with the backlogging function in the GX devices this means that you'll have to continuously query quite far into the past in order to really make sure to have data replicated. We might some day design a proper replication function; but at the moment there are no such plans and also we will not offer support of such setups; unless the involved directly commercial value is extremely high.

If you really do want to host the data; we recommend to implement your own data transmission system on the GX device. Or change the URL of the existing data-transmission system on the GX device to your own URL. Note that this will (obviously) break all the advanced features such as Remote Firmware updates, Remote Support, Remote Console, and-so-forth.

4. # Rate limiting and error 429

If you receive HTTP error 429 - Too many requests, it means that you have exceeded rate limiter limits. As soon as you hit a rate limit, a Retry-After header with a number of seconds you have to wait to retry is present.

5. # Authentication endpoints

The authentication endpoints include the only endpoints in the API for which no authorization header is required to access them.

5.1. # Login

5.1.1. # Username and password

POST

{ "username": "john@", "password": "secret-passw0rd"

}

Or, if a SMS authentication token is required:

{ "username": "john@", "password": "secret-passw0rd", "sms_token": "12345678"

}

When logging in a token is issued which may be used to authorize further requests by including it in the "XAuthorization" request header as follows:

X-Authorization: Bearer {token}

5.1.2. # Access token When using personal access tokens (accesstokens), you have a token that can authenticate against the VRM API without the need of requesting a bearer token. Authentication with such an access token can be done as following:

2 / 34

vrmapi/overview

X-Authorization: Token

5.2. # Login as demo GET Issues an token for accessing the API as the VRM demo user (userid: 22). The demo user has limited access (not all endpoints work for the demo login, e.g. diagnostics is not working) to a few demo installations.

5.3. # Logout POST Accessing this endpoint with a token set in the Authorization header will blacklist the token at the server side for further use.

6. # Installation endpoints

All installation endpoints are parametrized with an installation id in the URL. In the following examples, 1039 will be used as an example installation id. Authentication is required before accessing these endpoints, see the "Authentication endpoints" section.

6.1. # About installation timezones Installation endpoints all work with unix timestamps as parameters, so they are in UTC. If you want to correct the results based on the timezone of the installation, obtain the timezone of the installation by calling: {idUser}/installations (detailed description below)

The response has a field "timezone": "Africa/Addis_Ababa". This indicates that the timezone in which the installation is located. Use this data to display the unix timestamps in the correct timezone.

6.2. # Get all installations/sites of a given user (Restricted) admins can retrieve installations of all users, dealers can only retrieve installations for the users that are linked to them, normal users can only retrieve their own installations/sites.

NOTE: As a normal user, you cannot retrieve information about the demo installations from the demo user.

Endpoint: {idUser}/installations

Method: GET

The response will be something like this for for example:



{ "success": true, "records": [ { "idSite": 100, "name": "Test installation", "idUser": 1001, "pvMax": 12258,

3 / 34

vrmapi/overview

"reports_enabled": false, "accessLevel": 1, "timezone": "UTC", "owner": true, "geofence": false, "geofenceEnabled": false, "device_icon": "solar" } ] }

If you add an extended=1 parameter to this endpoint, more data which is used on the installation overview of VRM is returned. It does not return all installation data, see the Retrieve diagnostic data / all current installation data call for that.

Endpoint: {idUser}/installations?extended=1

Method: GET

The response will be something like this for example:



{ "success": true, "records": [ { "idSite": 100, "name": "Test installation", "idUser": 1001, "pvMax": 12258, "accessLevel": 1, "timezone": "UTC", "owner": true, "geofence": false, "geofenceEnabled": false, "device_icon": "solar", "alarm": false, "last_timestamp": 1472217903, "tags": [ { "idTag": 41, "name": "ok" } ], "timezone_offset": 7200, "extended": [ { "idDataAttribute": 4, "code": "lt", "description": "Latitude", "formatWithUnit": "%.5F LAT", "rawValue": "52.7237", "textValue": null, "formattedValue": "52.72370 LAT" }, {

4 / 34

vrmapi/overview

"idDataAttribute": 5, "code": "lg", "description": "Longitude", "formatWithUnit": "%.5F LNG", "rawValue": "7.0896", "textValue": null, "formattedValue": "7.08960 LNG" }, { "idDataAttribute": 135, "code": "g2", "description": "Grid L2", "formatWithUnit": "%.0F W", "rawValue": "0", "textValue": null, "formattedValue": "0 W" }, { "idDataAttribute": 136, "code": "g3", "description": "Grid L3", "formatWithUnit": "%.0F W", "rawValue": "0", "textValue": null, "formattedValue": "0 W" }, { "idDataAttribute": 143, "code": "bv", "description": "Battery Voltage (System)", "formatWithUnit": "%.2F V", "rawValue": "54.12", "textValue": null, "formattedValue": "54.12 V" }, { "idDataAttribute": 144, "code": "bs", "description": "Battery State of Charge (System)", "formatWithUnit": "%.1F %%", "rawValue": "76", "textValue": null, "formattedValue": "76.0 %" }, { "idDataAttribute": 147, "code": "bc", "description": "Battery Current (System)", "formatWithUnit": "%.2F A", "rawValue": "17.9", "textValue": null, "formattedValue": "17.90 A" }, { "idDataAttribute": 215, "code": "bst", "description": "Battery state", "formatWithUnit": "%s",

5 / 34

vrmapi/overview

"rawValue": null, "textValue": "charging", "formattedValue": "charging" }, { "rawValue": 8, "formatWithUnit": "%.0F W", "code": "consumption", "description": "Consumption", "textValue": null, "idDataAttribute": null, "formattedValue": "8 W" }, { "rawValue": 0, "formatWithUnit": "%.0F W", "code": "solar_yield", "description": "Solar_yield", "textValue": null, "idDataAttribute": null, "formattedValue": "0 W" }, { "rawValue": 49.0818, "formatWithUnit": "%.0F W", "code": "from_to_grid", "description": "From_to_grid", "textValue": null, "idDataAttribute": null, "formattedValue": "49 W" }, { "rawValue": 0, "formatWithUnit": "", "code": "generator", "description": "Generator", "textValue": null, "idDataAttribute": null, "formattedValue": "" }, { "rawValue": 0, "formatWithUnit": "", "code": "ac_in", "description": "Ac_in", "textValue": null, "idDataAttribute": null, "formattedValue": "" }, { "rawValue": 0, "formatWithUnit": "", "code": "ac_out", "description": "Ac_out", "textValue": null, "idDataAttribute": null, "formattedValue": "" }

6 / 34

vrmapi/overview

}, } ] }

], "current_time": "11:25"

6.3. # Retrieve connected devices (e.g. to get device instance)

Endpoint: {idSite}/system-overview

Sample response:

{ "success":true, "records":{ "devices":[ { "name":"Gateway", "productCode":"", "productName":"Venus GX", "firmwareVersion":"v2.09", "lastConnection":1505459195, "class":"device-gateway", "loggingInterval":60, "lastPowerUpOrRestart":1504551552 }, { "name":"Temperature sensor", "productCode":"", "productName":"a162", "lastConnection":1505459195, "class":null, "instance":23 } ], "unconfigured_devices":false }

}

6.4. # Retrieve diagnostic data / all current installation data This endpoint can be used to retrieve all most recent logged data for a given installation. It can only be accessed if the current logged in user has Full access to the specified installation. Endpoint:

{idSite}/diagnostics?count=1000

Parameters:

count: specifies the maximum number of returned records

Sample response:

7 / 34

vrmapi/overview

{ "success": true, "records": [ { "idSite": 1495, "timestamp": 1497056046, "Device": "Gateway", "instance": 0, "idDataAttribute": 1, "description": "gatewayID", "formatWithUnit": "%s", "dbusServiceType": null, "dbusPath": null, "formattedValue": "Venus", "dataAttributeEnumValues": [ { "nameEnum": "VGR, VGR2 or VER", "valueEnum": 0 }, { "nameEnum": "Venus", "valueEnum": 1 }, { "nameEnum": "Venus", "valueEnum": 2 } ], "id": 1 } ], "num_records": 1

}

6.4.1. # Retrieving energy readings For retrieving increment type data, such as Energy readings.

Device type Gateway Gateway Battery Monitor Battery Monitor Solar Charger System overview System overview System overview System overview System overview

Data type float float float float float float float float float float

Description Network traffic tx Network traffic rx Discharged Energy delta Charged Energy delta User yield delta Grid to battery Grid to consumers PV to battery Gas PV to grid

Code tx rx dH21 dH22 dYU Gb Gc Pb Gu Pg

8 / 34

 ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download