Table of contents


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.


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:

/v2/users/{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.


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:

/v2/users/{idUser}/installations

Method:

GET

The response will be something like this for for example:

/v2/users/3/installations

{
  "success": true,
  "records": [
    {
      "idSite": 100,
      "name": "Test installation",
      "idUser": 1001,
      "pvMax": 12258,
      "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:

/v2/users/{idUser}/installations?extended=1

Method:

GET

The response will be something like this for example:

/v2/users/3/installations?extended=1

{
  "success": true,
  "records": [
    {
        "idSite": 100,
        "name": "Test installation",
        "idUser": 1001,
        "pvMax": 12258,
        "reports_enabled": false,
        "accessLevel": 1,
        "timezone": "UTC",
        "owner": true,
        "geofence": false,
        "geofenceEnabled": false,
        "device_icon": "solar",
        "alarm": false,
        "last_timestamp": 1472217903,
        "num_devices": 1,
        "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"
            },
            {
              "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",
              "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": ""
            }
          ],
          "current_time": "11:25"
      },
    }
  ]
}


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

Endpoint:

/v2/installations/{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
   }
}


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:

/v2/installations/{idSite}/diagnostics?count=1000

Parameters:

Sample response:

{
  "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
}


Retrieving energy readings

For retrieving increment type data, such as Energy readings, see this page.


Retrieving measurement data over a time range

We distinguish between a few types of data. For each type, examples and available endpoints are listed.


Graph measurements

Graphs are returned as series of floats, representing data points which can be plotted directly to a line graph.

GET /v2/installations/1039/widgets/Graph?attributeCodes[]=IV1&attributeCodes[]=IV2&attributeCodes[]=IV3
Returns graph data points for the AC input voltage phase 1-3 for the default instance for the last day.

GET /v2/installations/1039/widgets/Graph?attributeCodes[]=VS&instance=255&start=1451606400&end=1452815999
Returns graph data points for the starter battery voltage for instance 255 for the first 14 days of the year 2016.

All available data attributes can be found here:

List of available attributes

Please note: the interval of the returned unix timestamps is determined automatically, and always starts on the unix timestamp you request. If you want consistent unix timestamps, please use rounded unix timestamps and same time range lengths. This is done to ensure speed of our data backend. In general, a larger time range means bigger intervals.


State changes over a time range

State measurements are a specialized version of the normal measurement data. Instead of series of floats which can be graphed directly, these endpoints return a succession of changes between discrete states.

GET /v2/installations/1039/widgets/VeBusState
Returns state changes for the VE.Bus State for the default instance for the last day.

GET /v2/installations/1039/widgets/MPPTState?instance=255&start=1451606400&end=1452815999
Returns state changes for the MPPT State for instance 255 for the first 14 days of the year 2016.

The available state data endpoints are as follows:

/v2/installations/1039/widgets/MPPTState
/v2/installations/1039/widgets/VeBusState
/v2/installations/1039/widgets/VeBusWarningsAndAlarms


Summary data

Summary data return a simple set of last recorded values. These endpoints thus cannot be parameterized with a unix timestamp.

GET /v2/installations/1039/widgets/BatterySummary
Returns latest recorded values for the Battery Summary for the default instance.

GET /v2/installations/1039/widgets/SolarChargerSummary?instance=255
Returns latest recorded values for the Solar Charger Summary for for instance 255.

The available summary endpoints are as follows:

/v2/installations/1039/widgets/BatterySummary
/v2/installations/1039/widgets/BMSDiagnostics
/v2/installations/1039/widgets/HistoricData
/v2/installations/1039/widgets/IOExtenderInOut
/v2/installations/1039/widgets/LithiumBMS
/v2/installations/1039/widgets/MotorSummary
/v2/installations/1039/widgets/PVInverterStatus
/v2/installations/1039/widgets/SolarChargerSummary
/v2/installations/1039/widgets/Status


Other endpoints

These endpoints return a custom data format.

GET /v2/installations/1039/widgets/Alarm
GET /v2/installations/1039/widgets/GPS
GET /v2/installations/1039/widgets/HoursOfAC


Retrieve tags

GET /v2/installations/1039/tags
Returns all tags for the installation.


Download installation data in XLS / CSV format

This endpoint can be used to retrieve base64 encoded exports of installation data. They are used on VRM when you download your data from the advanced page.

Endpoint:

/v2/installations/{idSite}/data-download?start={start_unix_timestamp}&end={end_unix_timestamp}&format=csv|xls

Method:

GET

The response will be a base64 encoded string which you can read and save as a file (as CSV or XLSX file depending on the format parameter).

Parameters: