Developer

Planning alternative routes

VERSION 1.25.9
PUBLIC PREVIEW

It is possible to plan alternative routes along with the main route when additional parameters are specified. All user-defined waypoints remain present in alternative routes. Requesting alternative routes is also available when planning routes with generated charging stops. Alternative routes may have different generated charging stops in this case. To plan alternative routes, the AlternativeRouteOptions must be specified 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 of route planning will have the list of calculated routes, the first route in this list will be the main route. The number of other routes, if there are any, will not be bigger than the maxAlternatives value specified in the RoutePlanningOptions. These generated routes are alternative routes.

See planning 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 give a reasonable amount of time for making a decision on switching to alternative routes. To do that, you can request that the alternative routes follow the reference route from the origin point for at least the specified number of meters and/or the number of seconds. This is achieved by setting 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 when 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.

When there is more than one route in the received routes parameter in the RoutePlanningResponse, the non-first route’s PlanningReason parameter represents the particular reason why the better route proposal is 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 of the reference route is unreachable.

Next steps

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