Sign in / Sign up
Subscribe to a route Route emissions introduction

Upgrading

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

Get a route

The route query retrieves the details of a previously calculated route.

Use getRoute to only fetch historical routes. Use subscription to retrieve newly created routes to avoid the overhead of manual polling.

Render route and route data

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

Render route and route data

Query

The getRoute query requires the ID returned in createRoute . The route details — recommended and alternatives — become available once the request status field reaches done.

Explore the sections below to learn how to use the different returned details:

  • Route Details Structure

    • Each returned route details follows a three-tier hierarchy

      Route- The top-level summary of the journey. It acts as the container for the entire trip, including route-level properties and the complete list of legs.

      Legs- Segments of the route divided by stops. A new leg is created each time the vehicle is scheduled to stop, whether for charging or a non-charging stop.

      Sections- The most granular segments within a Leg. These break down a single leg into different travel modes, such as driving, taking a ferry, or walking.

  • Alternative routes

    • For routes created through createRoute with alternatives > 0 , the alternatives array includes the alternative routes. The availability is on a best-effort basis, it may return fewer routes than requested, or even none.

  • Legs types

    • The leg.type identifies the leg’s purpose. Legs that include charging stops are labeled as station (if the stop was auto-selected) or station_via (if the stop was user-requested). Legs without charging stops are labeled as via (if the stop was user-requested as non-charging via) or final (if the leg ends at the destination).

  • Location properties

    • Use properties field present in leg's origin and destination to extract additional location related properties such as name, solar_irradiance, temperature , air_pressure and more.

  • Alternative stations along route

    • For routes created through createRoute with alternative_station_radius, the route details include the alternative_stations field with all compatible stations located within the specified distance of the path. This provides a list of fallback charging options along the route.

  • Traffic data

    • For routes calculated with traffic_aware enabled, the API returns real-time congestion data. Use traffic.delay to retrieve the exact duration added by traffic in seconds and traffic.congestions to map the traffic congestion along the route polyline.

  • Unit conversion

    • Use the unit argument to automatically convert distance and energy values in the response. Utilizing this eliminates the need for manual client-side calculations.

  • Path plot

    • The path_plot object provides high-resolution data of average_speed, elevation, state_of_charge , consumption, coordinates along the entire polyline. This is the primary field for rendering elevation, consumption, or speed profiles.

  • Durations

    • Available at the route and leg levels, the durations field provides a granular breakdown of total, charging, driving, stopover, and ferry journey times. This allows you to present a detailed timeline of the trip.

  • Tags

    • The Tags field enriches segments with categorical metadata such as highway, toll, or crossborder. Available at the route, leg, and section levels, these labels allow applications, for example, to render specific notifications based on the nature of the road ahead.

  • Route warnings

    • If constraints—such as preferred operators or avoided segments—cannot be fulfilled, the API flags these compromises in the warnings field at the route and leg levels. Use these to maintain transparency with drivers regarding any calculation deviations. Refer to the field enums for a full list of available warning codes.

Arguments

id • ID

• Required

ID of a route.

Selectable fields

id • ID

ID of a route calculation.

status • RouteStatus

Status of a route.

Show RouteStatus enum values

alternatives • RouteDetails

[BETA] Alternative routes.

meta • RouteMetadata

Meta data for a route.

request_input • CreateRoute

Route request.

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.