API State
Der API State ist die Datenstruktur hinter der UI. Er ist über drei Schnittstellen verfügbar. Es gibt keine Kompatibilitätsgarantie, Felder können sich zwischen Releases ändern.
- REST-API:
GET /api/stateliefert den kompletten Zustand als ein JSON-Dokument, eingepackt in einresult-Objekt. Mit dem Query-Parameterjqlässt sich die Antwort per jq-Ausdruck filtern.- Live-Beispiel:
https://demo.evcc.io/api/state - Gefiltert auf ein einzelnes Feld:
https://demo.evcc.io/api/state?jq=.loadpoints[2].chargePower
- Live-Beispiel:
- MQTT: jedes Feld wird als eigenes Topic veröffentlicht. Felder der Site liegen unter
evcc/site/<feld>, Ladepunkt-Felder unterevcc/loadpoints/<n>/<feld>mit Index ab 1. Verschachtelte Objekte und Listen werden in Sub-Topics aufgelöst, z. B.evcc/site/pv/1/power. Werte werden als einfache Strings veröffentlicht, Zeitstempel als Unix-Sekunden, Zeitdauern in Sekunden. - WebSocket: beim Verbinden erhält der Client den kompletten Zustand als ein JSON-Objekt. Ladepunkt-Felder verwenden Schlüssel mit Punktnotation wie
loadpoints.0.chargePower. Danach werden nur noch inkrementelle Updates gesendet: kleine JSON-Objekte mit den geänderten Feldern, die der Client in seine Kopie des Zustands übernimmt.
Top Level
HTTP API is ready to accept requests.
Authentication is disabled.
Status of configured vehicle authentication providers, keyed by provider name.
Total power of all auxiliary meters in W.
Latest available evcc version.
Home battery discharge is prevented during fast charging and planned charging.
Home battery is currently charged from grid.
Price or emission limit for charging the home battery from grid.
Home battery is allowed to discharge to the grid (experimental).
Current operation mode of the home battery.
Battery buffer SoC in %. Energy above this level may be used for charging in solar mode.
Battery buffer start SoC in %. Solar charging starts automatically above this level.
Path of the evcc configuration file.
Path of the evcc database.
Instance runs in demo mode.
Colors assigned to devices for consistent UI display.
Experimental UI features are enabled.
Fatal startup errors.
A grid meter is configured.
Time of the last energy history update.
Home consumption power in W.
InfluxDB integration configuration.
Update interval of the control loop in seconds.
Charging locations. One entry per configured loadpoint.
Built-in MCP server is enabled.
Messaging services configuration. Structure depends on configuration.
Configured notification messages per event type.
Modbus proxy configuration.
MQTT integration configuration.
OCPP forwarder rules and upstream connection status.
Battery optimizer is enabled.
Available battery optimizer charging strategies.
Selected battery optimizer charging strategy.
Battery priority SoC in %. Home battery is charged first while below this level.
Total solar generation energy in kWh.
Total solar generation power in W. Sum of all pv meters.
Configured grid operating point in W. Positive values maintain grid import.
Initial setup is required.
Configured site title.
A dynamic grid price or CO₂ forecast is configured.
Type of the smart charging limit, price based or emission based.
A feed-in tariff with forecast is configured.
Solar forecast is adjusted to real production data (experimental).
Startup has completed.
Charging statistics over different time periods.
Operating system and architecture.
Current grid CO₂ emissions in g/kWh.
Current CO₂ emissions of home consumption in g/kWh, taking the green energy share into account.
Current CO₂ emissions of charging in g/kWh, taking the green energy share into account.
Current feed-in rate per kWh in the configured currency.
Current grid energy price per kWh in the configured currency.
Current energy price of home consumption per kWh, taking the green energy share into account.
Current energy price of charging per kWh, taking the green energy share into account.
Configured tariffs. Structure depends on configuration.
Current cost of solar generation per kWh in the configured currency.
Current outside temperature in °C.
Telemetry is enabled.
Server time zone abbreviation and UTC offset.
Running evcc version.
Typen
AuthProviders
Status of configured vehicle authentication providers, keyed by provider name.
Used by: State.authProviders
Battery
Home battery state. Aggregated across all battery meters.
Used by: State.battery
Total battery capacity in kWh.
Measurement data per battery meter.
Total battery energy in kWh.
Projected charge levels based on the solar and price forecast.
Current battery power in W. Positive means discharging, negative means charging.
Charge level in %. Weighted by capacity across all batteries.
BatteryForecast
Projected home battery charge levels based on the solar and price forecast.
Used by: Battery.forecast
Projected highest charge level.
Projected lowest charge level.
BatteryForecastPoint
A projected home battery charge level at a point in time.
Used by: BatteryForecast.highest, BatteryForecast.lowest
The projection hits the upper or lower battery limit.
Projected charge level in %.
Time of the projected charge level.
BatteryMeter
Measurement data of a single home battery meter.
Used by: Battery.devices
Battery capacity in kWh. Zero when not specified.
Battery supports external control of its operation mode.
Current per phase in A.
Total energy in kWh.
Meter icon name for UI display.
Unique device name of the meter.
Current power in W.
Power per phase in W.
Total exported energy in kWh.
Charge level in %.
Battery optimizer suggestion.
Meter title for UI display.
BatteryMode
Battery operation mode.
Used by: State.batteryMode
"unknown""normal""hold""charge""holdcharge"
BatterySuggestion
Battery optimizer suggestion for a home battery.
Used by: BatteryMeter.suggestion
Suggestion differs from the current operating mode.
Recommended charge power in W.
Recommended discharge power in W.
Certificate
A TLS certificate key pair.
Used by: EebusConfig.certificate
Private key in PEM format. Redacted.
Public certificate in PEM format.
ChargeMode
Charging mode.
Used by: Loadpoint.mode, Vehicle.mode
"off""now""minpv""pv"
ChargerStatusReason
Reason why the charger is waiting.
Used by: Loadpoint.chargerStatusReason
"unknown""waitingforauthorization""disconnectrequired"
Circuit
A load management circuit limiting power and current of its assigned loadpoints.
Used by: State.circuits
Current in A.
Circuit icon name for UI display.
Maximum allowed current in A.
Maximum allowed power in W.
Name of the parent circuit.
Current power in W.
Circuit title for UI display.
Currency
Currency in ISO 4217 format.
Used by: State.currency
"AUD""BGN""BRL""CAD""CHF""CNY""CZK""EUR""GBP""HUF""ILS""JPY""NZD""NOK""PLN""RON""USD""DKK""SEK""ZAR""TRY""MYR""THB"
DeviceColorEntry
Color assigned to a device for consistent UI display.
Used by: State.deviceColors
Assigned color as CSS value.
Device title the color is assigned to.
Eebus
EEBus integration configuration and status.
Used by: State.eebus
Static configuration.
Runtime status.
EebusConfig
EEBus integration configuration.
Used by: Eebus.config
TLS certificate.
Network interfaces the EEBus service uses.
Port the EEBus service listens on.
SHIP id.
URI the EEBus service listens on.
EebusStatus
EEBus runtime status.
Used by: Eebus.status
EnergyByDay
Expected solar production energy of a day.
Used by: SolarDetails.dayAfterTomorrow, SolarDetails.today, SolarDetails.tomorrow
Forecast data covers the whole day.
Expected production energy in kWh.
FatalError
A fatal startup error.
Used by: State.fatal
Device class the error originates from, like meter or charger.
Name of the device that caused the error.
Error message.
Forecast
Price, CO₂ and solar production forecasts.
Used by: State.forecast
CO₂ emission forecast in g/kWh per time slot.
Feed-in rate forecast. Rate per kWh in the configured currency per time slot.
Grid price forecast. Price per kWh in the configured currency per time slot.
Charging cost forecast used by the plan optimizer per time slot.
Solar production forecast.
Temperature forecast in °C per time slot.
ForecastSlot
A forecast time slot as [start, end, value] array. Start and end are unix seconds. Value unit depends on the forecast type.
Used by: Forecast.co2, Forecast.feedin, Forecast.grid, Forecast.planner, Forecast.temperature
GenericConfigStatus
Configuration and runtime status of an integration. Structure depends on configuration.
Used by: State.messaging, State.tariffs
Hems
Home energy management system integration.
Used by: State.hems
Static configuration.
Runtime status.
HemsConfig
Home energy management system configuration.
Used by: Hems.config
A home energy management system is configured.
HemsStatus
Current external limits imposed by the home energy management system.
Used by: Hems.status
Allowed feed-in in %. Values below 100 mean production is curtailed.
Consumption is currently limited.
Maximum allowed consumption power in W.
Maximum allowed production power in W.
InfluxConfig
InfluxDB integration configuration.
Used by: State.influx
Database name (InfluxDB 1.x) or bucket (InfluxDB 2.x).
Skip TLS certificate verification.
Organization (InfluxDB 2.x).
Password (InfluxDB 1.x). Redacted.
Access token (InfluxDB 2.x). Redacted.
InfluxDB server URL.
Username (InfluxDB 1.x).
Loadpoint
A charging location with a charger, an optional dedicated meter and an optional vehicle.
Used by: State.loadpoints
Battery boost is active. When enabled, home battery power is used for fast charging.
SoC limit for battery boost in %.
Charging current per phase in A.
Energy charged in the current charging session in kWh.
Duration of the current charging session in seconds.
Current charging power in W.
Estimated remaining charging time in seconds.
Estimated remaining energy in kWh.
The connected vehicle is not identified automatically by its status.
Values are averaged.
Values are cached.
The climater state of the connected vehicle is ignored for charge control.
Charger only supports full ampere steps for current control.
Charger is a heating device where disabled means normal operation.
Charger is a heating device. SoC values represent temperature in degrees.
Charger is an always-connected device without vehicles and charging sessions, like a heat pump.
The connected vehicle only provides data while charging.
Vehicle API calls are retried on failure.
The connected vehicle pushes data updates instead of being polled.
Charger is a switchable device without current control, like a heat pump or switch socket.
No wake-up calls are sent to the connected vehicle.
The connected vehicle may need a short welcome charge to start communicating.
Charger icon name for UI display.
Charger supports automatic switching between 1-phase and 3-phase charging.
Charger is physically connected with a single phase.
Reason why the charger is waiting, like a pending authorization or a required disconnect.
Total energy imported by the charge meter in kWh.
Charging voltage per phase in V.
A vehicle is connected and charging.
A vehicle is connected to the charger.
Duration since the vehicle was connected, in seconds.
Delay before charging stops in solar mode, in seconds.
Grid draw power above which charging stops in solar mode, in W.
Currently applied SoC limit in %.
Currently applied maximum charging current in A.
Currently applied minimum charging current in A.
Currently applied minimum SoC in %.
Id of the currently applied charging plan. Zero if no plan is active.
SoC goal in % of the currently applied charging plan.
Currently applied charging plan strategy.
Target time of the currently applied charging plan.
Currently applied priority.
Charger is currently allowed to charge.
Delay before charging starts in solar mode, in seconds.
Available surplus power above which charging starts in solar mode, in W.
Energy used in the last 24 hours in kWh.
Energy used in the last 7 days in kWh.
Session energy limit in kWh. Zero means no limit.
Session SoC limit in %. Zero means no limit.
Maximum charging current in A.
Minimum charging current in A.
Minimum SoC in %. Vehicle is fast-charged until this level is reached.
Vehicle SoC is below the configured minimum SoC.
Charging behavior.
Unique loadpoint identifier used in API routes and configuration.
Current offered to the vehicle in A.
Pending phase switching action in solar mode.
Remaining time until the pending phase switching action executes, in seconds.
Number of phases expected to be used for charging.
Configured phase mode. 0 is automatic switching, 1 and 3 select a fixed phase count.
The current time slot is an active charging slot of the plan.
Energy goal of the charging plan in kWh.
Duration in seconds the charging plan is projected to miss its target time.
Projected end of the charging plan. End of the last planned slot.
Projected start of the charging plan. Start of the earliest planned slot.
Charging plan strategy.
Target time of the charging plan.
Priority for surplus distribution. Higher number means higher priority.
Remaining time until the pending charge start or stop action executes, in seconds.
Average CO₂ emissions of the current charging session in g/kWh.
Energy charged in the current charging session in kWh.
Total cost of the current charging session in the configured currency.
Average energy price of the current charging session per kWh in the configured currency.
Share of solar energy in the current charging session in %.
Fast charging with cheap or clean grid energy is currently active.
Price or emission limit for fast charging with grid energy.
Start of the next fast charging period with cheap or clean grid energy.
Charging pause for prioritized feed-in is currently active.
Feed-in rate limit above which charging is paused.
Start of the next charging pause for prioritized feed-in.
Charging suggestion from the battery optimizer.
Loadpoint title for UI display.
Energy used since midnight in kWh.
Display-only UI settings.
Climater of the connected vehicle is active.
Automatic vehicle detection is running.
SoC limit configured in the vehicle itself, in %.
Unique name of the connected vehicle. Empty for guest vehicles.
Odometer reading of the connected vehicle in km.
Range of the connected vehicle in km.
Charge level of the connected vehicle in %. Temperature in degrees for heating devices.
Title of the connected vehicle for UI display.
A short welcome charge is active to enable vehicle communication.
LoadpointSuggestion
Battery optimizer suggestion for a loadpoint.
Used by: Loadpoint.suggestion
Suggestion differs from the current operating mode.
Recommended charge power in W.
Recommended discharge power in W.
LoadpointUi
Display-only UI settings of a loadpoint.
Used by: Loadpoint.ui
Upper bound of the temperature scale for heating devices, in degrees.
Lower bound of the temperature scale for heating devices, in degrees.
MessagingEvent
A configured notification message.
Used by: MessagingEvents.asleep, MessagingEvents.connect, MessagingEvents.disconnect, MessagingEvents.guest, MessagingEvents.planoverrun, MessagingEvents.soc, MessagingEvents.start, MessagingEvents.stop, MessagingEvents.suggestion
Notifications for this event are disabled.
Message body template.
Message title template.
MessagingEvents
Configured notification messages, keyed by event type.
Used by: State.messagingEvents
Meter
Measurement data of a single meter.
Used by: State.aux, State.consumers, State.ext, State.grid, State.pv
Current per phase in A.
Total energy in kWh.
Meter icon name for UI display.
Unique device name of the meter.
Current power in W.
Power per phase in W.
Total exported energy in kWh.
Meter title for UI display.
ModbusBaudrate
Serial baud rate.
Used by: ModbusProxySettings.baudrate
12009600192003840057600115200
ModbusComset
Serial communication parameters.
Used by: ModbusProxySettings.comset
"8N1""8E1""8N2"
ModbusProxy
A Modbus proxy forwarding requests to a physical device.
Used by: State.modbusproxy
Port the proxy listens on.
How write requests are handled.
Connection settings of the physical device.
ModbusProxyReadonly
How the Modbus proxy handles write requests.
Used by: ModbusProxy.readonly
"false""true""deny"
ModbusProxySettings
Connection settings of a Modbus device.
Used by: ModbusProxy.settings
Serial baud rate.
Serial communication parameters.
Serial device path.
Use RTU protocol over TCP.
Device address for TCP connections.
MqttConfig
MQTT integration configuration.
Used by: State.mqtt
Broker address.
CA certificate for TLS connections.
Client certificate for TLS connections.
MQTT client id.
Client key for TLS connections.
Skip TLS certificate verification.
Broker password. Redacted.
Root topic all values are published under.
Broker username.
Network
Network configuration.
Used by: State.network
Externally reachable URL.
Hostname.
URL in the local network.
HTTP port.
URL schema, http or https.
Ocpp
OCPP server configuration and status.
Used by: State.ocpp
OCPP server configuration.
OCPP server status.
OcppConfig
OCPP server configuration.
Used by: Ocpp.config
Port the OCPP server listens on.
OcppConnectionStatus
Connection status of an OCPP station.
Used by: OcppStationStatus.status
"unknown""configured""connected"
OcppForwarder
OCPP forwarder rules and upstream connection status.
Used by: State.ocppforwarder
Static configuration.
Runtime status.
OcppForwarderRule
A rule forwarding an OCPP station to an upstream backend.
Used by: OcppForwarder.config
CA certificate for TLS connections.
Skip TLS certificate verification.
Password for upstream authentication. Redacted.
Only forward read operations to the station.
Station id to forward.
Station id used towards the upstream backend.
URL of the upstream OCPP backend.
Username for upstream authentication.
OcppForwarderSession
Connection status of an OCPP forwarder rule.
Used by: OcppForwarder.status
Charger id.
Last connection error.
Connection to the upstream backend is established.
URL of the upstream OCPP backend.
OcppStationStatus
Connection status of an OCPP station.
Used by: OcppStatus.stations
Station id.
Connection status.
OcppStatus
OCPP server status.
Used by: Ocpp.status
Externally reachable URL of the OCPP server.
Connection status per configured station.
PhaseAction
Pending phase switching action in solar mode.
Used by: Loadpoint.phaseAction
"inactive""scale1p""scale3p"
PlanStrategy
Charging plan strategy.
Used by: Loadpoint.effectivePlanStrategy, Loadpoint.planStrategy, Vehicle.planStrategy
Force continuous charging without gaps.
Duration of uninterrupted charging directly before the target time, in seconds.
PvAction
Pending charge start or stop action in solar mode.
Used by: Loadpoint.pvAction
"inactive""enable""disable"
Rate
A time slot with an associated price or emission value.
Used by: Loadpoint.plan
End of the time slot.
Start of the time slot.
Price per kWh in the configured currency or emissions in g/kWh.
Remote
Remote access configuration and connection status.
Used by: State.remote
Static configuration.
Runtime status.
RemoteConfig
Remote access configuration.
Used by: Remote.config
Remote access is enabled.
RemoteStatus
Remote access connection status.
Used by: Remote.status
Connection to the remote access server is established.
Last connection error.
Last remote activity per client, keyed by username. RFC3339 timestamps.
Remote login attempts are currently blocked by the rate limiter.
Remote access URL.
RepeatingPlan
A repeating charging plan.
Used by: Vehicle.repeatingPlans
Plan is active.
SoC goal in %.
Target time in HH:MM format.
Time zone of the target time, like Europe/Berlin.
Weekdays the plan is active. 0 is Sunday, 6 is Saturday.
ShmConfig
SMA Home Manager configuration.
Used by: State.shm
SmartCostType
Type of the smart charging limit.
Used by: State.smartCostType
"co2""pricedynamic""priceforecast"
SolarDetails
Solar production forecast.
Used by: Forecast.solar
Expected production the day after tomorrow.
Correction factor applied to the forecast based on past production.
Expected production power over time.
Expected production today.
Expected production tomorrow.
Sponsor
Sponsorship status.
Used by: State.sponsor
Static configuration.
Runtime status.
SponsorStatus
Sponsorship status.
Used by: Sponsor.status
Expiry time of the sponsor token.
Sponsor token expires soon.
Name of the sponsor.
Sponsor token. Redacted.
StaticEnergyPlan
Charging plan with an energy goal.
Used by: StaticPlan
StaticPlan
Charging plan with a fixed target time and a SoC or energy goal.
Used by: Vehicle.plan
One of: StaticSocPlan | StaticEnergyPlan
StaticSocPlan
Charging plan with a SoC goal.
Used by: StaticPlan
Statistics
Charging statistics, keyed by time period.
Used by: State.statistics
StatisticsData
Aggregated charging statistics for a time period.
Used by: Statistics.30d, Statistics.365d, Statistics.thisYear, Statistics.total
Average CO₂ emissions in g/kWh.
Average energy price per kWh in the configured currency.
Total charged energy in kWh.
Share of solar energy in %.
TimeseriesEntry
A forecast value at a point in time as [ts, val] array. ts is unix seconds, val is power in W.
Used by: SolarDetails.timeseries
Vehicle
A configured vehicle.
Used by: State.vehicles
Usable battery capacity in kWh.
Feature flags of the vehicle implementation.
Vehicle icon name for UI display.
SoC limit in %. Charging stops when reached.
Minimum SoC in %. Vehicle is fast-charged until this level is reached.
Charge mode applied when the vehicle connects.
Unique vehicle name used in API routes and configuration.
Charging plan with a fixed target time and SoC or energy goal.
Charging plan strategy.
Repeating charging plans.
Vehicle title for UI display.