A naive EV range estimate is battery_kwh ÷ consumption_per_km. That number is wrong in basically every real driving condition, because consumption isn't constant — it changes with temperature, HVAC use, driving style, and whether you're on the motorway or in stop-start city traffic. /ev-range models all four.
The baseline
Without a user-supplied consumption figure, the endpoint assumes 155 Wh/km for city driving or 200 Wh/km for motorway driving — motorway consumption is higher because aerodynamic drag dominates at speed, while city driving benefits from regenerative braking during stop-start traffic.
fetch("https://aplicious.com/api/v1/vehicles/ev-range?battery_kwh=75&motorway=true&temperature_c=5&driving_style=normal", {
headers: { "X-API-Key": "lapi_live_••••" },
});Three real-world adjustments most calculators skip
Driving style multiplies the baseline by 0.85 (eco), 1.0 (normal), or 1.25 (sport) — sport driving genuinely costs you up to 25% more range, not a rounding error.
Temperature applies a penalty below 10°C — lithium-ion batteries lose usable capacity in the cold, up to roughly +15% consumption at freezing — and a smaller penalty above 35°C, since battery thermal management also costs energy in extreme heat.
HVAC load adds a flat 15-25 Wh/km if ac_heating=true is set, with the higher figure applying below 10°C, since heating a cabin in cold weather costs meaningfully more energy than air conditioning in mild conditions.
State of charge and usable battery percentage
The endpoint also accounts for state_of_charge_pct(you're not always starting from 100%) and a configurable usable_battery_pct(defaulting to 90% — most EV battery packs reserve a buffer at the top and bottom of the charge curve that isn't usable range, to protect long-term battery health).
Putting together a trip planner
async function estimateRange(battery_kwh: number, conditions: { tempC: number; motorway: boolean; style: "eco"|"normal"|"sport" }) {
const params = new URLSearchParams({
battery_kwh: String(battery_kwh),
temperature_c: String(conditions.tempC),
motorway: String(conditions.motorway),
driving_style: conditions.style,
});
const res = await fetch(
`https://aplicious.com/api/v1/vehicles/ev-range?${params}`,
{ headers: { "X-API-Key": process.env.APLICIOUS_KEY! } }
);
return (await res.json()).data;
}Pair this with /fuel-cost (for the ICE-vehicle comparison) and /co2-emissionsif you're building an EV-vs-gas comparison tool rather than a range estimator alone.