Planning a route

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. The route planning options defined within buildRoutePlanningOptions are appropriate for most use cases. The buildRoutePlanningOptions method will create a RoutePlanningOptions instance, providing you with a possibility to customize most important attributes, while providing meaningful defaults for the rest of the attributes:

1val amsterdam = GeoPoint(52.377956, 4.897070)
2val rotterdam = GeoPoint(51.926517, 4.462456)
3val routePlanningOptions = buildRoutePlanningOptions(
4    itinerary = Itinerary(origin = amsterdam, destination = rotterdam),
5    maxAlternatives = 2,
6    routeType = RouteType.Efficient,
7    avoids = setOf(AvoidType.UnpavedRoads, AvoidType.Ferries),
8)

The only required parameter is the itinerary. The Itinerary contains the origin and destination points, any waypoints that you want to include in the route, as well as the PlanningTime. There are several 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.

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

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.

1val routePlanningCallback = object : RoutePlanningCallback {
2    override fun onSuccess(result: RoutePlanningResponse) {
3        // YOUR CODE GOES HERE
4    }
5
6    override fun onFailure(failure: RoutingFailure) {
7        // YOUR CODE GOES HERE
8    }
9}
10
11val cancellable = routePlanner.planRoute(routePlanningOptions, routePlanningCallback)

Adjusting route planning criteria

Waypoints

Waypoints are specific points through which a route should be calculated. They do not define the entire route but must be passed through during the journey from origin to destination.

The maximum allowed number of waypoints is 150.

Waypoints are defined using a list of ItineraryPoint. By default, they are included in the route in the order they are specified. Each waypoint results in an additional leg in the response. Each added waypoint also results in an extra RouteStop in the routeStops list, where the first element is the origin and the last element is the destination.

1val amsterdam = ItineraryPoint(Place(GeoPoint(52.377956, 4.897070)))
2val rotterdam = ItineraryPoint(Place(GeoPoint(51.926517, 4.462456)))
3val hague = ItineraryPoint(Place(GeoPoint(52.078663, 4.288788)))
4val utrecht = ItineraryPoint(Place(GeoPoint(52.091458, 5.11518)))
5val itinerary = Itinerary(
6    origin = amsterdam,
7    destination = rotterdam,
8    waypoints = listOf(hague, utrecht),
9)
10val routePlanningOptions = buildRoutePlanningOptions(itinerary = itinerary)

Alternative routes

The numAlternatives parameter of buildRoutePlanningOptions specifies the maximum number of alternative routes to be planned. 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.

1val amsterdam = GeoPoint(52.377956, 4.897070)
2val rotterdam = GeoPoint(51.926517, 4.462456)
3
4val routePlanningOptions = buildRoutePlanningOptions(
5    itinerary = Itinerary(
6        origin = amsterdam,
7        destination = rotterdam,
8    ),
9    maxAlternatives = 1,
10)
11
12val routePlanningCallback = object : RoutePlanningCallback {
13    override fun onSuccess(result: RoutePlanningResponse) {
14        val mainRoute = result.routes[0]
15        // YOUR CODE GOES HERE
16    }
17
18    override fun onFailure(failure: RoutingFailure) {
19        // YOUR CODE GOES HERE
20    }
21
22    override fun onRoutePlanned(route: Route) {
23        // YOUR CODE GOES HERE
24    }
25}
26
27val cancellable = routePlanner.planRoute(routePlanningOptions, routePlanningCallback)

1val amsterdam = GeoPoint(52.377956, 4.897070)
2val rotterdam = GeoPoint(51.926517, 4.462456)
3
4val routePlanningOptions = RoutePlanningOptions(
5    itinerary = Itinerary(
6        origin = amsterdam,
7        destination = rotterdam,
8    ),
9    alternativeRoutesOptions = AlternativeRoutesOptions(
10        maxAlternatives = 1,
11    ),
12)
13
14val routePlanningCallback = object : RoutePlanningCallback {
15    override fun onSuccess(result: RoutePlanningResponse) {
16        val mainRoute = result.routes[0]
17        // YOUR CODE GOES HERE
18    }
19
20    override fun onFailure(failure: RoutingFailure) {
21        // YOUR CODE GOES HERE
22    }
23
24    override fun onRoutePlanned(route: Route) {
25        // YOUR CODE GOES HERE
26    }
27}
28
29val cancellable = routePlanner.planRoute(routePlanningOptions, routePlanningCallback)

