{"openapi":"3.1.0","info":{"title":"EV Charging API","version":"1.0.0","description":"Electric-vehicle charging maths as an API, computed locally and deterministically — the three numbers every EV driver and charging app actually needs. The charge-time endpoint gives how long a session takes: from the battery size and the gap between the starting and target state of charge it works out the energy to add and the time at a given charger power and efficiency — a 60 kWh battery from 20 % to 80 % on a 7.2 kW home charger at 90 % efficiency takes about 5.6 hours, and it reminds you that DC fast charging slows sharply above 80 % so road trips should be planned around the fast part of the curve. The range-added endpoint turns a charging session into miles: from the charger power, the minutes plugged in and the car's miles per kWh it gives the energy and range added, plus the handy \"miles per hour of charging\" figure — a 7 kW home charger adds roughly 22 mi/hr, a 150 kW DC station hundreds. The cost endpoint gives what a charge costs, correctly billing the energy drawn from the grid (the energy to the battery divided by the charging efficiency) times the price per kWh, with the effective cost per usable kWh — home overnight rates make EV miles very cheap while DC fast chargers cost several times more. Everything is computed locally and deterministically, so it is instant and private. Ideal for EV apps, route and trip planners, fleet and charging-station tools, charge-cost calculators and dashboards. Pure local computation — no key, no third-party service, instant. Estimates — real DC charging tapers above 80 % and cold weather cuts range. 3 compute endpoints. For battery runtime use a battery API; for generic energy cost use an energy-cost API.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/evcharging-api","description":"oanor gateway"}],"tags":[{"name":"Charging"},{"name":"Meta"}],"components":{"securitySchemes":{"oanorKey":{"type":"apiKey","in":"header","name":"x-oanor-key","description":"Get your key at https://www.oanor.com/developer/keys"}}},"security":[{"oanorKey":[]}],"paths":{"/v1/charge-time":{"get":{"operationId":"get_v1_charge_time","tags":["Charging"],"summary":"Charge time between two states of charge","description":"","parameters":[{"name":"battery_kwh","in":"query","required":true,"description":"Battery capacity (kWh)","schema":{"type":"string"},"example":"60"},{"name":"start_pct","in":"query","required":true,"description":"Start state of charge %","schema":{"type":"string"},"example":"20"},{"name":"target_pct","in":"query","required":true,"description":"Target state of charge %","schema":{"type":"string"},"example":"80"},{"name":"charger_kw","in":"query","required":true,"description":"Charger power (kW)","schema":{"type":"string"},"example":"7.2"},{"name":"charge_efficiency_pct","in":"query","required":false,"description":"Charging efficiency % (default 90)","schema":{"type":"string"},"example":"90"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Charge time = the energy to add (battery × the % gap) ÷ the charger power × efficiency. Real DC fast charging slows sharply above ~80 % to protect the cells, so 20→80 % is far quicker than 80→100 % — plan road trips around the fast part of the curve. AC home charging is roughly linear.","inputs":{"start_pct":20,"charger_kw":7.2,"target_pct":80,"battery_kwh":60,"charge_efficiency_pct":90},"charge_time_hours":5.56,"charge_time_minutes":333,"energy_to_battery_kwh":36},"meta":{"timestamp":"2026-06-06T23:53:56.181Z","request_id":"c2c8ea33-f3d6-46e8-964d-d33892f11609"},"status":"ok","message":"Charge time","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/cost":{"get":{"operationId":"get_v1_cost","tags":["Charging"],"summary":"Charge cost including losses","description":"","parameters":[{"name":"energy_to_battery_kwh","in":"query","required":true,"description":"Energy added to the battery (kWh)","schema":{"type":"string"},"example":"36"},{"name":"price_per_kwh","in":"query","required":true,"description":"Electricity price per kWh","schema":{"type":"string"},"example":"0.15"},{"name":"charge_efficiency_pct","in":"query","required":false,"description":"Charging efficiency % (default 90)","schema":{"type":"string"},"example":"90"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"You pay for the energy drawn from the grid, which is the energy to the battery ÷ the charging efficiency (~85–95 %), times the price. Home overnight rates make EV miles very cheap; DC fast chargers cost several times more per kWh, so charge at home when you can and use fast charging for trips.","inputs":{"price_per_kwh":0.15,"charge_efficiency_pct":90,"energy_to_battery_kwh":36},"grid_kwh":40,"charge_cost":6,"cost_per_kwh_to_battery":0.167},"meta":{"timestamp":"2026-06-06T23:53:56.277Z","request_id":"b1f28584-c787-400d-ae64-9dc4055546ee"},"status":"ok","message":"Charge cost","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/range-added":{"get":{"operationId":"get_v1_range_added","tags":["Charging"],"summary":"Range added over a session","description":"","parameters":[{"name":"charger_kw","in":"query","required":true,"description":"Charger power (kW)","schema":{"type":"string"},"example":"7.2"},{"name":"minutes","in":"query","required":true,"description":"Minutes plugged in","schema":{"type":"string"},"example":"60"},{"name":"mi_per_kwh","in":"query","required":false,"description":"Car efficiency (mi/kWh, default 3.5)","schema":{"type":"string"},"example":"3.5"},{"name":"charge_efficiency_pct","in":"query","required":false,"description":"Charging efficiency % (default 90)","schema":{"type":"string"},"example":"90"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Range added = the energy that reaches the battery (charger kW × time × efficiency) × the car's miles per kWh (~3–4 for a typical EV, less for a truck or in the cold). The handy figure is miles per hour of charging — a 7 kW home charger adds ~22 mi/hr, a 150 kW DC station hundreds.","inputs":{"minutes":60,"charger_kw":7.2,"mi_per_kwh":3.5,"charge_efficiency_pct":90},"range_added_mi":22.7,"energy_added_kwh":6.48,"miles_per_hour_of_charge":23},"meta":{"timestamp":"2026-06-06T23:53:56.387Z","request_id":"f84b82b4-7783-4c5f-8214-a2d66c52ef94"},"status":"ok","message":"Range added","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/meta":{"get":{"operationId":"get_v1_meta","tags":["Meta"],"summary":"Spec","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"notes":"kWh, kW, miles. time = (battery × %gap) ÷ (kW × efficiency); range = kW × time × eff × mi/kWh; cost = (energy ÷ efficiency) × price. Estimates — DC fast charging tapers above 80 %, and cold weather cuts range. For battery runtime use a battery API.","service":"evcharging-api","endpoints":{"GET /v1/cost":"Cost of a charge including charging losses.","GET /v1/meta":"This document.","GET /v1/charge-time":"Time to charge from a start % to a target % at a charger power.","GET /v1/range-added":"Range added over a session and miles per hour of charging."},"description":"EV-charging maths: time to charge between two states of charge, range added over a session, and the cost of a charge."},"meta":{"timestamp":"2026-06-06T23:53:56.464Z","request_id":"18357167-b8ef-43cc-a360-e84ba8a35b14"},"status":"ok","message":"Meta","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}}},"x-oanor-pricing":[{"slug":"free","name":"Free","price_cents_month":0,"monthly_call_quota":5400,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":1290,"monthly_call_quota":61000,"rps_limit":6,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":3990,"monthly_call_quota":249000,"rps_limit":15,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":11900,"monthly_call_quota":1290000,"rps_limit":40,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/evcharging-api"}