bash

Introduction

be4vision Web API enables you to access data of your PV plant portfolio. At the moment there is only a read-only access available.

To access the API you need an be4vision account with the API access enabled. Send your request for an API activated account to service@be4energy.com

Getting Started

Since there are no public endpoints you need an account to start. To get an API account send an email to service@be4energy.com

Once you have an account it is quite simple to get data from an meter for example.

Web API URL

https://api.be4energy.com/v1

Get a login token

POST Request 

 curl 
 -H 'Content-Type:application/json' 
 -d '{"username": "alf", "password": "XXXX"}'
 -X POST 
 https://api.be4energy.com/v1/login/api

200 OK Response 

{
    "message": "Logged in as user alf",
    "access-token": "[TOKEN]"
}

400 BAD REQUEST Response 

{
    "message": {
        "username": "Field can't be blank",
        "password": "Field can't be blank"
    }
}

401 UNAUTHORIZED Response 

{
    "status": 401,
    "message": "Wrong credentials"
}

To query data from our exposed endpoints you need a token for bearer authentication. There are two types of token you can fetch. Usually you will need an API token. This kind of token does not haven an expiration date. However you can invalidate the token by the logout endpoint.

POST https://api.be4energy.com/v1/login/api

FROM DATA

name type mandatory
username string required
password string required

If the query succeeded you will get a token which have to be send as HTTP header for each request you will make.

Authorization: Bearer [TOKEN]

Get PV-Plant IDs

GET Request 

 curl 
 -H 'Authorization: Bearer [TOKEN]'
 -X GET
 https://api.be4energy.com/v1/plant/portfolio

200 OK Response 

{
    "plantids": [
        "P1234456",
        "P1233434"
    ]
}

401 UNAUTHORIZED Response 

{
    "status": 401,
    "message": "Already logged out.",
    "message": "Signature verification failed."
}

With the token you can query the PV-Plant portfolio to see which PV-Plants you have permission to query.

GET https://api.be4energy.com/v1/plant/portfolio

RESPONSE

The response will contain a list of all plant IDs you have permission for with this account.

object type example
plantids array ["P12345","P231233"]




PV-Plant Information

GET Request 

 curl 
 -H 'Authorization: Bearer [TOKEN]'
 -X GET
 https://api.be4energy.com/v1/plant/portfolio/parameter?plantids=P123454

200 OK Response 

{
    "P123454": {
        "plant.location.altitude": "20.5",
        "plant.location.latitude": "42.2323",
        "plant.name": "PVA Berlin",
        "plant.location.longitude": "13.323232",
        "plant.dc.installedpower.total": "100000",
        "plant.inv.total": "3",
        "plant.timezone.identifier": "Europe/Berlin",
        "plant.ac.nominalpower.total": "100000"
    }
}

401 UNAUTHORIZED Response 

{
    "status": 401,
    "message": "No permission for that plant id (2P1602501).",
    "message": "Already logged out.",
    "message": "Signature verification failed.",
}

Get information for each PV-Plant of your account.

GET https://api.be4energy.com/v1/plant/portfolio/parameter

PATH PARAMS

name type mandatory description
plantid string optional get only information of plantid PXXXX
plantids string optional get only information of plantids PXXXX,PXXXXX

RESPONSE

There will be a set of information for each PV-Plant.

object type example unit memo
plant.name string SP Berlin Common name of the PV-Plant
plant.dc.installedpower.total int 100000 Wp
plant.ac.nominalpower.total int 100000 VA
plant.location.longitude float 12.32 decimal
plant.location.latitude float 42.2323 decimal
plant.location.altitude float 20.5 m height above zero in meters
plant.inv.total int 3 count
plant.timezone.identifier string Europe/Berlin

Get devices of the plant

GET Request 

 curl
 -H 'Authorization: Bearer [TOKEN]'
 -X GET
 https://api.be4energy.com/v1/device/meter?plantid=P123454

200 OK Response 

{
    "meter_1": {
        "alias": "EM Main Production",
        "values": {
            "P_AC_TOTAL": {
                "alias": "AC Active Power",
                "unit": "W"
            },
            "E_TOTAL_EXPORT": {
                "alias": "Active Energy: export",
                "unit": "Wh"
            },
            "E_TOTAL_IMPORT": {
                "alias": "Active Energy: import",
                "unit": "Wh"
            }
        }
    }
}

401 UNAUTHORIZED Response 

{
    "status": 401,
    "message": "No permission for that plant id (2P1602501).",
    "message": "Already logged out.",
    "message": "Signature verification failed.",
}

This endpoint returns device and value information. Before you can query data of certain devices and values you will need to query this first. Devices are divided into different categories. At the moment there are the following categories.

The example on the right side will query all energy meter of the PV-Plant.

GET https://api.be4energy.com/v1/device/meter

PATH PARAMS

name type mandatory
plantid string required

Response

object type example
deviceid (object) object ID meter_1
alias (property) property EM Main Production
values (object) object
valueid (object) object ID P_AC_TOTAL

Query data for device

GET Request 

 curl 
 -H 'Authorization: Bearer [TOKEN]'
 -X GET
 https://api.be4energy.com/v1//data/interval?plantid=P123456&
deviceid=inverter_1&
valueid=P_AC&
from=2018-03-01 23:00:00&
to=2018-03-02 23:00:00&
resolution=15min&
aggregate=max

Response Example: 

{
    "plantid": "P1710013",
    "deviceid": "inverter_1",
    "valueid": "P_AC",
    "from": "2018-03-01 23:00:00",
    "to": "2018-03-02 23:00:00",
    "data": {
        "2018-03-01 23:00:00": 0,
        "2018-03-01 23:15:00": 0,
        ...
        "2018-03-02 07:00:00": 2900,
        "2018-03-02 07:15:00": 3107,
        "2018-03-02 07:30:00": 3797,
        ...
        "2018-03-02 22:30:00": null,
        "2018-03-02 22:45:00": null
    }
}

404 NOT FOUND Response 

{
    "status": 404,
    "message": "Could not resolve device id",
    "message": "Could not resolve value id",
}

401 UNAUTHORIZED Response 

{
    "status": 401,
    "message": "permission denied for this aggreagte. Allowed aggreagtes: [avg, min, max, delta]",
    "message": "permission denied for this resolution. Allowed resolution: []",
    "message": "No permission for that plant id (PXXXXXXX).",
    "message": "Already logged out.",
    "message": "Signature verification failed."
}

Now that you have the device ids, you can query data on those devices. Goto Single Value Data for more information.

GET https://api.be4energy.com/v1/data/interval

PATH PARAMS

name type mandatory example memo
plantid string required
deviceid string required
valueid string required
from datetime required 2018-03-01 00:00:00 Date will be interpreted as UTC date
to datetime required 2018-03-01 00:00:00 Date will be interpreted as UTC date
resolution string required 15min
aggregate string required avg min

RESPONSE

In the response you will find the requested object ids such as plantid, deviceid and valueid. This allowed makes sure you know where the data is from.

object type example
plantid (object) object ID P12345
deviceid (object) object ID inverter_1
valueid (object) object ID P_AC
from (property) datetime 2018-03-01 23:00:00
to (property) datetime 2018-03-02 23:00:00

Authentication

Login

POST Request 

 curl 
 -H 'Content-Type:application/json' 
 -d '{"username": "alf", "password": "XXXX"}' 
 https://api.be4energy.com/v1/login/api

200 OK Response 

{
    "message": "Logged in as user alf",
    "access-token": "[TOKEN]"
}

400 BAD REQUEST Response 

{
    "message": {
        "username": "Field can't be blank",
        "password": "Field can't be blank"
    }
}

401 UNAUTHORIZED Response 

{
    "status": 401,
    "message": "Wrong credentials"
}

To get access to the system query an API token. If there are any changes to the account you will have to get a new token. The access token will be invalidated after 10 days, therefore you have to get a new token.

POST https://api.be4energy.com/v1/login/api

FROM DATA

name type mandatory
username string required
password string required

RESPONSE

object type memo
message String If successful it will inform you who has logged in
access-token String API Token which needs to be send with every further request

If the query succeeded you will get a token which have to be send as HTTP header for each request you will make.

HTTP ERRORS

http error codes memo
400 Bad Request if the username or password is missing
403 Forbidden if username or password is wrong

Logout Access Token

POST Request 

curl 
-H 'Authorization: Bearer [TOKEN]'
-X POST
https://api.be4energy.com/v1/logout/access

200 OK Response 

{
    "status": 200,
    "message": "User logout"
}

401 UNAUTHORIZED Response 

{
    "status": 401,
    "message": "Already logged out."
}

Invalidate your access token. After calling this endpoint your token will no longer grant permission to the API.

POST https://api.be4energy.com/v1/logout/access

RESPONSE

object type memo
message String User logout

HTTP ERRORS

http error codes memo
401 UNAUTHORIZED already logged out

Accessing Plant Information

Portfolio

GET Request 

 curl 
 -H 'Authorization: Bearer [TOKEN]'
 -X GET
 https://api.be4energy.com/v1/plant/portfolio

200 OK Response 

{
    "plantids": [
        "P1234456",
        "P1233434"
    ]
}

401 UNAUTHORIZED Response 

{
    "status": 401,
    "message": "Already logged out.",
    "message": "Signature verification failed."
}

Fetch a list of all projects you have access to.

GET https://api.be4energy.com/v1/plant/portfolio

RESPONSE

The response will contain a list of all plant IDs you have permission for with this account.

object type example
plantids array ["P12345","P231233"]

Plant Information

GET Request 

 curl 
 -H 'Authorization: Bearer [TOKEN]'
 -X GET
 https://api.be4energy.com/v1/plant/portfolio/parameter?plantids=P123454

200 OK Response 

{
    "P123454": {
        "plant.location.altitude": "20.5",
        "plant.location.latitude": "42.2323",
        "plant.name": "PVA Berlin",
        "plant.location.longitude": "13.323232",
        "plant.dc.installedpower.total": "100000",
        "plant.inv.total": "3",
        "plant.timezone.identifier": "Europe/Berlin",
        "plant.ac.nominalpower.total": "100000"
    }
}

401 UNAUTHORIZED Response 

{
    "status": 401,
    "message": "No permission for that plant id (2P1602501).",
    "message": "Already logged out.",
    "message": "Signature verification failed."
}

Get information for each PV plant.

GET https://api.be4energy.com/v1/plant/portfolio/parameter

PATH PARAMS

name type mandatory description
plantid string optional get only information of plantid PXXXX
plantids string optional get only information of plantids PXXXX,PXXXXX

RESPONSE

Under each plant id there will be a set of information of the PV plant.