Route type

The routeType parameter of buildRoutePlanningOptions determines which types of paths are preferred during route planning.

Types

There are several RouteType values that can be used to specify the type of route to be planned:

• 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 involve 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.

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(
8        maxAlternatives = 2,
9    ),
10)

Avoids

The avoids parameter of buildRoutePlanningOptions 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

Possible avoids and their corresponding sections are:

• AvoidType.TollRoads: Avoids toll roads (section: SectionType.TollRoad).
• AvoidType.Motorways: Avoids motorways (section: SectionType.Motorway).
• AvoidType.Ferries: Avoids ferries (section: SectionType.Ferry).
• AvoidType.UnpavedRoads: Avoids unpaved roads (section: SectionType.Unpaved).
• AvoidType.CarPools: Avoids routes that require the use of carpool lanes (HOV/High-Occupancy Vehicle) (section: SectionType.Carpool).
• AvoidType.AlreadyUsedRoads:
  • Avoids using the same road multiple times. This is important for round trips when you do not want to use the same roads again.
  • This is most useful in conjunction with RouteType.Thrilling.
  • There is no corresponding section.
• AvoidType.BorderCrossings: Avoids crossing country borders (section: SectionType.Country).
• AvoidType.Tunnels: Avoids tunnels (section: SectionType.Tunnel).
• AvoidType.CarTrains: Avoids car trains (section: SectionType.CarTrain).
• AvoidType.LowEmissionZones: Avoids low-emission zones (section: SectionType.LowEmissionZone).

Guidance instructions

Guidance instructions are provided as part of the calculated route. The language and phoneticsInstructionType parameters of buildRoutePlanningOptions specify the language and phonetics type for the instructions.

1val amsterdam = GeoPoint(52.377956, 4.897070)
2val rotterdam = GeoPoint(51.926517, 4.462456)
3val routePlanningOptions = buildRoutePlanningOptions(
4    itinerary = Itinerary(origin = amsterdam, destination = rotterdam),
5    maxAlternatives = 2,
6    routeType = RouteType.Efficient,
7    avoids = setOf(AvoidType.UnpavedRoads, AvoidType.Ferries),
8    language = Locale.ENGLISH,
9    instructionPhoneticsType = InstructionPhoneticsType.Ipa,
10)

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.

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 cancellable = routePlanner.planRoute(routePlanningOptions, routePlanningCallback)

Vehicle

The Vehicle contains parameters relevant for selecting suitable routes. It also provides information about the current state, such as the fuel level or charge state. Some roads on the map have vehicle-dependent 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.

The vehicle is configured through the 'VehicleProvider' object.

Planning failures

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

• ApiKeyFailure – The routing call did not finish due to a problem with the API key.
• BadInputFailure – The request contained an invalid combination of input parameters.
• ComputationTimeoutFailure – The request reached an internal computation time threshold and timed out.
• DeserializationFailure – Deserialization failed.
• HttpFailure – The routing call ended with an unexpected HTTP status code.
• InstructionGenerationFailure - Instruction generation failed.
• InternalFailure – An internal routing failure occurred.
• MapMatchingFailure - One of the input points (Origin, Destination, or Waypoints) could not be matched to the map because no known drivable section was found nearby.
• NetworkFailure – The routing network call failed with an [IOException].
• NoRouteFoundFailure - No valid route could be found.
• RouteReconstructionFailure - Route reconstruction using supportingPoints failed.
• RoutePlanningCancelled - The calculation was canceled.
• UnknownFailure - The routing call ended with an unknown failure.

Next steps

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

• Planning a long distance EV route
• Search quickstart
• Showing routes on the map
• Planning alternative routes
• Reconstructing a route from a polyline
• Waypoints and custom routes
• Range calculation