---
title: EV Routing | Plaza Docs
description: Range-aware directions for electric vehicles with energy consumption modeling and charging stop planning.
---

The EV Routing API extends [Directions](/guides/directions/index.md) 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](/guides/authentication#premium-endpoints/index.md) — 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](/guides/directions/index.md) 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

Terminal window

```
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](/guides/directions/index.md) 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:

Terminal window

```
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"]
    }
  }'
```