object type example unit memo
plant.name string SP Berlin Common name of the PV plant
plant.dc.installedpower.total int 100000 Wp
plant.ac.nominalpower.total int 100000 VA
plant.location.longitude float 12.32 decimal
plant.location.latitude float 42.2323 decimal
plant.location.altitude float 20.5 m height above zero in meters
plant.inv.total int 3 count
plant.timezone.identifier string Europe/Berlin

Accessing Device Information

Plant

GET Request 

 curl 
 -H 'Authorization: Bearer [TOKEN]'
 -X GET
 https://api.be4energy.com/v1/device/plant?plantid=P123454

200 OK Response 

{
    "plant_device": {
        "values": {
            "INV_P_AC_TOTAL": {
                "alias": "AC Power: Inverter",
                "unit": "W"
            }
        },
        "alias": "Plant Device",
        "commonId": "plant_device"
    }
}

401 UNAUTHORIZED Response 

{
    "status": 401,
    "message": "No permission for that plant id (PXXXXXXX).",
    "message": "Already logged out.",
    "message": "Signature verification failed."
}

Returns value of the plant device. At the moment there is only the total as inverter power available.

GET https://api.be4energy.com/v1/device/plant

PATH PARAMS

name type mandatory
plantid string required

Response

object type example
deviceid (object) object ID plant
alias (property) property Plant Device
values (object) object
valueid (object) object ID INV_P_AC_TOTAL

Battery

GET Request 

 curl 
 -H 'Authorization: Bearer [TOKEN]'
 -X GET
 https://api.be4energy.com/v1/device/battery?plantid=P123454

200 OK Response 

{
    "bat_1": {
        "alias": "Battery 1.1",
        "serial": "XYZ",
        "loggerId": "XXXXXXXXX",
        "values": {
            "BAT_E_DC_CAPACITY": {
                "alias": "Capacity",
                "unit": "Wh",
                "class": "E_DC"
            },
            "BAT_SOC": {
                "alias": "State of Charge",
                "unit": "%",
                "class": "SOC"
            }
        }
    }
}

401 UNAUTHORIZED Response 

{
    "status": 401,
    "message": "No permission for that plant id (PXXXXXXX).",
    "message": "Already logged out.",
    "message": "Signature verification failed."
}

Returns all battery devices of the system and the available values. The API returns only a subset of the values available of the battery devices in be4vision.

GET https://api.be4energy.com/v1/device/battery

PATH PARAMS

name type mandatory
plantid string required

Response

object type example
deviceid (object) object ID bat_1
alias (property) property Battery 01
serial (property) property XYZ
loggerId (property) property XXXXXXXXX
values (object) object
valueid (object) object ID BAT_SOC
value alias (property) property State of Charge
value unit (property) property W

Battery Inverter

GET Request 

 curl 
 -H 'Authorization: Bearer [TOKEN]'
 -X GET
 https://api.be4energy.com/v1/device/batteryinverter?plantid=P123454

200 OK Response 

{
    "bat_1": {
        "alias": "Battery 1.1",
        "serial": "XYZ",
        "loggerId": "XXXXXXXXX",
        "values": {
            "E_TOTAL": {
                "alias": "Energy Yield Total",
                "unit": "Wh"
            },
            "P_AC": {
                "alias": "AC Power",
                "unit": "W"
            }
        }
    }
}

401 UNAUTHORIZED Response 

{
    "status": 401,
    "message": "No permission for that plant id (PXXXXXXX).",
    "message": "Already logged out.",
    "message": "Signature verification failed."
}

Returns all battery inverter of the system and the available values. The API returns only a subset of the values available of the battery inverter in be4vision.

GET https://api.be4energy.com/v1/device/batteryinverter

PATH PARAMS

name type mandatory
plantid string required

Response

object type example
deviceid (object) object ID batinv_1
alias (property) property BatInv 01
serial (property) property XYZ
loggerId (property) property XXXXXXXXX
values (object) object
valueid (object) object ID P_AC_TOTAL
value alias (property) property AC Power
value unit (property) property W

Controller

GET Request 

 curl 
 -H 'Authorization: Bearer [TOKEN]'
 -X GET
 https://api.be4energy.com/v1/device/controller?plantid=P123454

200 OK Response 

{
    "ctrl_1": {
        "alias": "Controller 01",
        "serial": "XYZ",
        "loggerId": "XXXXXXXXX",
        "values": {
            "CTRL_P_SETPOINT_TSO": {
                "alias": "AC Power Setpoint: TSO",
                "unit": "W"
            },
            "CTRL_P_SETPOINT_DM": {
                "alias": "AC Power Setpoint: DM",
                "unit": "W"
            }
        }
    }
}

401 UNAUTHORIZED Response 

{
    "status": 401,
    "message": "No permission for that plant id (PXXXXXXX).",
    "message": "Already logged out.",
    "message": "Signature verification failed."
}

Returns all controller of the system and the available values. The API returns only a subset of the values available of the controller in be4vision.

GET https://api.be4energy.com/v1/device/controller

PATH PARAMS

name type mandatory
plantid string required

Response

object type example
deviceid (object) object ID ctrl_1
alias (property) property PPC 01
serial (property) property XYZ
loggerId (property) property XXXXXXXXX
values (object) object
valueid (object) object ID CTRL_P_SETPOINT_DM
value alias (property) property Setpoint DM
value unit (property) property W

Digital Devices

GET Request 

 curl 
 -H 'Authorization: Bearer [TOKEN]'
 -X GET
 https://api.be4energy.com/v1/device/digital?plantid=P123454

200 OK Response 

