Sign in / Sign up
Route introduction Subscribe to route updates

Create a new route

As described in the route introduction, the first thing you will need to do is fetch a route ID. 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, you will need to provide us with EV details and at least a departure location and destination. Apart from that you can also support any of the options that are described below.

  • Support alternative stations along a route

    • If you want to request alternative charging stations along a route, you can set the stationsAlongRouteRadius property of the route mutation. The radius can be set 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

    • You can add a station as a waypoint or as a destination. To do this, add stationId to routeRequest.via.properties or routeRequest.destination.properties.

  • Cargo load and occupants

    • If you want to apply cargo and occupants, you can set ev.cargo and ev.occupants. You can overwrite these values on a leg basis by setting the cargo and occupants properties on routeRequest.origin.properties and any of the routeRequest.via.properties. If you do not set the values to 0, each leg inherits the values from the previous one or from the ev object.

  • Get additional properties

    • Our route destination, origin and stations have an optional properties attribute in any of our route queries. You can use this to fetch a complete address, the current temperature (temp) and air pressure at that location.

  • Using percentages

    • You can configure this query to use percentages for the state of charge and final state of charge. This way client-side conversions are no longer needed. Please be aware that the percentages are based upon the usable_kwh or the capacity included inside this mutation.

  • Operator ranking

    • In your route request, you can rank or exclude operators based on preference. We support ten different levels of preference. Level 1 is considered the highest level, and level 10 is the lowest. It is possible to skip levels or add multiple operators to the same level. Every level lowers the preference by 10 percent. Enable your operator ranking by setting it to preferred or required. If you always prefer and exclude the same operators, we recommend that you add your operator ranking to your client configuration instead. The route request will override any client configuration you might have.

  • Amenity preferences

    • route calculations can be extended by using the amenity_preferences argument. Within the argument there are two options; all_charge_stops and scheduled_charge_stops. Use all_charge_stops to add preferred amenities to every stop. Example given: include a playground at every charge stop. scheduled_charge_stops can be used to schedule a stop with a specific duration, amenity types and distance between the amenities and station. All amenities need to match the specified distance to be truthful. Use stop_after and offset to configure when the stop should occur. Example given: include a charge stop of 30 minutes after 3/3.5 hours with a playground within 500m.

We do not use onboard chargers of 20 kWh 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 • RequestInput

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.