VRM JSON Juice API notes (draft)

Introduction

The Juice API can be used to .. . On this page there are usage notes as well as an example. The formal API documentation is found here: https://juice.victronenergy.com/build/apidoc/.

An example PHP file is here: vrm_juice_php_example.

A Wordpress blog that uses the API to show actual solar yield in Watts as well as a complete system status is here: http://lackancottage.co.uk/about-us/off-grid/.

And the source code of the iOS and Android VRM apps, also using the Juice API, are here:

idDataAttribute vs code

When parsing results, do not use the idDataAttribute. Use the code instead.

Formatting values, and adding a unit (ie. V or W)

the API will reply with a format string, usable by many programming languages. For PHP see printf

Juice backend work list

Below is a list of changes that will soon be implemented in the Juice API

Add a few lines to the documentation (https://juice.victronenergy.com/build/apidoc/) to make it clear what the verification_token is for, and how it should (or could?) be used. Same for version and for client_version. What is the functionality behind that? Specify that it should be ‘200.a’, and explain that it is for backwards compatibility in case we need to change the API.
Rename the documentation, now called 'Victron Energy 2.0 Webservice API Specification' to 'VRM JSON Juice API documentation 2.0'.

The documentation does not make clear what the difference is between sites/get_site_attributes and sites/attributes. Perhaps it is possible to add an explanation per function? In that case I think it should be:

sites/attributes: Request one or more attributes from a site, based on idDataAttribute.
sites/get_attributes_by_code: Request one or more attributes from a site, based on DataAttribute code.
sites/get_site_attributes: What is this for?

Add a unit to the formatValueWithUnit example in the documentation, attribute object, so that the difference between that one and the formatValueOnly is more visible.
We need to make it possible for users to request the generated solar energy. That table stores kWh data for several things. Ofcourse we could make it all very nice and customizeable, like we did with the attributes queries, but I think it is better to keep this one simpe. My proposal is to make a new method, sites/get_energy_data. Input is version, sessionid, verification_token, siteid, instance, client_version. Put in the documentation that the value to be put into that instance parameter is always 0. Output is:
```
{
    "data": {
        "energyAttributes": []   -> listofenergyattributes
    },
    "status: { etc. }
}

energyAttribute object:

{
    "code": "ATTR_CODE",
    "instance": 0,
    "total": 1233,
    "formatValueOnly": "%.2F",
    "formatValueWithUnit": "%.2F kWh",
    
}
```
I have left the idDataAttribute out on purpose, since we decided some time ago that all frontend work should use the attribute codes instead.
To many details in an error code are visible, see other email to Rutger.

DISQUS

~~DISQUS~~

Table of Contents