{
    "DIGITAL_9": {
        "alias": "Switch",
        "serial": "XYZ",
        "loggerId": "XXXXXXXXX",
        "values": {
            "DIGITAL_1": {
                "alias": "Digital 01",
                "unit": ""
            },
             "DIGITAL_2": {
                "alias": "T01-GAS-Pressure",
                "unit": "",
                "class": "DIGITAL_INPUT"
            },
        }
    }
}

401 UNAUTHORIZED Response 

{
    "status": 401,
    "message": "No permission for that plant id (PXXXXXXX).",
    "message": "Already logged out.",
    "message": "Signature verification failed."
}

Returns all digital IO devices of the system and the available values. The API returns only a subset of the values available of the digital devices in be4vision.

GET https://api.be4energy.com/v1/device/digital

PATH PARAMS

name type mandatory
plantid string required

Response

object type example
deviceid (object) object ID digital_1
alias (property) property Door Switch
serial (property) property XYZ
loggerId (property) property XXXXXXXXX
values (object) object
valueid (object) object ID DIGITAL 01
value alias (property) property Digital 01
value unit (property) property

Energy Storage Controller

GET Request 

 curl 
 -H 'Authorization: Bearer [TOKEN]'
 -X GET
 https://api.be4energy.com/v1/device/energystoragecontroller?plantid=P123454

200 OK Response 

{
    "ssc_1": {
        "alias": "ESC 1.1",
        "serial": "XYZ",
        "loggerId": "XXXXXXXXX",
        "values": {
            "E_TOTAL": {
                "alias": "Energy Yield Total",
                "unit": "Wh"
            },
            "P_AC": {
                "alias": "AC Power",
                "unit": "W"
            }
        }
    }
}

401 UNAUTHORIZED Response 

{
    "status": 401,
    "message": "No permission for that plant id (PXXXXXXX).",
    "message": "Already logged out.",
    "message": "Signature verification failed."
}

Returns all energy storage controller of the system and the available values. The API returns only a subset of the values available of the energy storage controller in be4vision.

GET https://api.be4energy.com/v1/device/energystoragecontroller

PATH PARAMS

name type mandatory
plantid string required

Response

object type example
deviceid (object) object ID inverter_1
alias (property) property BatInv 01
serial (property) property XYZ
loggerId (property) property XXXXXXXXX
values (object) object
valueid (object) object ID P_AC_TOTAL
value alias (property) property AC Power
value unit (property) property W

Inverter

GET Request 

 curl 
 -H 'Authorization: Bearer [TOKEN]'
 -X GET
 https://api.be4energy.com/v1/device/inverter?plantid=P123454

200 OK Response 

{
    "inverter_1": {
        "alias": "Inv 1.1",
        "serial": "XYZ",
        "loggerId": "XXXXXXXXX",
        "values": {
            "E_TOTAL": {
                "alias": "Energy Yield Total",
                "unit": "Wh"
            },
            "P_AC": {
                "alias": "AC Power",
                "unit": "W"
            }
        }
    }
}

401 UNAUTHORIZED Response 

{
    "status": 401,
    "message": "No permission for that plant id (PXXXXXXX).",
    "message": "Already logged out.",
    "message": "Signature verification failed."
}

Returns all inverters of the system and the available values. The API returns only a subset of the values available of the inverter in be4vision.

GET https://api.be4energy.com/v1/device/inverter

PATH PARAMS

name type mandatory
plantid string required

Response

object type example
deviceid (object) object ID inverter_1
alias (property) property Inv 01
serial (property) property XYZ
loggerId (property) property XXXXXXXXX
values (object) object
valueid (object) object ID P_AC_TOTAL
value alias (property) property AC Power
value unit (property) property W

Meteo

GET Request 

 curl 
 -H 'Authorization: Bearer [TOKEN]'
 -X GET
 https://api.be4energy.com/v1/device/meteo?plantid=P123454

200 OK Response 

{
    "meteo_5": {
        "alias": "TS01 - Pyr-tilt-T",
        "values": {
            "RAD_P": {
                "alias": "Radiation Power",
                "unit": "W/m²"
            }
        }
    },
    "meteo_7": {
        "alias": "TS01 - T-a",
        "values": {
            "T_A": {
                "alias": "Temperature",
                "unit": "°C"
            }
        }
    }
}

401 UNAUTHORIZED Response 

{
    "status": 401,
    "message": "No permission for that plant id (PXXXXXXX).",
    "message": "Already logged out.",
    "message": "Signature verification failed."
}

Returns all meteo devices of the system and the available values.

GET https://api.be4energy.com/v1/device/meteo

PATH PARAMS

name type mandatory
plantid string required

Response

object type example
deviceid (object) object ID meteo_1
alias (property) property Radiation 01
serial (property) property XYZ
loggerId (property) property XXXXXXXXX
values (object) object
valueid (object) object ID RAD_P
value alias (property) property Radiation Power
value unit (property) property °C

Meter

GET Request 

 curl
 -H 'Authorization: Bearer [TOKEN]'
 -X GET
 https://api.be4energy.com/v1/device/meter?plantid=P123454

200 OK Response 

{
    "meter_1": {
        "alias": "Janitza UMG604 (Modbus) (9172)",
        "values": {
            "P_AC_TOTAL": {
                "alias": "AC Active Power",
                "unit": "W"
            },
            "E_TOTAL_EXPORT": {
                "alias": "Active Energy: export",
                "unit": "Wh"
            },
            "E_TOTAL_IMPORT": {
                "alias": "Active Energy: import",
                "unit": "Wh"
            }
        }
    }
}

