Power direction and response fields
Units, positive and negative power, nullability and the meaning of device telemetry.
Units and missing values
Active power is in watts (W), energy and battery capacity in watt-hours (Wh), voltage in volts (V), current in amperes (A), frequency in hertz (Hz) and temperature in degrees Celsius (°C). Divide W or Wh by 1,000 to obtain kW or kWh. Apparent power uses VA and reactive power uses var.
Battery soe (state of energy), soh (state of health), minSoe, maxSoe and
boiler pwmPercent use percentages: 50 means 50%, not 0.5.
Every listed property is returned, but many values can be null. Unsupported PV
inputs, phases and sensors are commonly null. Null means no usable value; 0
means a measured zero. Dates are ISO 8601 strings with a UTC offset or null.
Check each device's lastSeenDate; the response contains last-known data, including
offline devices, and is not a synchronized measurement across the installation.
Positive and negative power
There is no single sign convention for every device type. The following rules
apply to the fields returned by getInstallationDevices.
| Device and field | Positive | Negative |
|---|---|---|
Grid import/export meter: powerAc, powerAcL1–powerAcL3 | Export to the grid | Import from the grid |
Production meter: powerAc, phase powers | Production into the installation | Reverse flow at that meter's boundary |
Inverter: powerAc, phase powers | Output to the installation AC bus, from PV and/or a discharging battery | Absorption from the AC bus, e.g. charging or standby consumption |
Battery: powerDc | Charging the battery | Discharging the battery |
Inverter: powerDc | Device-dependent: net DC input toward AC conversion, or PV production | Reverse conversion from AC to DC on devices that report net DC conversion |
Inverter: powerDcPvTotal, powerDcPv1–powerDcPv6 | PV production into the inverter | No defined charging/import meaning |
Inverter: backupPowerAc | Supplying the backup/EPS loads | Reverse flow into the backup output, if reported |
EV charger: powerAc, phase powers, powerDc | Vehicle charging consumption | No supported discharge/V2G meaning in this API version |
Boiler: powerAc, phase powers | Electricity consumed for heating | No defined generation/export meaning |
For signed battery currentDc, positive also means charging and negative means
discharging. Prefer powerDc for battery power direction. AC current, reactive
power and power factor can have device-specific sign conventions; do not infer
active import/export from their signs.
Meter boundary matters
The energyMeters array may contain grid, production and consumption meters.
Each meter includes options, a string or null describing its role/options.
GridSense recognizes these values:
options | Meter role |
|---|---|
Export+Import | Main grid import/export meter. |
Boiler consumption | Boiler consumption meter. |
A string containing Production ext | External production meter. |
This field is an open string, not a fixed enum. Null bytes and surrounding
whitespace are removed; an empty string remains empty. If options is null,
empty or unrecognized, confirm the meter's role and wiring. Array position does
not identify the grid meter. Multiple meters may measure the same connection;
summing them can double count power.
For a known grid meter, powerAc: -2500 means importing 2.5 kW and
powerAc: 2500 means exporting 2.5 kW. GridSense's internal energy-flow summary
uses the opposite sign for its gridPower field, returned by
getInstallationCurrentEnergyFlow.
totalImportAc, totalExportAc, dailyImportAc and dailyExportAc are energy
counters in Wh. Direction is in the field name: do not negate an import counter
because the instantaneous grid meter power is negative. Daily reset timing
follows the device and has no universal timezone guarantee in this API.
Inverter power is not grid export or battery power
An inverter producing 3,000 W can supply local loads while the site still imports from the grid. Use a known grid meter to determine the installation's grid flow. Likewise, inverter AC output can include both PV and battery power.
batteries[].powerDc: 1500 means the battery is charging at 1.5 kW;
-1500 means it is discharging at 1.5 kW. This sign is opposite to the inverter's
AC output during battery-only operation. Conversion losses mean the magnitudes
need not be equal.
Inverter powerDc is passed through from the integration. Some devices use it for
PV production; SolarEdge uses net DC conversion, which can include battery flow.
For those SolarEdge integrations, PV power is derived from inverter DC power plus
battery charging power and clamped at zero. Use powerDcPvTotal for solar
production and the battery's own powerDc for charge/discharge. Do not apply that
SolarEdge calculation universally or assume powerDc is solar generation when
powerDcPvTotal is null.
The current API reports supportsBiDirectionalCharging: false for EV chargers.
It does not define negative charger power as a supported vehicle-to-grid feature.
Aggregated installation energy flow
Get current installation energy flow
returns { valid, installationId, data }. It uses online inverters, batteries,
meters, EV chargers and boilers only; relays do not contribute. With none online,
data is null. Otherwise all nine fields are present, but individual values may
be null. The readings are not synchronized.
| Field | Meaning |
|---|---|
inverterPower | Inverter AC power plus external production meters, in W. Positive = output; negative = absorption. |
solarPower | Estimated solar power in W from inverter DC power, integration-specific battery corrections and external production meters. It is not simply the sum of PV telemetry. |
batteryPower | Sum of battery DC power in W. Positive = charging; negative = discharging. |
batterySoe | Arithmetic mean of online battery soe in percent, not weighted by capacity. Missing readings count as zero in this average. |
gridPower | Negative mean of online Export+Import meter power in W. Positive = import; negative = export, opposite to raw meter powerAc. |
housePower | Estimated consumption in W: grid plus inverter power, minus EV charger and boiler consumption, clamped to zero. |
evChargerPower | Sum of charger power in W, preferring each charger's DC reading over AC. Positive = charging consumption. |
boilerPower | Sum of available boiler AC readings in W, falling back to absolute Boiler consumption meter readings only when no boiler device reading is available. |
lastUpdated | Newest timestamp among the included online devices, not the request time or the oldest reading. |
For example, gridPower: -1200 means exporting 1.2 kW, while
batteryPower: 800 means charging at 800 W. With inverterPower: 4200,
evChargerPower: 600 and boilerPower: 400, housePower is 2,000 W.
Aggregation can turn missing readings into zero. In particular, gridPower is
null when no meters are online, but zero when online meters exist without an
Export+Import meter. A zero is therefore not proof of a balanced grid connection.
Inspect the device endpoint and meter options when interpreting incomplete data.
Response field groups
The installation reference and device reference document every property in their response schemas, including types, nullability and units. Expand an array's item schema under Responses to inspect a device's fields.
| Object | Returned information |
|---|---|
| Installation | ID, name, private/commercial type, address, timezone, coordinates, altitude and creation date. |
| All devices | ID, installation/gateway IDs, manufacturer, model, firmware version, serial number and first/last seen dates. Associated IDs may be null. |
| Inverter | SunSpec status and vendor status text, off-grid flag, charge/discharge limits, total/phase AC measurements, apparent/reactive power and power factor, backup AC power, DC/PV measurements for up to six inputs and temperature. |
| Battery | Associated inverter ID, numeric status, DC power/voltage/current, energy/health percentages, pack/cell temperatures, cell voltages, capacities, available energy, continuous power limits and energy percentage limits. |
| Energy meter | Role/options (options), total/phase AC power, phase voltages/currents, frequency and import/export energy counters. |
| EV charger | Mode, authorization requirement, bidirectional capability, configured/current charging-current limits, status, offered power, AC/DC measurements and temperature. |
| Relay | Channel count and arrays of current and desired states. |
| Boiler | Status and mode, AC measurements, four temperature sensors, temperature targets, available/effective maximum power, vendor operating states, device/relay state, load state and PWM percentage. |
Status and limits
Inverter status is a normalized object with rawValue and name:
rawValue | name |
|---|---|
| 1 | Off |
| 2 | Sleeping |
| 3 | Starting |
| 4 | MPPT |
| 5 | Throttled |
| 6 | Shutting Down |
| 7 | Fault |
| 8 | Standby |
Unrecognized inverter status is null. Battery and boiler status codes and EV
charger status strings are device-specific; the API does not provide a common
enum for them. Boiler operationMode, operationState and loadState are also
vendor-specific numeric values.
Power limits and offers (maxChargePower, maxDischargePower, battery continuous
power limits, powerOffered, availablePower, effectiveMaxPower) are magnitudes,
not signed instantaneous measurements. EV currentMaxChargingCurrent is computed
from the mode/schedule and may differ from maxChargingCurrent.
Battery ratedEnergy uses the configured capacity override when one exists.
Relay state arrays use zero-based channel indexes. true means on and false
means off. A null desiredState entry means automatic control/no manual override;
the entire array may also be null. Desired state can differ from actual state and
does not include the resolved result of automation.