Planning a route

VERSION 0.3.34
PUBLIC PREVIEW

Requesting routes

To calculate a route from A to B, you need to provide route planning criteria. They are built using the RoutingOptions class. You can take advantage of the named parameters in Kotlin, or use RoutingOptions.Builder to choose the properties that you need. The only required parameters is itinerary. There are multiple optional parameters that you can use to shape the route planning criteria to fit your use cases. For a detailed description of available parameters, see the Routing API documentation.

1val amsterdam = GeoCoordinate(52.377956, 4.897070)
2val rotterdam = GeoCoordinate(51.926517, 4.462456)
3val routingOptions = RoutingOptions.Builder(itinerary = Itinerary(amsterdam, rotterdam))
4 .maxAlternatives(2)
5 .routeType(RouteType.EFFICIENT)
6 .travelMode(TravelMode.TRUCK)
7 .build()

Once you have a RoutingOptions object, provide it to the planRoute method. This can be done asynchronously using the RoutingCallback, or synchronously as described in the Synchronous routing call. If the route planning is successful, the onSuccess(RoutingResult) method is called. If an error occurred, it is in RoutingError.

1routingApi.planRoute(
2 routingOptions,
3 object : RoutingCallback {
4 override fun onSuccess(result: RoutingResult) {
5 /* YOUR CODE GOES HERE */
6 }
7
8 override fun onError(error: RoutingError) {
9 /* YOUR CODE GOES HERE */
10 }
11 }
12)

Route with alternatives

Adjusting route planning criteria

Route types

The route type parameter specifies the type of optimization used when calculating routes:

  • FAST: Route calculation is optimized by travel time, while keeping the routes sensible. For example, the calculation may avoid shortcuts along inconvenient side roads or long detours that only save very little time.
  • SHORT: Route calculation is optimized by travel distance, while keeping the routes sensible. For example, straight routes are preferred over those incurring turns.
  • EFFICIENT: Route calculation is optimized so that a good compromise between small travel time and low fuel or energy consumption is achieved.
  • THRILLING: Route calculation is optimized so that routes include interesting or challenging roads and use as few motorways as possible.
    • You can choose the level of turns included and also the degree of hilliness. See the hilliness and windingness parameters to set this.
    • There is a limit of 900km on routes planned with thrilling route type.

Default value is set to FAST.

Avoids

The RoutingOptions.avoidTypes parameter specifies something that the route calculation should try to avoid when determining the route. The avoid can be specified multiple times. Possible values are:

Vehicle profile

Vehicle profile relates to a set of parameters that are used to provide extra information about the vehicle specification. It also provides information about the current state, e.g., the level of fuel. Some roads in the map have vehicle and time dependent restrictions. For example, roads may restrict traffic to pedestrians, or can only be used by electric vehicles. Various road types may prohibit vehicles carrying hazardous materials. Tunnels may only be passable by vehicles up to a maximum height, and for trucks, with the proper tunnel code. Key parameters defining vehicle profiles:

  • Vehicle type, e.g., car or motorcycle.
  • Engine type, e.g., combustion, electric or hybrid, having a combustion and an electric engine. For pedestrians and bicycles, no engine is allowed.
  • Consumption parameters used to adjust the overall range prediction of the vehicle.
  • Vehicle dimensions.
  • Hazardous payload describing classification of carrying hazardous materials that is carried by the vehicle.
  • Tunnel codes describing which tunnels can be used.
  • Trailer.
  • Preference of fuel type/charging cable compatibility.
  • Number of occupants, allowing the use of high occupancy roads.

Vehicle profile properties are valid only at the current point in time and they get updated over time, e.g., the consumption curve. Vehicle profile is also useful during free driving mode without a route, e.g., to steer range features like 360 range around your current position.

Planning errors

A RoutingError is returned if any error occurred during the Routing API call. There are a few RoutingErrors that are returned in different situations.