401 UNAUTHORIZED Response 

{
    "status": 401,
    "message": "No permission for that plant id (PXXXXXXX).",
    "message": "Already logged out.",
    "message": "Signature verification failed."
}

Returns all energy meter devices of the system and the available values.

GET https://api.be4energy.com/v1/device/meter

PATH PARAMS

name type mandatory
plantid string required

Response

object type example
deviceid (object) object ID meter_1
alias (property) property Energy Meter
values (object) object
valueid (object) object ID P_AC_TOTAL
value alias (property) property AC Active Power
value unit (property) property W

PV Charge Controller

GET Request 

 curl 
 -H 'Authorization: Bearer [TOKEN]'
 -X GET
 https://api.be4energy.com/v1/device/pvchargecontroller?plantid=P123454

200 OK Response 

{
    "bat_1": {
        "alias": "PVC 1.1",
        "serial": "XYZ",
        "loggerId": "XXXXXXXXX",
        "values": {
            "E_TOTAL": {
                "alias": "Energy Yield Total",
                "unit": "Wh"
            },
            "P_AC": {
                "alias": "AC Power",
                "unit": "W"
            }
        }
    }
}

401 UNAUTHORIZED Response 

{
    "status": 401,
    "message": "No permission for that plant id (PXXXXXXX).",
    "message": "Already logged out.",
    "message": "Signature verification failed."
}

Returns all PV charge controller of the system and the available values. The API returns only a subset of the values available of the energy storage controller in be4vision.

GET https://api.be4energy.com/v1/device/pvchargecontroller

PATH PARAMS

name type mandatory
plantid string required

Response

object type example
deviceid (object) object ID batinv_1
alias (property) property BatInv 01
serial (property) property XYZ
loggerId (property) property XXXXXXXXX
values (object) object
valueid (object) object ID P_AC_TOTAL
value alias (property) property AC Power
value unit (property) property W

Stringbox

GET Request 

 curl 
 -H 'Authorization: Bearer [TOKEN]'
 -X GET
 https://api.be4energy.com/v1/device/stringbox?plantid=P123454

200 OK Response 

{
    "stringbox_1": {
        "alias": "SCB 1.1.1.T1",
        "serial": null,
        "loggerId": "798059",
        "values": {
            "I_DC_1": {
                "ppeak": "1",
                "unit": "A",
                "class": "I_DC",
                "alias": "String Current 01"
            },
            "I_DC_10": {
                "ppeak": "1",
                "unit": "A",
                "class": "I_DC",
                "alias": "String Current 10"
            },
            "I_DC_11": {
                "ppeak": "1",
                "unit": "A",
                "class": "I_DC",
                "alias": "String Current 11"
            },
            "I_DC_12": {
                "ppeak": "1",
                "unit": "A",
                "class": "I_DC",
                "alias": "String Current 12"
            },
            "I_DC_13": {
                "ppeak": "1",
                "unit": "A",
                "class": "I_DC",
                "alias": "String Current 13"
            },
            "I_DC_14": {
                "ppeak": "1",
                "unit": "A",
                "class": "I_DC",
                "alias": "String Current 14"
            },
            "I_DC_2": {
                "ppeak": "1",
                "unit": "A",
                "class": "I_DC",
                "alias": "String Current 02"
            },
            "I_DC_3": {
                "ppeak": "1",
                "unit": "A",
                "class": "I_DC",
                "alias": "String Current 03"
            },
            "I_DC_4": {
                "ppeak": "1",
                "unit": "A",
                "class": "I_DC",
                "alias": "String Current 04"
            },
            "I_DC_5": {
                "ppeak": "1",
                "unit": "A",
                "class": "I_DC",
                "alias": "String Current 05"
            },
            "I_DC_6": {
                "ppeak": "1",
                "unit": "A",
                "class": "I_DC",
                "alias": "String Current 06"
            },
            "I_DC_7": {
                "ppeak": "1",
                "unit": "A",
                "class": "I_DC",
                "alias": "String Current 07"
            },
            "I_DC_8": {
                "ppeak": "1",
                "unit": "A",
                "class": "I_DC",
                "alias": "String Current 08"
            },
            "I_DC_9": {
                "ppeak": "1",
                "unit": "A",
                "class": "I_DC",
                "alias": "String Current 09"
            },
            "U_DC_TOTAL": {
                "ppeak": "1",
                "unit": "V",
                "class": "U_DC",
                "alias": "DC Voltage"
            }
        }
    },
}

401 UNAUTHORIZED Response 

{
    "status": 401,
    "message": "No permission for that plant id (PXXXXXXX).",
    "message": "Already logged out.",
    "message": "Signature verification failed."
}

Returns all stringbox devices of the system and the available values.

GET https://api.be4energy.com/v1/device/stringbox

PATH PARAMS

name type mandatory
plantid string required

Response

object type example
deviceid (object) object ID stringbox_1
alias (property) property CB 01.1
serial (property) property XYZ
loggerId (property) property DS458DFKDLKRT
values (object) object
valueid (object) object ID I_DC_1
value alias (property) property String Current 01
value unit (property) property A
value class (property) property I_DC

Tracker

GET Request 

 curl 
 -H 'Authorization: Bearer [TOKEN]'
 -X GET
 https://api.be4energy.com/v1/device/tracker?plantid=P123454

200 OK Response 

