The DER (Distributed Energy Resource) API is general to all appliances that consume, produce or store energy and offer an interface including batteries, charging stations, inverters, and heat pumps. It is based on an abstraction model with the following sign convention:

• Energy exports are considered negative, e.g. the power produced by PV panels, the power of a battery discharging, the net power export to the grid at the global coupling point.
• Energy imports are considered positive, e.g. the power consumed by a load, the power of a battery charging, the net power import from the grid at the global coupling point.

The API is based on three main endpoints:

• Flexibilities: Reflecting the state of an appliance and its resulting operating constraints

• Constraints: Set of constraints applying to an appliance, including operational limits and direct control set points

• Recommendation: Used to advise a local controller in case of non-direct control of the appliance via the API. (Recommendations are currently not supported)

Their scope and usage is further documented hereafter.

Constraint Endpoint

Appliance constraints allows to set constraints to an appliance. Constraints can consist in:

• Operational ranges, i.e min/max values. For example, to allow a battery to only discharge up to 2kW, set activePowerMax=0 and activePowerMin=-2000.

• Set points, i.e. the control value directly expected to be applied to an appliance. For example, to charge an EV with 2kW, set activePower = 2000.

To each constraint is associated:

• A date after which the constraint expires (invalidAt)

• A priority level: 0-low, infinity-high. In case multiple constraints are set to a same field, or if conflicting constraints are set, the priority level allows to determine the final operating constraint.

Flexibility Endpoint

The flexibilities reflect the state of an appliance and its resulting operating constraints.

The concept of flexibility is general to all appliances. For example:

• In the case of an EVCS (Electric Vehicle Charging Station), the minActivePower and maxActivePower values reflect the min and max total operating power range of the EVCS; the power is the latest power value

• In the case of a meter at the global coupling point with the grid, the minActivePower (negative value) is the total feedin power limit, and the maxActivePower (positive value) is the total import limit. The power, if negative, reflects power being exported to the grid, whereas if positive, reflects the power being imported from the grid

• In the case of a battery, the min power (negative value) represents the max discharging power, whereas the max power (positive value) represents the max charging power. The power, when negative, reflects the fact that the battery is discharging, whereas when positive, reflects the power being charged by the battery.

• If an appliance is not available to external control via the API due to local constraint, its flexibilities shall reflect it. For example, its minActivePower/maxActivePower values will return 0.

• If constraints set on the appliance restrict its operation range, its flexibilities shall reflect it. For example, to preserve a certain energy level, the minEnergy/maxEnergy values returned by the flexibilities may differ from their physical counterparts

Recommendation Endpoint

Warning: this endpoint is currently not supported.

Recommendations are used to advise a local controller in case of non-direct control of the appliance via the API. For direct control of the appliance, see the Constraints endpoint.

The recommendation can be either an energy/state-of-charge/temperature level to attain in a given period of time, or a power value to follow over a period of time.

As opposed to constraints, recommendations may not be followed strictly by the local controller, for example:

Summary of API requests and usage

Note: the local controller refers to the local Energy Management System.