Developer

Planning alternative routes

VERSION 1.26.0
PUBLIC PREVIEW

It is possible to plan alternative routes along with the main route by specifying additional parameters. All user-defined waypoints remain present in the alternative routes. Requesting alternative routes is also available when planning routes with generated charging stops. In such cases, the alternative routes may have different generated charging stops. To plan alternative routes, include AlternativeRouteOptions in RoutePlanningOptions.

Planning initial route with alternative routes

To request alternative routes during initial route planning, a non-zero value for maxAlternatives must be specified when constructing AlternativeRouteOptions; other parameters must remain unset.

The routes parameter in the RoutePlanningResponse result contains the list of calculated routes. The first route in this list is the main route. Any additional routes in the list are alternative routes. The number of alternative routes, if present, will not exceed the value of the maxAlternatives parameter specified in the RoutePlanningOptions.

See planning a route for more information on how to plan a route using RoutePlanningOptions.

1val amsterdam = GeoPoint(52.377956, 4.897070)
2val rotterdam = GeoPoint(51.926517, 4.462456)
3val routePlanningOptions = RoutePlanningOptions(
4    itinerary = Itinerary(
5        origin = amsterdam,
6        destination = rotterdam,
7    ),
8    alternativeRoutesOptions = AlternativeRoutesOptions(
9        maxAlternatives = 1,
10    ),
11)
12val result = routePlanner.planRoute(routePlanningOptions)

Requesting alternative routes during route reconstruction

See polyline reconstruction for more detailed information on how to perform route reconstruction.

There are two types of alternative routes that can be requested:

  • Any route – Alternative routes that are significantly different from the reference route.
  • Better route – Alternative routes that are better than the reference route. See the following section, "Requesting better route proposals".

The type of alternative routes can be specified by setting AlternativeType when constructing AlternativeRouteOptions.

It is important to allow enough time to decide whether to switch to an alternative route. To do this, you can request that the alternative routes follow the reference route from the origin point for at least a specified number of meters and/or econds. This is controlled by the minDeviationDistance and minDeviationTime parameters when constructing AlternativeRouteOptions.

1val amsterdam = GeoPoint(52.377956, 4.897070)
2val rotterdam = GeoPoint(51.926517, 4.462456)
3val routePlanningOptions = RoutePlanningOptions(
4    itinerary = Itinerary(
5        origin = amsterdam,
6        destination = rotterdam,
7    ),
8    alternativeRoutesOptions = AlternativeRoutesOptions(
9        maxAlternatives = 1,
10        alternativeType = AlternativeType.AnyRoute,
11        minDeviationTime = 25.seconds,
12        minDeviationDistance = Distance.meters(30),
13    ),
14    routeLegOptions = listOf(
15        RouteLegOptions(
16            supportingPoints = result.routes[0].geometry,
17        ),
18    ),
19    reconstructionMode = ReconstructionMode.Update,
20)
21val updateResult = routePlanner.planRoute(routePlanningOptions)

Requesting better route proposals

Requesting better alternative routes is important to get an optimal route at the time the request is made. A better route proposal is returned if it is:

To request better alternative routes, the AlternativeType.BetterRoute must be specified for alternativeType when constructing AlternativeRouteOptions.

If there is more than one route in the received routes parameter in the RoutePlanningResponse, the PlanningReason parameter of each non-first route indicates the reason why that better route proposal was planned. The possible values are:

  • Requested – The route was requested by the client. The reference route has this planning reason.
  • Blockage – the reference route contains road blockages.
  • BetterProposal – the alternative route is better than the reference route, according to the given planning criteria.
  • OutOfRange – At least one of the stops on the reference route is unreachable.

Next steps

Since you have learned how to plan alternative routes, here are recommendations for the next steps: