EV Routing

The EV Routing API extends Directions with electric vehicle parameters — battery capacity, current charge level, and consumption modeling. Plaza calculates energy usage along the route accounting for elevation changes, speed, and auxiliary systems.

EV Routing is a premium endpoint — each request counts as 4x.

Endpoint

POST /api/v1/route

EV routing uses the same endpoint as standard directions. Include the ev object to activate EV-aware routing.

Request body

All standard Directions parameters apply, plus:

Field	Type	Default	Description
ev.battery_capacity_wh	number	—	Required. Total battery capacity in watt-hours (e.g., 75000 for 75 kWh).
ev.initial_charge_pct	number	0.8	Starting charge as a fraction 0–1 (e.g., 0.8 = 80%).
ev.min_charge_pct	number	0.10	Minimum acceptable charge at destination as a fraction 0–1.
ev.min_power_kw	number	—	Minimum charger power in kilowatts (filters out slower chargers).
ev.connector_types	string[]	—	Acceptable connector types (e.g., ["ccs", "chademo"]).

Basic request

curl -X POST https://plaza.fyi/api/v1/route \
  -H "x-api-key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": { "type": "Point", "coordinates": [-73.9857, 40.7484] },
    "destination": { "type": "Point", "coordinates": [-77.0369, 38.9072] },
    "mode": "auto",
    "ev": {
      "battery_capacity_wh": 75000,
      "initial_charge_pct": 0.9,
      "min_charge_pct": 0.10
    }
  }'

import Plaza from "@plazafyi/sdk";

const client = new Plaza();

const route = await client.v1.route({
  origin: { type: "Point", coordinates: [-73.9857, 40.7484] },
  destination: { type: "Point", coordinates: [-77.0369, 38.9072] },
  mode: "auto",
  ev: {
    battery_capacity_wh: 75000,
    initial_charge_pct: 0.9,
    min_charge_pct: 0.1,
  },
});

console.log(`Energy used: ${route.properties.energy_used_wh} Wh`);

import plaza

client = plaza.Client()

route = client.v1.route(
    origin={"type": "Point", "coordinates": [-73.9857, 40.7484]},
    destination={"type": "Point", "coordinates": [-77.0369, 38.9072]},
    mode="auto",
    ev={
        "battery_capacity_wh": 75000,
        "initial_charge_pct": 0.9,
        "min_charge_pct": 0.10,
    },
)
print(f"Energy used: {route['properties']['energy_used_wh']} Wh")

Response

The response includes standard Directions fields plus EV-specific properties:

{
  "type": "Feature",
  "geometry": {
    "type": "LineString",
    "coordinates": [[-73.9857, 40.7484], "...", [-77.0369, 38.9072]]
  },
  "properties": {
    "distance_m": 365000,
    "duration_s": 14400,
    "energy_used_wh": 52000,
    "charging_stops": [],
    "charge_profile": [
      [0, 0.9],
      [100000, 0.65],
      [200000, 0.42],
      [365000, 0.21]
    ]
  }
}

Property	Type	Description
energy_used_wh	number	Total energy consumed in watt-hours.
charging_stops	array	Recommended charging stops along the route.
charge_profile	array	[distance_m, charge_pct] pairs showing battery level at intervals.

Energy consumption model

Plaza models energy consumption based on:

• Base consumption: 180 Wh/km on flat terrain
• Elevation gain: +80 Wh per 100m of ascent
• Regenerative braking: 15% energy recovery per 100m of descent
• Auxiliary systems: +10 Wh/km (climate control, lights, etc.)
• Speed penalty: Consumption increases above 90 km/h (+0.5% per km/h over)

Filtering chargers

Use min_power_kw and connector_types to control which chargers are considered:

curl -X POST https://plaza.fyi/api/v1/route \
  -H "x-api-key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": { "type": "Point", "coordinates": [-73.9857, 40.7484] },
    "destination": { "type": "Point", "coordinates": [-77.0369, 38.9072] },
    "mode": "auto",
    "ev": {
      "battery_capacity_wh": 75000,
      "initial_charge_pct": 0.85,
      "min_charge_pct": 0.10,
      "min_power_kw": 50,
      "connector_types": ["ccs"]
    }
  }'