Battery percentage looks like a simple field. An API returns a number, and an application draws a gauge. The difficulty begins when the application turns that number into a charging schedule, an energy estimate, or a claim about vehicle readiness. A useful integration needs to understand what was measured, when it was measured, and which conclusions the reading can support.
This guide focuses on interpreting telemetry and presenting calculations honestly. The figures below are illustrative engineering examples. For the broader integration context, see the battery charge API overview.
Give each battery quantity its own meaning
State of charge, usually shortened to SOC, expresses a reported charge level relative to the capacity basis used by the source. A value of 60% is a proportion. It is not itself an energy measurement, a charging speed, or an assessment of battery condition. Before combining providers, check whether their fields represent the same underlying concept.
Energy is commonly expressed in kilowatt-hours, or kWh. Power is commonly expressed in kilowatts, or kW. Power describes a rate of energy transfer; energy describes an amount. Battery health is another concept, concerned with condition or capability relative to a reference. A high SOC reading does not establish high battery health.
Keep these quantities in separately named fields. Prefer explicit names such as state_of_charge_percent, charging_power_kw, and energy_added_kwh in your own normalized model. If a provider supplies a health measure, preserve its definition and methodology instead of treating every field called health as interchangeable.
A useful question for a schema review is whether a developer could mistake the field for a different unit or measurement. If the answer is yes, improve the name and description before building calculations around it.
Attach time and provenance to every observation
A battery reading needs a vehicle identifier, a source, a value, a unit, and a timestamp with documented meaning. Where possible, store both the observation time supplied by the source and the time your system received it. A recent network response does not by itself explain when the underlying value was obtained.
Suppose a dashboard receives 58% at 10:15, but the observation was made at 10:02. Showing “58%, updated now” hides thirteen minutes of age. Showing “58%, reported at 10:02” communicates the evidence directly. If the source does not provide an observation time, use a label such as “Retrieved at 10:15; observation time unavailable.”
Define how long a reading remains suitable for each product feature. A historical chart can retain an old observation indefinitely within your retention policy, while a present charging estimate may require recent data. Expiring confidence should not erase useful history or transform an old percentage into a new value.
The car battery charge API guide provides further context for separating vehicle measurements from the assumptions an application adds.
Validate values without rewriting the evidence
Check data types, units, timestamp formats, and documented ranges at the adapter boundary. A source returning 0.72 might mean a fraction representing 72%, while another returning 72 might already use percent. Perform conversion only from the documented contract. Guessing from a single observation will eventually misinterpret a legitimate low reading.
Keep missing, invalid, and zero values distinct. Zero can be a real reported measurement. Missing means no usable value was supplied. Invalid means a supplied value could not be accepted under the agreed rules. A user interface can explain those conditions without replacing them all with an empty gauge.
Handle surprising changes as a data question
If two nearby observations jump from 41% to 84%, preserve the source values while checking ordering, account association, units, and timestamps. Do not immediately smooth the jump away or claim a battery fault. A quality flag can stop the new reading from driving an estimate until the discrepancy is understood.
Likewise, retain enough precision for calculations while displaying only useful precision. A gauge showing 62.137% suggests confidence the source may not support. Rounding for presentation should not overwrite the stored observation.
Know which capacity your calculation assumes
Converting a percentage difference into energy requires a capacity assumption. That capacity must use a basis compatible with the reported SOC. A manufacturer's headline capacity, a usable capacity field, and an application estimate may describe different things. Store the chosen basis alongside the result so another developer can reproduce it.
For a deliberately simplified example, assume a usable capacity of 60 kWh and a starting SOC of 40%. A target of 70% represents a difference of 30 percentage points. Multiplying 60 kWh by 0.30 gives 18 kWh. That is the estimated increase in stored energy under the stated assumptions.
The calculation does not establish how much electricity a charger must deliver or a meter will record. Keep energy measured at the charger, energy estimated inside the battery, and billed energy as distinct quantities unless a documented source makes their relationship explicit. If capacity is unknown, a percentage based progress display can remain useful without inventing an energy amount.
Explain charging time as a conditional estimate
The Department of Energy's charging equipment overview identifies battery state of charge, capacity, battery type, vehicle charging capability, and charging equipment as factors affecting charging time. That context is why dividing an energy estimate by a charger label should be presented as a simplified calculation, not a promised completion time.
Continue the example with 18 kWh of estimated energy needed. If average power reaching the battery were a constant 6 kW, the calculation would be 18 kWh divided by 6 kW, giving three hours. At an assumed average of 4.5 kW, it would give four hours. Both results depend on the chosen average power actually describing the relevant charging period.
These are scenarios, not measured predictions for a particular vehicle. They omit changes in power and other effects not represented in the inputs. A momentary power reading also cannot establish the average for the remainder of a session. Present the assumptions next to the estimate and recompute when new evidence changes them.
A useful interface might say “Illustrative estimate: about three hours at an assumed average battery power of 6 kW.” If recent power data is unavailable, do not silently substitute the station's advertised maximum and retain the same confidence label.
Keep targets, limits, and observations separate
A requested target describes what someone wants. A configured limit describes a setting reported by the source. The observed SOC describes a measurement. These fields can differ without contradiction, and your data model should allow all three to coexist.
Suppose a user chooses a 75% target while the last reported configured limit is 70%. The interface should expose the mismatch before using 75% in a completion estimate. If your application supports changing settings, show the command outcome separately and wait for appropriate confirmation before presenting the new setting as observed.
When the target is at or below the current reported SOC, show that the requested level is already met within the measurement's limits. Do not produce a negative charging duration. That simple boundary check makes the calculation more understandable without making a claim about whether the vehicle is ready for every intended trip.
Design charts and alerts around evidence
Draw gaps when observations are missing. Connecting two distant points with a smooth line can suggest continuous knowledge that you do not have. If you interpolate for an analytical view, label the interpolation and preserve the original observation markers.
For a threshold notification, define how recent the reading must be and whether repeated confirmation is needed. Record the observation that triggered the message so support can explain it later. A stale reading should not repeatedly generate what looks like a new event. The developer resources can help organize these acceptance rules.
Make the number understandable before making it actionable
Responsible SOC handling starts with a precise field definition and ends with a reader who understands the limits of the result. Keep percentages, energy, power, health, targets, and timestamps distinct. Preserve missing values and label every derived assumption. Those choices support useful dashboards and explainable calculations while avoiding certainty that the telemetry itself cannot provide. Explore the EV charging API guide when connecting battery readings to a wider charging workflow.
