Sign in / Sign up
Migration from Route Legacy Subscribe to a route

Upgrading

If you're currently using the legacy routing service, check the migration guide to learn how to transition to this service.

Create a route

The createRoute mutation initiates an EV route calculation by specifying waypoints, vehicle parameters, and routing preferences.

Render route and route data

Plot a route on a map and render the route detail data.

Render route and route data

Mutation

The createRoute mutation requires a vehicle.id , an origin, and a destination. Fetch valid vehicle IDs using the vehicle query.

Routing Constraints

Slow Charging Connectors - Routing excludes connectors below 43 kW. If your vehicle is limited to a lower charging speed, compatible higher-rated chargers will still be selected.

Hybrid Vehicles - Routes for hybrid and plug-in hybrid vehicles don't include recommended charging stops.

Beyond the required arguments, you can use the optional arguments to tailor the route to specific trip conditions and business goals. Explore the sections below to learn how these arguments enable key features.

  • Plan intermediate waypoints or mandatory charging stops

    • Include via points to define intermediate waypoints or mandatory charging stops.

      Mandatory Charging Stops - Use via[].properties.station to force the API to plan a charging session at that specific station.

      Non-Charging Waypoints - Provide only the via.geometry (coordinates) without station identifiers. The API treats these as standard intermediate transit points where no charging is planned.

  • Operator preferences

    • Use operator_preferences to require, prefer, avoid, or exclude specific charging networks.

      Request and project-level preferences - Operator preferences can be defined at the request or project level. If your preferences are fixed, it's best to configure them in your project. You can always override them by specifying the operators at the request level.

      Preference type and Ranking - Set the type to preferred to influence selection or required to strictly limit the route to those operators. Preferred operators can be ranked with high, medium, or low priority levels.

      Country Scoping - Use the countries field to restrict a preference to specific countries. Otherwise, the preferences are applied globally.

      Unranked Operators - Operators without preferences may still be used if no preferred options are reachable or if they would cause an impractical increase in trip duration.

  • Alternative Stations

    • To request alternative charging stations along a route, set the input.alternative_station_radius.value with a value between 500 and 5000 meters. This will search for alternative charging stations along the route compatible with vehicle within the set radius.

  • Traffic-Aware Routes

    • Enable traffic_aware for the route to consider real-time traffic congestion. Please contact support for more details on how to enable it.

  • Driving styles

    • Adjust the style of driving through driving_preferences . For granular control, use speed_factor or maximum_speed to manually scale predicted speeds relative to road limits.

  • Stations as a destination

    • Use destination.properties.station to select a specific station as the route destination. Note that stations used as a destination are treated as non-charging stops.

  • Cargo and occupants

    • Define vehicle load (total_cargo_weight and occupants) at the origin and via. These values automatically propagate through all legs of the journey, but can be overridden at any intermediate via point to support load changes (e.g., dropping off passengers or cargo).

  • Alternative charging stations

    • Set alternative_station_radius to search for compatible charging stations along the entire route. These fallback options are returned in the alternative_stations field when retrieving route details.

  • Departure time

    • Specify a departure_time to calculate expected arrival times, factor in real-time traffic patterns (if used in combination with traffic_aware) , and apply historical, current, or forecasted weather data to the consumption model.

  • Alternative Routes

    • Set alternative_routes to request additional route options. This is a best-effort calculation; the API may return fewer alternatives than requested depending on road topology and charging density.

Arguments

input • CreateRouteInput

• Required

Input for generating a route.

Selectable fields

ID

Response

A response can either contain a data or an errors object. The response header will always return 200 as a status code.

Data object

When successful, a data object will be returned with the requested fields. If there are no fields present the data object will return the operation name with the appropriate return type. If the operation was a query, this output will be an object of the schema’s query root type; if the operation was a mutation, this output will be an object of the schema’s mutation root type.

Error object

If unsuccessful, an errors object will be returned with more details in the extensions object. The error object can contain any of the following objects.