Route

Planning routes for EVs comes with unique challenges. Battery capacity, real-world energy consumption, topography, weather, and charging network availability all determine whether a vehicle will reach its destination.

The Route API considers all these variables to find optimal EV routes. Using a world-class energy consumption model, it automatically places charging stops exactly when and where they’re needed. Routes are fully customizable, so you can fine-tune them to fit your own business rules.

How it works

To ensure high performance, the Route API operates asynchronously, following the same async pattern used across the API. Creating and retrieving a route happen in separate steps.

1. Create a routeCall the createRoute mutation with at least a vehicle, origin, and destination. The mutation returns a route id right away, which you’ll use in the next step to track and retrieve the route. Many more customization options are available; see customize your route below.
2. Open a subscriptionSubscribe to the route subscription using the id from the previous step. While the route is being calculated, the subscription pushes status updates you can use to drive an async loading state in your UI.
3. Render the resultOnce the route’s status resolves to done, error, or not_found, render the corresponding UI for that outcome.
4. Re-fetch on demandA route that has reached a final status that is successful is stored with its complete details. If you need to display it again later, for example after navigating back to it, use the getRoute query instead of opening a new subscription.

Hybrid vehicles

Hybrid and plug-in hybrid vehicles don’t rely solely on their battery, so their routes don’t include charging stops.

Customize your route

createRoute accepts a range of optional input to fine-tune how a route is calculated. More details on each field can be found in the API reference.

Feature	Description
Waypoints	Add intermediate stops. Provide via.properties.station.station_id to force a charging stop at a specific station, or only via.geometry for a plain transit point with no charging.
Stop duration	Set how long, in seconds, the vehicle stays at a waypoint or the destination, using properties.station.stop_duration or properties.location.stop_duration.
Highway charging	Prioritize charging stations located directly on the highway with station_preferences.prefer_highway_charging, avoiding stops that require exiting the highway.
Weather	Apply a weather preset or custom weather conditions to the consumption model. Defaults to real-time weather data.
Season	Assume summer, winter, or current weather conditions, as a simpler alternative to weather.
Route features to avoid	Avoid toll_road or ferry on a best effort basis.
Operator ranking	Prefer specific charging networks with type: preferred, or restrict routing to only those networks with type: required. Rank operators as high, medium, or low, and scope a ranking to specific countries per operator.
Operator exclusions	Exclude an operator entirely from the route with operators.exclude. Falls back to your project’s dashboard configuration when not set at the request level.
Operator avoidance	Avoid an operator without excluding it outright, using operators.avoid.
Alternative charging stations	Search for alternative charging stations within a radius between 500 and 5000 meters along the route.
Alternative routes	Request additional route options, on a best effort basis. Set to 0 to calculate only the recommended route.
Driving preferences	Adjust the driving style with speed_factor or maximum_speed, or pick a style of eco or sport.
Traffic awareness	Take real-time traffic congestion into account. Contact support to enable this for your project.
Departure time	Calculate expected arrival times using real-time traffic and historical, current, or forecasted weather.
Destination as a station	Set a specific station as the route’s destination. This is treated as a non-charging stop.
Vehicle load per waypoint	Set occupants, total_occupant_weight, and total_cargo_weight on origin or via. These propagate through the rest of the journey, and can be overridden at any later via point.
Minimum charging power	By default, routing excludes connectors below 43 kW. Set a different minimum to match your vehicle’s charging speed. Higher-rated chargers are still selected even if your vehicle charges slower than their maximum rate.

Thank you for your feedback.

Was this content helpful?