Sections

Sign in / Sign up
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 usableCarBattery 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.

  • Amenities

    • In the route request you can define a list of amenities that should be available at the charge stations. Valid amenity types are: restaurant, bathroom, supermarket, playground, coffee, shoping, museum, hotel, park and pharmacy. The route that matches the requested amenities best will be available as a route alternative with the type bestMatching. If you did include an operator ranking object in your route request this ranking is equally taken into account. Use the amenity list query to retrieve the amenity details for a station id.

We do not use onboard chargers of 20 kWh in routing unless a car 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 • input_object • RequestInput

Response

If successful, the HTTP status code in the response header is 200 and the response body contains the attributes you requested.

If unsuccessful, the header status code is an error code and the response body contains an error response object. The error response object can be any of the ones below.

Errors and warnings

Error

CAR_NOT_FOUND

No car was found with the provided ID

Error

ERROR_FORBIDDEN_MESSAGE

You are forbidden to execute this operation

Error

NEGATIVE_VALUE_NOT_ALLOWED

Negative value for $LOCATION is not allowed.

Error

OPERATOR_BOTH_EXCLUDED_AND_RANKING

Operator $OPERATORID is in both in the ranking and excluded lists

Error

OPERATOR_DUPLICATED_IN_EXCLUDE

Operator $OPERATORID is present multiple times in the exclude lists

Error

OPERATOR_DUPLICATED_IN_RANKING

Operator $OPERATORID is present multiple times in the ranking lists

Error

OPERATOR_INVALID_RANKING

Operator ranking must be between 1 and 10!

Error

OPERATOR_NOT_FOUND

No operator was found with the $OPERATORID ID

Error

OPERATOR_RANKING_NONE_GIVEN

The route operator type was set to $ROUTEOPTYPE, but no ranking was provided. Please add an operator to your client or route request

Error

ROUTE_BATTERY_CAPACITY_ABOVE_ALLOWED

The provided battery capacity is too high. The value must be less than or equal to $MAX kwh

Error

ROUTE_BATTERY_CAPACITY_BELOW_ALLOWED

The provided battery capacity is too small. The value must be greater than or equal to $MIN kwh

Error

ROUTE_CARGO_BELOW_ALLOWED

Provided amount of cargo weight is not valid . The value must be greater than 0.

Error

ROUTE_CONSUMPTION_EXCEEDED

Provided consumption value for $NAME is not valid. The value must be between 0 and $MAXVALUE for this car

Error

ROUTE_CONSUMPTION_INVALID_WORST

Provided consumption value for $NAME is not valid. The worst value must be greater than or equal to best value

Error

ROUTE_CONSUMPTION_TOTAL_EXCEEDED

Provided consumption values are not valid. The total must be between 0 and $MAXVALUE for this car

Error

ROUTE_DESTINATION_STATION_AND_EXTERNAL_STATION_NOT_MATCHING

The destination station for the route requested was not matched with the external station

Error

ROUTE_DESTINATION_STATION_NOT_FOUND

The destination station for the route requested was not found with the provided ID

Error

ROUTE_DUPLICATE_AMENITIES

Amenities $DUPLICATEDAMENITIES are duplicated

Error

ROUTE_FINAL_SOC_EXCEEDING_BATTERY_CAPACITY

The provided final state of charge is too high. The value must be less than or equal to 80% of the car battery capacity

Error

ROUTE_INVALID_AMENITIES

Amenities $INVALIDAMENITIES are not valid. Allowed: $ALLOWEDAMENITIES

Error

ROUTE_INVALID_DESTINATION_COORDINATES

The destination coordinates provided are not valid

Error

ROUTE_INVALID_ORIGIN_COORDINATES

The origin coordinates provided are not valid

Error

ROUTE_INVALID_VIA_COORDINATES

The via coordinates provided are not valid

Error

ROUTE_MAX_NUMBER_OF_PASSENGERS_EXCEEDED

Provided number of passengers is not valid. The value must be between 1 and $PASSENGERCOUNT for this car

Error

ROUTE_MIN_POWER_BELOW_ALLOWED

The provided minimum power is too small. The value must be greater than 0 kwh

Error

ROUTE_OCCUPANTS_ABOVE_ALLOWED

Provided number of occupants is not valid. The value must be less than $OCCUPANTSCOUNT for this car.

Error

ROUTE_OCCUPANTS_BELOW_ALLOWED

Provided number of occupants is not valid. The value must be at least 1.

Error

ROUTE_ORIGIN_STATION_AND_EXTERNAL_STATION_NOT_MATCHING

The origin station for the route requested was not matched with the external station

Error

ROUTE_ORIGIN_STATION_NOT_FOUND

The origin station for the route requested was not found with the provided ID

Error

ROUTE_RADIUS_ABOVE_ALLOWED

The radius value is above allowed, the maximum value is 5000 meters

Error

ROUTE_RADIUS_BELOW_ALLOWED

The radius value is below allowed, the minimum value is 500 meters

Error

ROUTE_SOC_EXCEEDING_BATTERY_CAPACITY

The provided state of charge is too high. The value must be less than or equal to the car battery capacity

Error

ROUTE_STATION_INVALID_CHARGER

The charger standard used on this car is not supported by the station

Error

ROUTE_STATION_INVALID_MIN_POWER

The minimum power requested is higher than the station could support

Error

ROUTE_STATION_INVALID_SPEED

The station speed is not fast or turbo

Error

ROUTE_VIA_CARGO_BELOW_ALLOWED

Provided amount of cargo is not valid. The value must be greater than 0.

Error

ROUTE_VIA_OCCUPANTS_ABOVE_ALLOWED

Provided number of occupants for via is not valid. The value must be less than $VIAOCCUPANTSCOUNT for this car.

Error

ROUTE_VIA_OCCUPANTS_BELOW_ALLOWED

Provided number of occupants for via is not valid. The value must be at least 1.

Error

ROUTE_VIA_STATION_AND_EXTERNAL_STATION_NOT_MATCHING

The via station for the route requested was not matched with the external station

Error

ROUTE_VIA_STATION_NOT_FOUND

The via station for the route requested was not found with the provided ID

Error

STATION_DESTINATION_COORDINATES_NOT_MATCHING

Coordinates [$DESTINATIONCOORDINATES] of destination don't match with station coordinates [$STATIONCOORDINATES]

Error

STATION_ORIGIN_COORDINATES_NOT_MATCHING

Coordinates [$ORIGINCOORDINATES] of origin don't match with station coordinates [$STATIONCOORDINATES]

Error

STATION_VIA_COORDINATES_NOT_MATCHING

Coordinates [$VIACOORDINATES] of via don't match with station coordinates [$STATIONCOORDINATES]

Error

ZERO_OR_NEGATIVE_VALUE_NOT_ALLOWED

Zero or negative value for $LOCATION is not allowed.