Developer

Planning a route

VERSION 1.26.0
PUBLIC PREVIEW

Requesting routes

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

1val amsterdam = GeoPoint(52.377956, 4.897070)
2val rotterdam = GeoPoint(51.926517, 4.462456)
3val routePlanningOptions = RoutePlanningOptions(
4    itinerary = Itinerary(origin = amsterdam, destination = rotterdam),
5    costModel = CostModel(routeType = RouteType.Efficient),
6    vehicle = Vehicle.Truck(),
7    alternativeRoutesOptions = AlternativeRoutesOptions(maxAlternatives = 2),
8)

Once you have a RoutePlanningOptions object, provide it to the planRoute method. The call is done asynchronously using the RoutePlanningCallback for result and error handling. If route planning is successful, the onSuccess(result: RoutePlanningResponse) and onRoutePlanned(route: Route) methods are called. If an error occurs, it will appear in the RoutingFailure returned by the onFailure(failure: RoutingFailure) method.

1routePlanner.planRoute(
2    routePlanningOptions,
3    object : RoutePlanningCallback {
4        override fun onSuccess(result: RoutePlanningResponse) {
5            // YOUR CODE GOES HERE
6        }
7

8        override fun onFailure(failure: RoutingFailure) {
9            // YOUR CODE GOES HERE
10        }
11

12        override fun onRoutePlanned(route: Route) {
13            // YOUR CODE GOES HERE
14        }
15    },
16)
Route with alternatives

Adjusting route planning criteria

Cost model

The CostModel provides criteria that specify which paths are preferable during route planning.

Route types

The RoutePlanningOptions.costModel.routeType parameter specifies the type of optimization used when calculating routes:

  • Fast: Route calculation is optimized for travel time, while keeping the routes sensible. For example, the calculation may avoid shortcuts along inconvenient side roads or long detours that save only a negligible amount of time.
  • Short: Route calculation is optimized for travel distance, while keeping the routes sensible. For example, straight routes are preferred over those that invlove many turns.
  • Efficient: Route calculation is optimized to achieve a good balance between shorter travel time and lower fuel or energy consumption.
  • Thrilling: Route calculation is optimized to include interesting or challenging roads and use as few motorways as possible.
    • You can choose the level of turns included and the degree of hilliness. See the hilliness and windingness parameters to set this.
    • There is a 900 km limit on routes planned with the Thrilling route type.

Default value is set to Fast.

Avoid options

The RoutePlanningOptions.costModel.avoidOptions parameter specifies the avoidance criteria. Avoids are honored whenever a reasonable route is available that fulfills all avoid criteria. However, if the detour becomes too large, some avoid criteria may be violated on parts of the route. These violations can be detected by checking the corresponding route sections.

Avoid types

The RoutePlanningOptions.costModel.avoidOptions.avoidTypes parameter specifies the elements that the route calculation should try to avoid when determining the route. An avoid type can be specified multiple times.

Possible avoids and their corresponding sections are:

Avoid areas

The RoutePlanningOptions.costModel.avoidOptions.avoidAreas parameter specifies a set of bounding boxes to avoid.

Vehicle

The Vehicle contains parameters relevant for selecting suitable routes. It also provides information about the current state, such as the fuel level. Some roads on the map have vehicle- and time-dependent restrictions. For example:

  • Some roads are restricted to pedestrians only.
  • Some can be used only by electric vehicles.
  • Certain roads prohibit vehicles carrying hazardous materials.
  • Tunnels may allow only vehicles below a certain height or trucks with a specific tunnel code.

Vehicles are distinguished by type. Each vehicle type has a different constructor, which accepts only the parameters relevant to that type. For example, dimensions are meaningful for motorized vehicles but not for bikes or pedestrians.

Vehicles have the following properties:

  • A type, such as a car, motorcycle, or truck.
  • A maximum speed.
  • An engine (for motorized vehicles), which can be combustion, electric, or both (for hybrid vehicles).
    • Pedestrians and bicycles do not support engines.
    • Each engine can contain consumption parameters used to predict vehicle range.
    • Motorized vehicles may have dimensions.
    • They can be used for commercial transport.
  • A load (for trucks) that may be subject to restrictions:
    • A hazmat classification can restrict usable roads.
    • An ADR tunnel code describes which tunnels the vehicle can use.

Some vehicle properties are valid only at the current point in time and update over time—for example, fuel level or battery charge. Vehicle data is also useful during free driving mode (no planned route), for example, in range features like 360-degree range around your current position.

Planning failures

A RoutingFailure is returned if any failure occurres during a Routing API call. Several RoutingFailures can be returned in different situations:

Incremental guidance computation

Incremental guidance computation is an internal optimization technique that reduces route planning time. It works by initially providing the route with a limited number of instructions and lane guidance, rather than computing all instructions and completing lane guidance for the entire route. Subsequent increments are automatically requested and calculated during in-drive navigation.

The mode for guidance computation is controlled by RouteInformationMode. It contains two cases: Complete and FirstIncrement.

  • The Complete case is set by default. In this mode, the planRoute method provides all instructions for the route immediately.
  • In the FirstIncrement case, the route is generated with only the first guidance increment. This takes less time than using Complete mode.
1val amsterdam = GeoPoint(52.377956, 4.897070)
2val rotterdam = GeoPoint(51.926517, 4.462456)
3val routePlanningOptions = RoutePlanningOptions(
4    itinerary = Itinerary(amsterdam, rotterdam),
5    mode = RouteInformationMode.FirstIncrement,
6)
7val result = routePlanner.planRoute(routePlanningOptions)

Next steps

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