Battery State of Charge: Reading Telemetry Responsibly
Read battery state of charge with the right units, timestamps, and context. Learn how to handle missing telemetry and explain charging estimates without false precision.
7 min readAPI field guide / 05
CAR BATTERY CHARGE API
Turn vehicle battery observations into understandable information. Keep state of charge, charging power, energy, and battery health distinct in your data model and interface.
Which battery measurement answers your question?
“Battery charge” can refer to the reported state of charge, a charging session’s energy, or the rate at which energy is being supplied. These are different measurements. A car battery integration should name each field precisely, retain units and observation times, and avoid presenting an estimated value as a direct measurement.
Separate state of charge from battery health
State of charge describes a reported charge level at a point in time. It does not, by itself, diagnose a battery’s long-term condition. If your product needs health information, establish an appropriate source and definition for that separate requirement. A single charging observation should not turn into an unsupported maintenance or replacement recommendation.
Keep power and energy in different fields
Power describes a rate; energy describes an amount. A model that uses power_kw and energy_kwh makes the distinction visible to reviewers and helps prevent charting mistakes. Carry units through storage, transformation, and display. Document whether a session figure is measured at the equipment, reported by the vehicle, or calculated within your application.
Protect the timing of observations
A recently received event can still contain an older measurement. Keep observation time and ingestion time separate when the source permits it. Decide how to handle duplicated messages, out-of-order events, and implausible values before those cases appear in a driver’s interface. Preserve the evidence needed to investigate a disagreement between data sources.
Make estimates transparent
If you estimate energy from a percentage and an assumed capacity, record both the formula and the assumption. Treat it as a planning aid. Charging behavior, measurement limits, and changing conditions can make a simplified estimate unsuitable as a completion promise. Prefer a clear range or an explicitly uncertain state over a falsely precise countdown.
A practical data checklist
Use this as an evaluation framework for your own data contract. Field names and actual availability remain provider-specific.
| Area | What to examine | Design consideration |
|---|---|---|
| State of charge | soc_pct | A reported level, with source and observation time. |
| Power | power_kw | A rate of energy transfer, not accumulated energy. |
| Energy | energy_kwh | An amount, with a defined measurement boundary. |
| Provenance | source and observed_at | Keep measured and calculated values distinguishable. |
Primary reference
U.S. Department of Energy charging equipment guidance
DOE’s charging guidance provides background on charging equipment, charging rates, and factors that affect charging time.
From the Charge Journal
KEEP EXPLORING.
Smart Charging Basics: Sessions, Schedules, and Power Limits
Understand how smart charging joins session state, schedules, power limits, and telemetry while keeping accepted commands separate from confirmed charging behavior.
6 min read
EV Charging APIs: A Practical Developer Guide
Learn how to scope an EV charging integration, distinguish station data from vehicle telemetry and control, and build a workflow that handles uncertainty.
6 min readLet’s connect