# EV routing

The EV routing features of the API extend the routing service with electric vehicle specific options. Routing responses can contain details of energy consumption of the vehicle on the route. Route calculations can also add charging stations to the route, to ensure that destination can be reached without running out of energy, while still optimizing the result for overall travel and charging time.

For code samples, see these tutorials:

## Consumption model

The Routing API allows you to specify vehicle specific parameters, which are then used to calculate energy consumption for the vehicle on a given route.

Unless specified otherwise, the energy is assumed to be in Wh.

### Consumption calculation formula

In this model, consumption ($$C$$) along the segment depends on the length, speed and elevation difference.

$C = P_{asc} \cdot \Delta h_+ + P_{desc} \cdot \Delta h_- + P_{speed} \cdot L + P_{aux} \cdot t$

#### Request and Model Parameters

The following request parameters define the consumption model for consumption calculation:

Request Parameter Model Parameter Mandatory Description
ascent $$P_{asc}$$ Energy in Wh consumed per meter rise in elevation.
descent $$P_{desc}$$ Energy in Wh recovered per meter fall in elevation.
freeFlowSpeedTable $$P_{speed}$$ Yes Function curve specifying consumption rate at a given free flow speed on a flat stretch of road. For details, see Consumption speed table.
trafficSpeedTable $$P_{speed}$$ Function curve specifying consumption rate at a given speed under traffic conditions on a flat stretch of road. For details, see Consumption speed table.
auxiliaryConsumption $$P_{aux}$$ Energy in Wh consumed by the vehicle's auxiliary systems (for example, air conditioning, lights) per second of travel.

#### Map Parameters

The following parameters are taken from the map data to support the consumption calculation:

Parameter Description
$$L$$ Length of the segment in meters.
$$\Delta h_+$$ Elevation difference between the end and the start of the segment in meters if positive, otherwise zero.
$$\Delta h_-$$ Elevation difference between the end and the start of the segment in meters if negative, otherwise zero.
$$t$$ Travel time along the segment in seconds.

### Consumption speed table

Refer to Consumption speed table for details.

To obtain energy consumption of the electric vehicle, add details of a consumption model to the request. All request parameters related to EV vehicles start with the prefix ev.

For sample requests, see these sections:

## Charge levels along the route

On top of the Consumption Model, the Routing API allows you to specify the battery parameters of a vehicle to return the charge levels at each waypoint along the route including the final destination.

Request Parameter Mandatory Description
initialCharge Yes Charge level in kWh of the vehicle's battery at the start of the route

## Charging time at a charging station

The Routing API allows you to specify the charging parameters of a vehicle as well as charging preferences of a user to calculate the charging time at a charging station.

Charging parameters of a vehicle:

Request Parameter Mandatory Description
maxCharge Yes Total capacity of the vehicle's battery (in kWh).
chargingCurve Yes Function curve describing the maximum battery charging rate (in kW) at a given charge level (in kWh). For details, see Charging time calculation.
maxChargingVoltage Maximum charging voltage supported by the vehicle's battery (in Volt). For details, see Charging time calculation.
maxChargingCurrent Maximum charging current supported by the vehicle's battery (in Ampere). For details, see Charging time calculation.
maxChargeAfterChargingStation Yes Maximum charge to which the battery should be charged at a charging station (in kWh).

Charging preferences of a user:

Request Parameter Mandatory Description
minChargeAtChargingStation Minimum charge when arriving at a charging station (in kWh).
minChargeAtFirstChargingStation Minimum charge when arriving at a first charging station (in kWh).
minChargeAtDestination Minimum charge at the final route destination (in kWh).
chargingSetupDuration Time spent (in seconds) after arriving at a charging station but before actually charging. For example, time spent for payment processing.

### Charging time calculation

chargingCurve is the main parameter to describe the speed of charging the battery. chargingCurve specifies the maximum power that can be accepted by the battery at a given state of its charge. If the battery has more fine-grained limitations on components of the power - namely voltage and current - then the request can specify these limitations by means of the optional maxChargingVoltage and maxChargingCurrent parameters.

These two parameters can better estimate the effective power of charging when charging stations offer voltage and current outside of acceptable range for the battery, while the offered power is still within this range.

Charging time is calculated with a charging efficiency of 0.9. If a charging station's supported voltage is less than 800V but the vehicle's maxChargingVoltage is higher than this, the power of the station will be limited to 45kW for calculating the charge time. Also a charging efficiency of 0.8 will be used for such stations. This is to account for the fact that higher-native-voltage vehicles cannot draw the rated power when connected to a lower voltage stations.

Example: Battery charging curve: constant charging at 150kW Battery max voltage: 400V Charging Station A: output power 150kW, voltage 800V, current 187.5A. Charging Station B: output power 150kW, voltage 400V, current 375A.

If the request does not specify the maximum voltage of the battery, then charging at station A will be assumed at the power of 150kW. However, due to the 400V limit, the effective power of charging is half as much: 400V * 187.5A = 75kW. For station B effective charging power will be the full 150kW, since its voltage is within the accepted range for the battery.

### Determining the maximum charge at a charging station

maxChargeAfterChargingStation allows to limit the maximum charge at a charging station during EV route planning. This parameter is aimed to specify the hardware limitation of the battery as suggested by the manufacturer. This parameter should not be used to instruct the EV routing algorithm about the "optimal" charge level.

The resulting charge value after visiting charging station may be lower than the value of this parameter. The algorithm considers various charge levels at each potential charging station, and tries to optimize the total route duration (travel time plus charging time) while ensuring that the route is reachable.

For example, if there is a fast but not reachable charging station on the route, the algorithm prefers first to charge at a slower station, but only to a level that enables it to reach the fast station. This way, the result is the best possible combination of driving and charging parts.

## Adding charging stations to ensure a reachable route

On top of the consumption model, the initial charge level, and the parameters to calculate the charging time, the Routing API allows you to request a reachable route optimized for the total travel and charging time. If necessary, charging stations are added to the route to achieve reachability.

Request Parameter Mandatory Description
makeReachable Yes When set to true, the router ensures that the calculated route is reachable within the given constraints.
connectorTypes Yes Comma-separated list of connector types that are compatible with the vehicle.
preferredBrands No Comma-separated list of charging station brand IDs. If makeReachable is set to true then charging stations from the specified brands will be preferred as potential charging stops, even if this makes the total route duration (travel time plus charging time) longer (up to 15 minutes per charging stop).

### Charging Stations

The Routing API only considers DC type stations, the reasons being the following:

1. Full charge at an AC station takes much longer (a few hours) and this does not fit the use case of EV Route planning with charging along the route.
2. The charging network of DC stations already provides sufficient coverage. For details, see Coverage / EV Routing.

The Routing API returns the Pool ID of the used charging station, that you can use to fetch full information about the charging station, including dynamic availability, with the HERE EV Charge Points API Specifically, the pool id can be used in HERE EV Charge Points API pool id resource

For sample requests, see these sections: