This feature is in a preview state, the API is stable, feature changes could be introduced in future.
General Idea
With the fast-growing importance of alternative electric and hybrid vehicles in logistics it is vital to understand how these vehicles behave and to be able to use them in a standard routing use case.
The operating range of electric vehicles is not only affected by the vehicle's own properties such as its battery capacity, weight, rolling resistance etc. but also by external factors such as temperature, weather conditions and road gradient, all of which can significantly impact energy consumption. Charging takes much longer than refueling a petrol or diesel vehicle, so when and where to charge and for how long become crucial factors in a routing calculation.
Furthermore, unique to EVs is the possibility of recuperation, and so elevation variance takes on particular significance when routing for EVs.
Vehicle Database
Electric vehicle models are provided in a separate database and can be retrieved by the getVehicleModels method in the Data API.
Although there are a few general reference vehicles provided the idea is to have a collection of vehicle models based on existing vehicles.
Each vehicle contains data like:
- Manufacturer and model
- Vehicle type and variant
- Battery capacity and official range
- Maximum power consumption
- Charging capabilities and speed
Consumption Calculation
There are many factors which affect energy consumption for electric vehicles such as:
- Acceleration and deceleration
- Weight and rolling resistance
- Air drag
- Wind speed, temperature and weather conditions
- Grade resistance
- Power consumption at waypoints (e.g. tail lift, crane, cooling)
Elevation profile
Elevation changes, or the road gradient along the route, can have a substantial effect on energy consumption, not only increasing consumption but also contributing to energy recuperation. The effect is further enhanced by the (load) weight of the vehicle.
(Load) weight
The combined weight of the vehicle and its load can affect rolling resistance, grade resistance and acceleration factors. For instance acceleration will impact the energy consumption of an LCV less than it will for a fully loaded HGV, thus different road types can become more or less desirable depending on the overall weight when calculating a route.
Weather
Weather has an impact on energy consumption in various ways, both positive and negative. Temperature affects the battery performance, especially for smaller vehicles like LCVs and cargo bikes. Wind speed and wind direction affect air drag, especially for vehicles with a big silhouette. The amount of precipitation affects the rolling resistance.
The API provides input parameters to set current weather data at each waypoint. If no weather is specified and the start and arrival time are no more than 14 days in the future, weather will be used according to the forecast provided by Open-Meteo. Otherwise we default to 23°C with a wind speed of 0 km/h for the least impact on the energy consumption.
Power consumption at waypoints
The electricity consumption of electrical appliances used during service at each waypoint can be individually defined and accounted for. The energy consumed at a waypoint is removed from the battery at arrival, always before considering a possible charging stop at the same waypoint. This means that the state of charge prior to departure from one waypoint must be sufficient to cover both the subsequent leg's power requirements and any additional consumption at the next waypoint.
Charging
The consumption calculation supports charging at defined waypoints. If waypoints are provided with charging capability then charging will be incorporated in the route calculation automatically where necessary. Factors taken into consideration include:
- The maximum charging speed at the available charging station(s)
- The predicted state of charge when reaching a charging station (which will impact the charging speed)
- The minimum energy required to avoid dropping below the user-defined minimumStateOfCharge
- Whether it is possible to use service time for charging
The charging algorithm minimizes the additional time needed to charge the battery. Charging during the service time does not need additional time so charging stations where charging is possible during service time may be preferred over those where this is not possible. Similarly, charging with a higher charging power allows to charge the same amount in less time and therefore may be preferred.
The charging time is a proposal, currently for information only. It is not included in the travel time of the route and the start time of subsequent events is not offset by it. The execution of the proposed charge events may lead to inaccurate route results, that need to be considered when planning charging. The delayed departure at a waypoint with a charging station can lead to different issues, including inaccurate traffic conditions, differing toll costs due to time-dependent costs or inaccurate break and rest times.
The state of charge may fall below the defined minimum state of charge or even below zero, if the electricity consumption exceeds the available energy in the battery and charging is not possible before falling below zero. In this case a warning will be added to the response, informing that the route may not be feasible. The reported state of charge is not limited to zero but may continue below zero, to provide some insight, how much energy is missing to complete the route or how many charging stops would be needed along the route. Charging cannot be planned unless the state of charge remains above 0%. Below this threshold, the battery's charging curve is undefined, making it impossible to create feasible planned routes.
Implementation
Vehicle Models are a more detailed representation of vehicles that extend the predefined profiles. Each vehicle model is based on one predefined profile, which is used for route calculation. The Vehicle Model inherits its properties from the predefined profile but may overwrite them. Furthermore, it extends the predefined profile with additional properties essential for energy consumption and charging calculation. When the EV Response fields are requested, the consumption relevant factors are applied on the route and the according response fields are generated. This data then enables cost comparisons with current vehicles and routes.
Overwriting Parameters
The existing overwriting hierarchy is extended by one layer - the vehicle model:
- Request parameters
- Vehicle model
- Predefined profile
Base is the predefined profile. Properties in the predefined profile are overwritten by values defined in the vehicle model. This can again be overwritten by request parameters in the vehicle object. However, when using a vehicle model some request parameters in the vehicle object are not supported. Those are specifically engineType, fuelType, electricityType, averageFuelConsumption, averageElectricityConsumption, bioFuelRatio, hybridRatio, dualFuelRatio, cylinderCapacity, emissionStandard and co2EmissionClass.
Integration
To use the model based energy consumption calculation you need to use the POST variant of the calculateRoute operation. Set up your route request with waypoints and other options as usual and follow these steps to get the energy consumption and charge results:
- Set a vehicle model id in the profile parameter (see our code sample how to get a vehicle model).
- Set relevant request parameters at waypoints like load weight, charging possibilities and weather (see our consumption calculation code sample).
- Add the EV_* results you want to see in the response to the results parameter.
With this the Routing API can provide:
- The state of charge of the battery and energy consumption at the end of the route and at the end of each leg.
- A plan, at which waypoints charging is necessary to reach the destination in the form of charge events.
- Regular update events on the state of charge and energy consumption, optionally with the polyline of the respective route section.
Emissions and Vehicle Models
Emissions can be calculated with vehicle models the same way as with predefined profile. However, some vehicle properties can not be changed when using a vehicle model, so some emission results are not applicable to vehicle models. Emission relevant properties are automatically used as defined in the vehicle model.
The emission result EMISSIONS_ISO14083_2023 requires vehicle[electricityConsumption] to be provided with predefined profiles. In case of vehicle models, this value is automatically calculated from the electricity consumption calculated by the Routing API so it does not have to be provided with the request.