# ⚡ EV Smart Routing API

Performs a route calculation **dedicated to electric vehicles**.
If the vehicle does not have enough autonomy, the service **adds charging stations (step points)** along the route.

> The criteria by default is `FASTEST`, the service optimizes the **total duration** (driving + charging time).


## 🌐 Endpoint


```
POST /bgis/service/2.0/evsmartrouting
```

## 🚗 Example : EV Smart Routing – Paris → Brussels

🔋 **Electric Vehicle** : Kia e-Niro 64kWh

🔌 **Charging Station Provider**: ecoMovement

🌍 **Geoserver Provider**: osm

📤 **Request JSON**


```
{
  "geoserver": "osm",
  "csps": ["ecoMovement"],
  "vehicle": {
    "initBatLvl": 100,
    "key": "eb1e9464-8654-4c01-bedd-b2f95412a60d"
  },
  "routingMode": "MODE_VIAS",
  "start": {
    "lon": 2.35222,
    "lat": 48.85661
  },
  "stop": {
    "lon": 4.35171,
    "lat": 50.85034
  },
  "condition": {
    "chargePluggingTime": 300,
    "geometry": true
  },
  "routingVehicleProfile": {
    "transportMode": "CAR"
  }
}
```

✅ **What it does:**

- Computes a route from Paris to Brussels
- Starts with 100% battery
- Adds a fixed 5-minute stop time at each charging station
- Uses the default vehicle profile for a car
- Minimal setup – easy to test and expand later


## 🧾 Headers

| Header | Value |
|  --- | --- |
| Content-Type | `application/json` |
| Accept | `application/json` |
| Authorization | `Bearer YOUR_TOKEN` |


## 📥 Request Body

### 🧩 Fields

| Field | Type | Optional | Description |
|  --- | --- | --- | --- |
| `geoserver` | `string` | Yes | Geoserver name (e.g., `"here"`) |
| `csps` | `string[]` | Yes | Charging station provider names (e.g., `"gireve"`) |
| `vehicle` | `object` | No | Electric vehicle configuration |
| `start` | `object` | No | Start coordinates |
| `stop` | `object` | No | Destination coordinates |
| `condition` | `object` | Yes | Trip and EV-related conditions |
| `csfs` | `string[]` | Yes | Filters applied to charging stations |
| `vias` | `object[]` | Yes | List of via points |
| `swidx` | `int` | Yes | Switch index |


**Example**


```
{
  "geoserver": "osm",
  "csps": ["ecoMovement"],
  "vehicle": {
    "key": "06b5c02d-ba2e-4b14-8b2b-6d793aac0da0",
    "initBatLvl": 80,
    "payload": 100
  },
  "start": { "lon": 2.3522, "lat": 48.8566 },
  "stop": { "lon": 5.0415, "lat": 47.3220 },
  "condition": {
    "minBatLvl": 10,
    "minArrivalBatLvl": 15,
    "temperature": 20,
    "departureTime": "2025-07-04T08:00:00+01:00",
    "encodedGeometry": true
  },
  "vias": [
    { "lon": 3.0, "lat": 48.0 }
  ],
  "swidx": 0
}
```

## 📍 Place

Describes the coordinates of a place, such as a start or stop point. See field details below.

### 🧩 Fields

| Field | Type | Optional | Description |
|  --- | --- | --- | --- |
| `lat` | `double` | No | Latitude |
| `lon` | `double` | No | Longitude |



```
{ "lon": 5.0415, "lat": 47.3220 }
```

## 🚗 Vehicle

Class representing a Vehicle. Fields details:

### 🧩 Fields

| Field | Type | Optional | Description |
|  --- | --- | --- | --- |
| `key` | `string` | No | Vehicle UUID key (from EV vehicle API) |
| `initBatLvl` | `float` | Yes | Initial battery level (%) – Default: 100 |
| `payload` | `int` | Yes | Payload in kg – Default: 75 kg |



```
"vehicle": {
  "key": "06b5c02d-ba2e-4b14-8b2b-6d793aac0da0",
  "initBatLvl": 75,
  "payload": 80
}
```

## 📦 Condition

Defines the conditions of the EV smart routing trip, including routing options, energy constraints, environmental factors, and rendering settings.

### 🧩 Field

| Field | Optional | Description |
|  --- | --- | --- |
| [`allowMaxSpeedRecommendation`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_allowMaxSpeedRecommendation_tutorial) | Yes | Allow to calculate the maximum speeds to reach destination or step-point. Since algorithm v3. Type: `boolean`. |
| [`allowNaStatus`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_allowNaStatus_tutorial) | Yes | Allow use of pools with NA availability status. `False` by default. Type: `boolean`. |
| [`alternative`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_alternative_tutorial) | Yes | Index of alternative route. 0 to disable. 0 by default. Type: `byte`. |
| [`chargePluggingTime`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_chargePluggingTime_tutorial) | Yes | Defines the fixed additional time in seconds for each charging stop. 300 by default. Type: `int`. |
| [`chargeTimeSlots`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_chargeTimeSlots_tutorial) | Yes | List of step-point time slots. If forced charges are defined, they take priority. Type: list of [ChargeTimeSlotFront]. |
| [`chargingStationDeprecatedConnector`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_chargingStationDeprecatedConnector_tutorial) | Yes | Enable support for deprecated connector types. False by default. Type: `boolean`. |
| [`co2emissions`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_co2emissions_tutorial) | Yes | Calculate CO₂ emissions savings for the journey. `False` by default. Type: `boolean`. |
| [`connectorTypes`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_connectorTypes_tutorial) | Yes | [List of connector type IDs to filter charging stations](/glossary/ev_connector_types#ev_connector_types). Type: list of Integer. |
| [`currency`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_currency_tutorial) | Yes | Currency for cost calculation ([ISO 4217 Code](https://fr.wikipedia.org/wiki/ISO_4217)). Type: `String`. Example:- `'EUR'`- `'USD'`- `'JPY'` |
| [`departureTime`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_departureTime_tutorial) | Yes | Departure timestamp (Epoch ms or [ISO 8601](https://fr.wikipedia.org/wiki/ISO_8601)). Type: `String`. |
| [`drivingStyle`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_drivingStyle_tutorial) | Yes | Driving behavior model. Type: [DrivingStyleFront]. |
| [`encodedGeometry`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_encodedGeometry_tutorial) | Yes | Enables encoded polyline output. `False` by default. Type: `boolean`. |
| [`criterias`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_criterias_tutorial) | Yes | List of routing criteria. Available values :- `AVOID_CROSSING_BORDER` - `AVOID_FERRIES` - `AVOID_MOTORWAYS` - `AVOID_TOLLS` - `TRAFFIC` |
| [`geometry`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_geometry_tutorial) | Yes | Enables polyline output. True by default. Type: `boolean`. |
| [`ignoreAvailableStatus`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_ignoreAvailableStatus_tutorial) | Yes | Use any station regardless of availability. `False` by default. Type: `boolean`. |
| [`maxAfterChargeBatLvl`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_maxAfterChargeBatLvl_tutorial) | Yes | Maximum battery level after charge (%). Type: `float`. |
| [`minArrivalBatLvl`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_minArrivalBatLvl_tutorial) | Yes | Minimum required battery at destination (%). Type: `float`. |
| [`minBatLvl`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_minBatLvl_tutorial) | Yes | Minimum battery level during the trip (%). Type: `float`. |
| [`optimMode`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_optimMode_tutorial) | Yes | Optimization mode Available values :- `ECO_ENERGY`- `FASTEST` (Default)- `SHORTEST`). |
| [`restrictedEvse`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_restrictedEvse_tutorial) | Yes | Accept restricted charging stations. Type: `boolean`. |
| [`routeDetails`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_routeDetails_tutorial) | Yes | Enable detailed route events (e.g., consumption). `False` by default. Type: `boolean`. |
| [`routeDetailsExtKey`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_routeDetailsExtKey_tutorial) | Yes | API key to unlock extended route details. Type: `String`. |
| [`routeDetailsFreq`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_routeDetailsFreq_tutorial) | Yes | Frequency (s) of route events. Default 60s. Type: `int`. |
| [`routesheet`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_routesheet_tutorial) | Yes | Enables generation of a route sheet. Type: `boolean`. |
| [`routesheetLanguage`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_routesheetLanguage_tutorial) | Yes | Language for route sheet rendering. Type: `String`. |
| [`routesheetMode`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_routesheetMode_tutorial) | Yes | Output format :- `TEXT` (Default)- `DETAILS`- `TEXT_DETAILS`. |
| [`routesheetVerboseLevel`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_routesheetVerboseLevel_tutorial) | Yes | Verbosity level :- `LOW`- `MEDIUM`- `HIGH`. |
| [`temperature`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_temperature_tutorial) | Yes | Temperature in Celsius. Default: 20. Type: `int`. |
| [`weather`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_weather_tutorial) | Yes | Enable real-time weather data. Type: `boolean`. |
| [`weatherProvider`](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_weatherProvider_tutorial) | Yes | Choose weather data provider. Type: `String`. |


**Example**


```
{
  "departureTime": "2025-07-03T10:00:00+02:00",
  "temperature": 25,
  "minArrivalBatLvl": 15,
  "minBatLvl": 10,
  "encodedGeometry": true,
  "chargePluggingTime": 300,
  "optimMode": "FASTEST",
  "currency": "EUR"
}
```

## 🚗 DrivingStyle

The `DrivingStyle` object defines how the electric vehicle is driven, affecting the energy consumption during the route.

### 🧩 Fields

| Field | Optional | Description |
|  --- | --- | --- |
| mode |  | Defines the driving mode. **Available values:** CUSTOM: Allow to override ponderation parameters.ECO: Reduce acceleration and prefer national roads.NORMAL: Use standard speed limits.SPORT: Increase acceleration, prefer highways. |
| allowOverVehSpdLim | Yes | Allows to define a maximum speed above the vehicle's maximum speed defined in the vehicle's database. Type: `boolean`. |
| limitMaxSpeed | Yes | Vehicle's max speed in km/h used during routing. If null, default from vehicle database is used. Type: `short`. |
| maxAcc | Yes | Average vehicle's acceleration in m/s². Must be > 0. Example: `1.25`. Type: `double`. |
| maxDec | Yes | Average vehicle's deceleration in m/s². Must be < 0. Example: `-1.25`. Type: `double`. |
| sps | Yes | Speed weight coefficient per road network level. Type: `list` of [SpeedPonderation](#speedponderationfront). |



```json
{
  "mode": "ECO",
  "allowOverVehSpdLim": false,
  "limitMaxSpeed": 110,
  "maxAcc": 1.2,
  "maxDec": -1.2,
  "sps": [
    {
      "factor": 0.9,
      "level": 2,
      "pondType": "ALL",
      "roadType": "MOTORWAY"
    },
    {
      "factor": 1.1,
      "level": 3,
      "pondType": "ETA",
      "roadType": "DEFAULT"
    }
  ]
}
```

👉 For detailed examples and usage, [check out the tutorial](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_drivingStyle_tutorial)

## 🛣️ SpeedPonderation

Used inside `sps`, represents the speed ponderation per road level.

### 🧩 Fields

| Field | Optional | Description |
|  --- | --- | --- |
| `factor` |  | Ponderation factor for speed. (Default = 1)Example: `0.8` (reduce), `1.3` (increase). Type: `float`. |
| `level` |  | Road network level. **Values:** 0 (all), 1 (main), 2 (secondary), 3 (third), 4 (fourth). Type: `int`. |
| `pondType` | Yes | Ponderation type. **Values:**- `ALL` (default)- `CAL`- `ETA`.. |
| `roadType` | Yes | Road type for ponderation. **Values:**- `ALL`- `DEFAULT`- `FERRY`- `MOTORWAY`- `PEDESTRIAN`- `ROUNDABOUNT`- `SLIPROAD` |



```json
{
  "factor": 0.85,
  "level": 1,
  "pondType": "CAL",
  "roadType": "MOTORWAY"
}
```

👉 For detailed examples and usage, [check out the tutorial](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_SpeedPonderationFront_tutorial)

## 🧭 Via

Describes a coordinate used as a via (waypoint) in EV Smart Routing.

### 🧩 Fields

| Field | Type | Optional | Description |
|  --- | --- | --- | --- |
| `lat` | double | No | Latitude in decimal degrees (WGS84). |
| `lon` | double | No | Longitude in decimal degrees (WGS84). |
| `chargeMaxDistance` | int | Yes | Maximum distance in meters from a charge point to force a charge. Default is `0`. |
| `ignoreVehicleProfile` | boolean | Yes | Whether to ignore the vehicle profile for this via. |
| `maxSpeed` | int | Yes | Max speed in km/h for the segment after this via. `0` means global speed is used. |
| `stopDuration` | int | Yes | Stop duration in seconds at this via point. Default is `0`. |
| `transportType` | string | Yes | Type of transport. **Options :** - `BICYCLE`- `CAR`- `DELIVERY_TRUCK`- `EMERGENCY`- `MOTORCYCLE`- `PEDESTRIAN`- `PUBLIC_BUS`- `TAXI`- `TRUCK`. |


**💡 Example**


```
{
  "lat": 45.764043,
  "lon": 4.835659,
  "chargeMaxDistance": 3000,
  "ignoreVehicleProfile": false,
  "maxSpeed": 90,
  "stopDuration": 600,
  "transportType": "CAR"
}
```

👉 For detailed examples and usage, [check out the tutorial](/api-reference/ev-move---electric-mobility/evsmartrouting/tutorial/evsmartrouting_condition#evsmartrouting_tutorial)

🔗 [Back to API Index](/api-reference/routing/routing)

## 🔗 API Playground

You can test this API endpoint directly in our dedicated BeMap documentation environment.

👉 [Go to BeMap API Playground](https://bemap-prod.benomad.com/bgis/documentation/#subpage-rest_2_0_0-examples-evsmartrouting-service-v2_0_0.md)