BATTERY CHARGE API

How should a battery API model be organized?

A useful battery model starts with meaning rather than a long list of fields. Identify the subject, the observation, its source, its units, and its time. Then establish which values are direct reports and which are your own calculations. That structure makes it easier to use battery information across interfaces without disguising gaps or assumptions.

Define the subject of the observation

An electric vehicle’s traction battery, a device’s battery, and a charging session are not interchangeable subjects. Give each a clear identity and relationship in your application. A shared model can provide consistent names for common ideas, but it should not force every source to supply a field that it cannot meaningfully report.

Preserve missing information

Distinguish zero, unknown, unavailable, and not applicable. A zero power reading may be a valid observation; an absent power field says something else. Document how your application stores those states, how they appear in exports, and what the interface says when a reading cannot be refreshed. A consistent missing-data policy prevents many accidental false alarms.

Make normalization reversible

Keep the provider’s original units and identifiers alongside normalized fields when appropriate. This supports debugging and prevents a later schema change from becoming impossible to trace. Apply validation at the integration boundary, record the reason for rejected values, and avoid silently clamping unexpected readings into a plausible-looking range.

Choose the right level of detail

A charge percentage can be enough for a simple display. A diagnostic view may also need provenance, observation age, quality flags, and the transformation that produced a derived figure. Collect and expose the detail that serves the actual user task. More fields do not automatically create a better experience, especially when their definitions are unclear.

A practical data checklist

Use this as an evaluation framework for your own data contract. Field names and actual availability remain provider-specific.