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

Upgrading

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

Create a new route

As described in the route introduction, after executing the mutation a new route ID will be received in the response. This route ID can then be sent to subscribe to route details and retrieve a polyline and other route data.

Render route and route data

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

Render route and route data

Mutation

To get a route ID, the input must contain at least the EV details and a departure location and destination. Other supported options are described below.

  • Support alternative stations along a route

    • To request alternative charging stations along a route, the alternative_station_radius property can be set on the input of the route mutation. The radius should be between 500 and 5000 meters. This will return all applicable stations within the set radius following the specified powers and standards.

  • Support stations as waypoint

    • A station can be added as a waypoint or as a destination. To do this, add station_id to request_input.via.properties.station or request_input.destination.properties.station.

  • Cargo load and occupants

    • To apply cargo and occupants, set request_input.origin.properties.vehicle.total_cargo_weight and request_input.origin.properties.vehicle.occupants. These values can be overridden on a leg basis by setting them on the request_input.via.properties.vehicle. Unless the values are set to 0, each leg inherits the values from the previous one or from the origin object.

  • Get additional properties

    • The route legs origin an destination have an optional properties attribute. This can be used to fetch details such as a complete address, the current temperature and air_pressure at that location.

  • Using unit arguments

    • All the fields that support unit conversion have a unit argument that can be set. For example, the range_at_origin and range_at_destination can be retrieved in kilometer, mile, kilowatt_hour or percentage. Please be aware that the percentages are based upon the usable_kwh or the capacity included inside this mutation.

  • Operator preference

    • The route request supports ranking and excluding operators based on preference and country. Operators can be ranked with three preference levels: high, medium, or low. Please note that unranked operators may still be selected if no preferred operators are available or using them would significantly lengthen the route duration. The countries field allows individual operator preferences within a ranking level or exclusion list to be scoped to specific countries. If countries is omitted for an operator, that operator’s preference applies globally. You may skip levels, list multiple operators per level, or assign the same operator to different levels as long as they are set for different countries. To enable ranking, set input.operators.type to preferred or required. If your preferences are fixed, it's best to configure them in your client. Route request preferences override client settings.

  • Departure time

    • Users can now specify a departure time, allowing the routing engine to calculate the expected arrival time and apply historical weather data if the departure time is in the past.

Onboard chargers of 20 kWh are not used in routing unless a vehicle has no plugs above 20 kWh. Therefore, if you add a plug of 20 kWh or less to your route request, this plug will often be ignored.

Arguments

input • CreateRouteInput

• Required

Input for generating a route.

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.