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.
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
stationsAlongRouteRadiusproperty of the route mutation. The radius can be set between
5000meters. 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
- Cargo load and occupants
If you want to apply cargo and occupants, you can set
ev.occupants. You can overwrite these values on a leg basis by setting the
routeRequest.origin.propertiesand 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
- Get additional properties
Our route destination, origin and stations have an optional
propertiesattribute in any of our route queries. You can use this to fetch a complete
address, the current temperature (
temp) and air
pressureat 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_kwhor 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
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
routecalculations can be extended by using the
amenity_preferencesargument. Within the argument there are two options;
all_charge_stopsto add preferred amenities to every stop. Example given: include a playground at every charge stop.
scheduled_charge_stopscan be used to schedule a stop with a specific
typesand distance between the amenities and station. All amenities need to match the specified distance to be truthful. Use
offsetto 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.
input • RequestInput
A response can either contain a
data or an
errors object. The response header will always return
200 as a status code.
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
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.
No car was found with the provided ID
Provided consumption value for $LOCATION is not valid. The value must be between 0 and $MAXVALUE kwh/100km for this car
Array $NAME should have at least one value
You are forbidden to execute this operation
Coordinates provided for $LOCATION are not valid.
Provided unit type $TYPE for $LOCATION is not valid.
Provided value $VALUE for $LOCATION is not valid. Expected value of type $EXPECTEDTYPE.
Negative value for $LOCATION is not allowed.
Provided number of occupants for $LOCATION is not valid. The value must be less than $OCCUPANTSCOUNT for this car.
Provided number of occupants for $LOCATION is not valid. The value must be at least 1.
Operator $OPERATORID is in both in the ranking and excluded lists
Operator $OPERATORID is present multiple times in the exclude lists
Operator $OPERATORID is present multiple times in the ranking lists
Operator ranking must be between 1 and 10!
No operator was found with the $OPERATORID ID
The route operator type was set to $ROUTEOPTYPE, but no ranking was provided. Please add an operator to your client or route request
The provided battery capacity is too high. The value must be less than or equal to $MAX kwh
The provided battery capacity is too small. The value must be greater than or equal to $MIN kwh
Provided amount of cargo weight is not valid . The value must be greater than 0.
Provided consumption value for $NAME is not valid. The worst value must be greater than or equal to best value
Provided consumption values are not valid. The total must be between 0 and $MAXVALUE for this car
The destination station for the route requested was not matched with the external station
The destination station for the route requested was not found with the provided ID
Amenities $DUPLICATEDAMENITIES are duplicated
The provided final state of charge is too high. The value must be less than or equal to 80% of the car battery capacity
Amenities $INVALIDAMENITIES are not valid. Allowed: $ALLOWEDAMENITIES
The destination coordinates provided are not valid
The origin coordinates provided are not valid
The scheduled charge stop duration is invalid. The value must be between 900 and 86400 seconds
The scheduled charge stop max_distance_from_station is invalid. The value must be between 0 and 1000 meters
The via coordinates provided are not valid
Provided number of passengers is not valid. The value must be between 1 and $PASSENGERCOUNT for this car
The provided minimum power is too small. The value must be greater than 0 kwh
The origin station for the route requested was not matched with the external station
The origin station for the route requested was not found with the provided ID
The radius value is above allowed, the maximum value is 5000 meters
The radius value is below allowed, the minimum value is 500 meters
The charger standard used on this car is not supported by the station
The minimum power requested is higher than the station could support
The station speed is not fast or turbo
Provided amount of cargo is not valid. The value must be greater than 0.
The via station for the route requested was not matched with the external station
The via station for the route requested was not found with the provided ID
The provided state of charge for $LOCATION is too high. The value must be less than or equal to the car battery capacity
Coordinates [$DESTINATIONCOORDINATES] of destination don't match with station coordinates [$STATIONCOORDINATES]
Coordinates [$ORIGINCOORDINATES] of origin don't match with station coordinates [$STATIONCOORDINATES]
Coordinates [$VIACOORDINATES] of via don't match with station coordinates [$STATIONCOORDINATES]
Provided tire pressure is not valid. The value must be at least 1.
Zero or negative value for $LOCATION is not allowed.