{
    "tracker_1": {
        "alias": "T01-01-1",
        "serial": "XYZ",
        "loggerId": "XXXXXXXXX",
        "values": {
            "CURRENT_AZIMUTH": {
                "alias": "Position: Azimuth Current [°]",
                "unit": "°",
                "class": "AZIMUTH"
            },
            "TARGET_AZIMUTH": {
                "alias": "Position: Azimuth Target [°]",
                "unit": "°",
                "class": "AZIMUTH"
            },
            "CURRENT_ELEVATION": {
                "alias": "Position: Elevation Current [°]",
                "unit": "°",
                "class": "ELEVATION"
            },
            "TARGET_ELEVATION": {
                "alias": "Position: Elevation Target [°]",
                "unit": "°",
                "class": "ELEVATION"
            },
            "SYSTEM_STATE": {
                "alias": "State: Tracker",
                "unit": "",
                "class": "STATE"
            },
            "FAULT_STATE": {
                "alias": "State: Fault",
                "unit": "",
                "class": "STATE"
            },
            "COM_STATE": {
                "alias": "State: Communication",
                "unit": "",
                "class": "STATE"
            }
        }
}

401 UNAUTHORIZED Response 

{
    "status": 401,
    "message": "No permission for that plant id (PXXXXXXX).",
    "message": "Already logged out.",
    "message": "Signature verification failed."
}

Returns all tracker devices of the system and the available values.

GET https://api.be4energy.com/v1/device/tracker

PATH PARAMS

name type mandatory
plantid string required

Response

object type example
deviceid (object) object ID tracker_1
alias (property) property Tracker 01.1
serial (property) property XYZ
loggerId (property) property DS458DFKDLKRT
values (object) object
valueid (object) object ID CURRENT_ELECATION
value alias (property) property Position: Elevation Current [°]
value unit (property) property °
value class (property) property ELEVATION

Direct Marketing

GET Request 

 curl 
 -H 'Authorization: Bearer [TOKEN]'
 -X GET
 https://api.be4energy.com/v1/device/dm/[plantid]

200 OK Response 

{
     "dm_1": {
        "alias": "DV Knoten",
        "serial": null,
        "loggerId": "1234567890",
        "values": {
            "DM_P_SP_TSO_W": {
                "alias": "Setpoint TSO",
                "unit": "W",
                "class": "P_SP"
            },
            "DM_P_SP_DM_W": {
                "alias": "Setpoint DM",
                "unit": "W",
                "class": "P_SP"
            },
            "DM_P_SP_DM_PERC": {
                "alias": "Setpoint DM [%]",
                "unit": "%",
                "class": "P_SP"
            },
            "DM_P_AC_GCP": {
                "alias": "AC Power (GCP)",
                "unit": "W",
                "class": "P_AC"
            }
        }
}

401 UNAUTHORIZED Response 

{
    "status": 401,
    "message": "No permission for that plant id (PXXXXXXX).",
    "message": "Already logged out.",
    "message": "Signature verification failed."
}

Returns all dm devices of the system and the available values.

GET https://api.be4energy.com/v1/device/dm/[plantid]

PATH PARAMS

name type mandatory
plantid string required

Response

object type example
deviceid (object) object ID dm_1
alias (property) property DV Knoten 1
loggerId (property) property DS458DFKDLKRT
values (object) object
valueid (object) object ID DM_P_SP_TSO_W
value alias (property) property Setpoint TSO
value unit (property) property W
value class (property) property P_SP

Aggregated Devices

GET Request 

 curl 
 -H 'Authorization: Bearer [TOKEN]'
 -X GET
 https://api.be4energy.com/v1/device/aggregated?plantid=P123454

200 OK Response 

{
    "virtual_1": {
        "alias": "Bezug - Einspeisung",
        "values": {
            "P_AC_TOTAL_IMPORT": {
                "alias": "Supply: Power",
                "unit": "W",
                "class": "P_AC"
            },
            "P_AC_TOTAL_EXPORT": {
                "alias": "Feed-in: Power",
                "unit": "W",
                "class": "P_AC"
            },
            "E_YEAR_IMPORT": {
                "alias": "Supply: Imported Energy Year",
                "unit": "Wh",
                "class": "E_YEAR"
            },
            "E_MONTH_EXPORT": {
                "alias": "Feed-in: Exported Energy Month",
                "unit": "Wh",
                "class": "E_MONTH"
            },
            "E_TODAY_EXPORT": {
                "alias": "Feed-in: Exported Energy Today",
                "unit": "Wh",
                "class": "E_TODAY"
            },
            "E_YEAR_EXPORT": {
                "alias": "Feed-in: Exported Energy Year",
                "unit": "-1",
                "class": "E_YEAR"
            },
            "E_TODAY_IMPORT": {
                "alias": "Supply: Imported Energy Today",
                "unit": "-1",
                "class": "E_TODAY"
            },
            "E_MONTH_IMPORT": {
                "alias": "Supply: Imported Energy Month",
                "unit": "-1",
                "class": "E_MONTH"
            }
        }
    },
    "virtual_2": {
        "alias": "Eigenverbrauch",
        "values": {
            "P_OWN_CONSUMPTION": {
                "alias": "Own Consumption: Power",
                "unit": "W",
                "class": "P_AC"
            },
            "E_TODAY_OWN_CONSUMPTION": {
                "alias": "Own Consumption: Energy Yield Today",
                "unit": "Wh",
                "class": "E_TODAY"
            },
            "E_MONTH_OWN_CONSUMPTION": {
                "alias": "Own Consumption: Energy Yield Month",
                "unit": "Wh",
                "class": "E_MONTH"
            },
            "E_YEAR_OWN_CONSUMPTION": {
                "alias": "Own Consumption: Energy Yield Year",
                "unit": "Wh",
                "class": "E_YEAR"
            }
        }
    },
    "virtual_3": {
        "alias": "Gesamtverbrauch",
        "values": {
            "E_TODAY_OVERALL_CONSUMPTION": {
                "alias": "Overall Consumption: Energy Yield Today",
                "unit": "Wh",
                "class": "E_TODAY"
            },
            "E_YEAR_OVERALL_CONSUMPTION": {
                "alias": "Overall Consumption: Energy Yield Year",
                "unit": "Wh",
                "class": "E_YEAR"
            },
            "E_MONTH_OVERALL_CONSUMPTION": {
                "alias": "Overall Consumption: Energy Yield Month",
                "unit": "Wh",
                "class": "E_MONTH"
            },
            "P_OVERALL_CONSUMPTION": {
                "alias": "Overall Consumption: Power",
                "unit": "W",
                "class": "P_AC"
            }
        }
    }
}

401 UNAUTHORIZED Response 

{
    "status": 401,
    "message": "No permission for that plant id (PXXXXXXX).",
    "message": "Already logged out.",
    "message": "Signature verification failed."
}

Returns all devices which contain aggregated data. For example there can be self consumption device.

GET https://api.be4energy.com/v1/device/aggregated

PATH PARAMS

name type mandatory
plantid string required

Response

object type example
deviceid (object) object ID virtual_1
alias (property) property Feedin 01.1
values (object) object
valueid (object) object ID P_AC_TOTAL_IMPORT
value alias (property) property Supply: Power
value unit (property) property W
value class (property) property P_AC

Value Object Description

valueid Description
P_AC_TOTAL_IMPORT AC Power supply from grid.

Available data resolution depends on the underlying meter data resolution

P_AC_TOTAL_EXPORT AC Power feed to grid.

Available data resolution depends on the underlying meter data resolution

E_TODAY_IMPORT Aggregated energy consumption from grid for the current day

Reseted each day at midnight

Data resolution is 60 Minutes

E_TODAY_EXPORT Aggregated energy feed to grid for the current day

Reseted each day at midnight

Data resolution is 60 Minutes

E_MONTH_IMPORT Aggregated energy consumption from grid for the current month

Reseted on 01.MM.YY 00:00:00 at plant time zone

Data resolution is 60 Minutes

E_MONTH_EXPORT Aggregated energy feed to grid for the current month

Reseted on 01.MM.YY 00:00:00 at plant time zone

Data resolution is 60 Minutes

E_YEAR_IMPORT Aggregated energy consumption from grid for the current year

Reseted on 01.01.YY 00:00:00 at plant time zone

Data resolution is 60 Minutes

E_YEAR_EXPORT Aggregated energy feed to grid for the current year

Reseted on 01.01.YY 00:00:00 at plant time zone

Data resolution is 60 Minutes

P_OWN_CONSUMPTION Energy consumption produced by plant generator (for example from the PV generator)

Available data resolution depends on the underlying meter data resolution

E_TODAY_OWN_CONSUMPTION Daily energy consumption produced by plant generator (for example from the PV generator)

Reseted each day on midnight

Data resolution is 60 Minutes

E_MONTH_OWN_CONSUMPTION Monthly energy consumption produced by plant generator (for example from the PV generator)

Reseted on 01.MM.YY 00:00:00 at plant time zone

Data resolution is 60 Minutes

E_YEAR_OWN_CONSUMPTION Yearly energy consumption produced by plant generator (for example from the PV generator)

Reseted on 01.01.YY 00:00:00 at plant time zone

Data resolution is 60 Minutes

P_OVERALL_CONSUMPTION Overall energy consumption

Available data resolution depends on the underlying meter data resolution

E_TODAY_OVERALL_CONSUMPTION Daily overall energy consumption

Reseted each day on midnight

Data resolution is 60 Minutes

E_MONTH_OVERALL_CONSUMPTION Monthly aggregated overall energy consumption

Reseted on 01.MM.YY 00:00:00 at plant time zone

Data resolution is 60 Minutes

E_YEAR_OVERALL_CONSUMPTION Yearly aggregated overall energy consumption

Reseted on 01.01.YY 00:00:00 at plant time zone

Data resolution is 60 Minutes

Accessing Data

Single Value Data

GET Request 

 curl 
 -H 'Authorization: Bearer [TOKEN]'
 -X GET
 https://api.be4energy.com/v1/data/interval?plantid=P123456&
deviceid=inverter_1&
valueid=P_AC&
from=2018-03-01 23:00:00&
to=2018-03-02 23:00:00&
resolution=15min&
aggregate=max

200 OK Response 

{
    "plantid": "P123456",
    "deviceid": "inverter_1",
    "valueid": "P_AC",
    "from": "2018-03-01 23:00:00",
    "to": "2018-03-02 23:00:00",
    "data": {
        "2018-03-01 23:00:00": 0,
        "2018-03-01 23:15:00": 0,
        ...
        "2018-03-02 07:00:00": 2900,
        "2018-03-02 07:15:00": 3107,
        "2018-03-02 07:30:00": 3797,
        ...
        "2018-03-02 22:30:00": null,
        "2018-03-02 22:45:00": null
    }
}

404 NOT FOUND Response 

{
    "status": 404,
    "message": "Could not resolve device id",
    "message": "Could not resolve value id",
}

401 UNAUTHORIZED Response 

{
    "status": 401,
    "message": "permission denied for this aggreagte. Allowed aggreagtes: [avg, min, max, delta]",
    "message": "permission denied for this resolution. Allowed resolution: []",
    "message": "No permission for that plant id (PXXXXXXX).",
    "message": "Already logged out.",
    "message": "Signature verification failed."
}

When fetching data there are some things to consider for the timestamp parameter from and to . First of all seconds are set to 00 by the API. The timestamp in the parameter from will be set the next earlier timestamp of the requests resolution. For example if you use 15 min resolution and set the timestamp for from :

2023-07-01 12: 20 :00 -> 2023-07-01 12: 15 :00
2023-07-01 12: 34 :00 -> 2023-07-01 12: 30 :00
2023-07-01 12: 44 :00 -> 2023-07-01 12: 30 :00
2023-07-01 12: 52 :00 -> 2023-07-01 12: 45 :00

For 5 min resolution the API will transform the parameter from timestamp like this:

2023-07-01 12: 20 :00 -> 2023-07-01 12: 20 :00
2023-07-01 12: 21 :00 -> 2023-07-01 12: 20 :00
2023-07-01 12: 44 :00 -> 2023-07-01 12: 40 :00

When using 1min resolution there will be no change. The API processes a half-open interval. It include from and excludes to [from, to).
For example with a 15min resolution the following interval will give this response

from : 2023-07-01 12:15:00 to: 2023-07-01 13:00:00 will return:

2023-07-01 12:15:00
2023-07-01 12:30:00
2023-07-01 12:45:00

In the default API license there is only 15min resolution available. To fetch data with a higher resolution please contact be4energy at service@be4energy.com

GET https://api.be4energy.com/v1/data/interval

PATH PARAMS

name type mandatory example memo
plantid string required
deviceid string required
valueid string required
from datetime required 2018-03-01 00:00:00 Date will be interpreted as UTC date
to datetime required 2018-03-01 00:00:00 Date will be interpreted as UTC date
resolution string required 15min
aggregate string required avg min

RESPONSE

In the response you will find the requested object ids such as plantid, deviceid and valueid. This allowed makes sure you know where the data is from.

object type example
plantid (object) object ID P12345
deviceid (object) object ID inverter_1
valueid (object) object ID P_AC
from (property) datetime 2018-03-01 23:00:00
to (property) datetime 2018-03-02 23:00:00

Several Values of Device

GET Request 

 curl 
 -H 'Authorization: Bearer [TOKEN]'
 -X GET 
 https://api.be4energy.com/v1/data/interval/bulk?plantid=PXXXXXX&
 deviceid=stringbox_1&valueids=I_DC_1,I_DC_2,I_DC_3,I_DC_4,I_DC_5&
  from=2020-07-20 23:00:00&
  to=2020-07-21 23:00:00&
  resolution=60min&
  aggregate=avg

200 OK Response 

{
    "plantid": "PXXXXXX",
    "from": "2020-07-21 09:00:00",
    "to": "2020-07-21 10:00:00",
    "last_date": "2020-07-21 09:45:00",
    "data": {
        "stringbox_1": {
            "alias": "SB X.Y.Z",
            "type": "STRINGBOX",
            "values": ["I_DC_1","I_DC_2","I_DC_3","I_DC_4","I_DC_6"],
            "data": {
                "2020-07-21 09:00:00": [4.94, 4.87, 4.94, 4.95, 5],
                "2020-07-21 09:15:00": [5.33, 5.25, 5.32, 5.33, 5.39],
                "2020-07-21 09:30:00": [5.71, 5.6, 5.68, 5.69, 5.76],
                "2020-07-21 09:45:00": [6.05, 5.96, 6.03, 6.05, 6.1]
            }
        }
    }
}

404 NOT FOUND Response 

{
    "status": 404,
    "message": "Could not resolve device id",
    "message": "Could not resolve value id",
    "detail": "value id does not exist in device: [value id]"
}

Query data for several values of a single device. This is the recommended way of get data of a device.

GET https://api.be4energy.com/v1/data/interval/bulk

PATH PARAMS

name type mandatory example memo
plantid string required
deviceid string required
valueids string required I_DC_1, I_DC_2 Comma separated value ids
from datetime required 2018-03-01 00:00:00 Date will be interpreted as UTC date
to datetime required 2018-03-01 00:00:00 Date will be interpreted as UTC date
resolution string required 15min
aggregate string required avg min

RESPONSE

In the response you will find the requested object ids such as plantid, deviceid and valueids. To match the array index of the 'data' corresponds to the index of the 'values' array.

For example in the current response you want to find the data of I_DC_6 which is at position 5
"values": ["I_DC_1","I_DC_2","I_DC_3","I_DC_4", "I_DC_6" ]

In the data array you can find the data at position 5
"2020-07-21 09:15:00": [5.33, 5.25, 5.32, 5.33, 5.39 ]

object type example
plantid (object) object ID P12345
deviceid (object) object ID stringbox_1
from (property) datetime 2018-03-01 23:00:00
to (property) datetime 2018-03-02 23:00:00
data object
data:[device_id]:alias string Stringbox 1.1.1
data:[device_id]:type string STRINGBOX
data:[device_id]:values (object) array [I_DC_1, I_DC_2]
data:[device_id]:data object Time series data
bash