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.

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.

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.

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.

Note
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 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 & warnings

    • Error
      CAR_NOT_FOUND

      No car was found with the provided ID

    • 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_DESTINATION_STATION_NOT_FOUND

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

    • 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 the car battery capacity value

    • 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_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 value

    • 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_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]