Plan a route

Page Summary

• Plan routes in advance and guide navigation using route tokens from Routes, Routes Preferred, or Route Optimization APIs.

• Route tokens allow for specifying objectives like minimizing delivery time, fuel consumption, or travel costs, enhancing route control.

• While the Navigation SDK attempts to follow the planned route, real-time conditions may cause deviations, prioritizing objectives over the exact path.

• Request new route tokens for each trip as they are specific to origin, destination, and time, ensuring up-to-date navigation.

• Route tokens streamline route planning, providing estimations and allowing for advanced objectives like eco-routing while adapting to dynamic conditions.

At times, you might want to plan the route your app provides to users. Using a route token from the Routes API or Route Optimization API can help you specify two things for your planned route:

• A polyline for the route

• Your route objectives

For example, here are some examples of routing objectives you may have:

• Minimize time to delivery: A business delivering food might want to minimize the time it takes to deliver the food.

• Minimize travel time or fuel consumption: A logistics business might want to improve the efficiency of their drivers and reduce their fuel costs.

• Minimize time to destination: A service dispatch operation might want to minimize the time it takes to get operators to a job request.

• Lower costs and improve safety: A ride-sharing business might want to find a route that costs less for riders and avoids certain areas for safety reasons.

Important: The route that drivers travel can differ from your planned route. Changing traffic or road conditions, the vehicle leaving the planned route, or a switch to a faster route can change the route during the trip. Whenever the Navigation SDK calculates a new route, it uses the routing options set in your route token, such as avoiding tolls.

For more information about planning a route using a route token, see Get a route token in Routes API and Transition Polylines and Route Tokens in Route Optimization API.

Why use a route token for route objectives

With a route token from the Routes API or Route Optimization API, you have more control over the route provided:

• Plan a route in advance for the Navigation SDK to use.

• Choose the best route for the Navigation SDK to use. If you request route tokens when generating routes in the Routes API, you get a route token for each generated route. You can then choose the token for the route you want to use when you pass it to the Navigation SDK.

• Estimate the price in advance, including estimations for ETA and distance. While the actual cost and time might vary, this estimation reduces the gap between expected and actual route cost.

• Specify more advanced route objectives, such as eco routing or the shortest route.

Tip: A route token is for one specific origin and destination and at a particular time. You must make a new Routes API or Route Optimization API request for a new route token.

How route tokens work

You can use the Routes API or Route Optimization API to plan a route using route objectives. You can pass a route token returned from either of these APIs to the Navigation SDK to guide how it routes your vehicle.

Here's what happens when you request and use a route token:

1. The Routes API or Route Optimization API returns an encrypted route token that includes the route polyline and route objectives.

2. You pass the route token to the Navigation SDK.

3. The Navigation SDK starts navigation on your planned route, even if a faster route is available.

4. During the trip, if traffic or road conditions change, or if the vehicle leaves the planned route, the Navigation SDK calculates a new route that follows the route objectives and routing options set in your route token.

This process maximizes how close the actual route is to your planned route.

Why a planned route may not be followed exactly

Navigation starts on your planned route, but the actual route can differ from it in situations like the following:

• The vehicle starts away from the planned starting point.
• Traffic or road conditions change during the trip.
• The vehicle leaves the planned route.

These differences can affect the distance, ETA, and other important trip qualities that you planned for.

Tip: As a best practice, always request a new route token every time you set the destination in the Navigation SDK, and plan for some variation to avoid any impact to your business.

Plan a route using a route token

You can plan a route by creating a route token and then passing it to the Navigation SDK, as described in the following steps:

Step 1: Create a route token using the Routes API or Route Optimization API

1. Request a route token with one of the following methods:

   • Routes API: computeRoutes. For more information about requesting a route token in the Routes API, see Compute a route and Get a route token.

   • Route Optimization API: optimizeTours or batchOptimizeTours. For more information about requesting a route token in the Route Optimization API, see Transition Polylines and Route Tokens.

2. Set up your Routes API request to meet the requirements for using a route token:

   • Set travelMode to DRIVE or TWO_WHEELER.
   • Set routingPreference to TRAFFIC_AWARE or TRAFFIC_AWARE_OPTIMAL.
   • Don't use Via waypoints.

Note: You can specify precise origin and destination values, such as entrances, loading docks, or designated pick-up areas, in your route token using a navigation point token.

Step 2: Pass the route token to the Navigation SDK

1. Store the route token: In the Navigation SDK, set up a string to store the route token. For example:

   String routeToken = "route token returned by Routes API";
   

   Example of a returned route token:

   {
   // Other fields
   "routeToken": "CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g",
   }
   

2. Pass the route token to the Navigation SDK using the Navigator.setDestinationsWithToken method. The Navigation SDK gets the destinations and routing options from the route token, so you don't need to pass waypoints or a travel mode.

   setDestinationsWithToken(String routeToken, RouteDescriptionLoadCallback callback);
   setDestinationsWithToken(String routeToken, DisplayOptions displayOptions, RouteDescriptionLoadCallback callback);
   

   Note: If your app uses a version of the Navigation SDK earlier than 8.1, use the deprecated setDestinations methods that take CustomRoutesOptions instead, and pass the same destination waypoints that you used to create the route token.

3. Check the route status in your callback. When the Navigation SDK finishes calculating the route, it passes a RouteDescription to your callback. If it finds a route from the vehicle's location to the destinations in your route token, RouteDescription.getRouteStatus returns Navigator.RouteStatus.OK, and you can start guidance. For example:

   navigator.setDestinationsWithToken(
       routeToken,
       routeDescription -> {
         if (routeDescription.getRouteStatus() == Navigator.RouteStatus.OK) {
           navigator.startGuidance();
         }
       });
   

Note: If you need to travel the same route again, request a new route token.

Check whether the Navigation SDK applied your route token

A route status of OK means that the Navigation SDK found a route, but not necessarily your planned route. To check whether the route matches your planned route, follow these steps in your callback:

1. Confirm that RouteDescription.getRouteStatus returns Navigator.RouteStatus.OK. The Navigation SDK provides route token details only when it finds a route. For more information, see Step 2.

2. Call RouteDescription.getRouteTokenExecutionDetails to get a RouteTokenExecutionDetails object. If the server doesn't provide route token details, this method returns null.

3. Call getTokenExecutionStatus on the RouteTokenExecutionDetails object. If it returns TOKEN_SUCCESSFULLY_APPLIED, the route matches your planned route. Any other status means that the route might differ from your planned route. For more information about each status, see Token execution status values.

4. Optional: If the status is TOKEN_SUCCESSFULLY_APPLIED, call getResolvedParameters on the same RouteTokenExecutionDetails object to check which routing options the route uses, such as whether it avoids tolls. For more information, see Resolved routing options.

Token execution status values

If the route status is OK, you can start guidance with any token execution status. The status tells you whether the route follows your planned route.

Status	Follows your planned route	Description
TOKEN_SUCCESSFULLY_APPLIED	Yes	The Navigation SDK applied your route token.
TOKEN_APPLIED_WITH_LOCATION_MISMATCH	Not necessarily	The Navigation SDK couldn't rebuild your planned route because a location in the route request was more than 25 meters from the matching location in your route token. With setDestinationsWithToken, this means that the device was more than 25 meters from the origin in your route token. The route still goes to your destinations, but the Navigation SDK can't confirm that it uses the routing options from your route token, such as toll avoidance.
TOKEN_IGNORED_OTHER	Not necessarily	The Navigation SDK couldn't rebuild your planned route for another reason, for example, because a road on your planned route is closed. The route still goes to your destinations, but the Navigation SDK can't confirm that it uses the routing options from your route token, such as toll avoidance.
NO_TOKEN_PROVIDED	Not applicable	The route request didn't include a route token.
UNKNOWN	Unknown	The status is unknown.

If the route doesn't necessarily follow your planned route and the exact route matters, for example, because you used it to calculate a price, log the status or request a new route token from the vehicle's current location.

Resolved routing options

getResolvedParameters returns a RouteTokenResolvedParameters object, or null if the routing options aren't available. RouteTokenResolvedParameters has the following methods:

• getTravelMode: The travel mode that the route uses, such as RoutingOptions.TravelMode.DRIVING. The Navigation SDK also reports RoutingOptions.TravelMode.DRIVING when the route uses a travel mode that has no matching value, or when the travel mode isn't available.
• getAvoidTolls: Whether the route avoids tolls.
• getAvoidHighways: Whether the route avoids highways.
• getAvoidFerries: Whether the route avoids ferries.

Example

The following code example demonstrates how to plan a route using a route token, check whether the Navigation SDK applied the token, and start guidance.

String routeToken = "route token returned by Routes API";

// Existing flow to get a Navigator.
NavigationApi.getNavigator(...);

// Handle the result of the route calculation.
RouteDescriptionLoadCallback callback =
    routeDescription -> {
      // Check whether the Navigation SDK found a route.
      if (routeDescription.getRouteStatus() != Navigator.RouteStatus.OK) {
        Log.w(TAG, "Route status: " + routeDescription.getRouteStatus());
        return;
      }

      // Check whether the Navigation SDK applied the route token.
      RouteTokenExecutionDetails executionDetails =
          routeDescription.getRouteTokenExecutionDetails();
      if (executionDetails == null) {
        Log.i(TAG, "Route token details aren't available.");
      } else if (executionDetails.getTokenExecutionStatus()
          != RouteTokenExecutionDetails.TokenExecutionStatus.TOKEN_SUCCESSFULLY_APPLIED) {
        Log.w(TAG, "The route might differ from your planned route.");
      }

      navigator.startGuidance();
    };

// Set destinations using the route token.
navigator.setDestinationsWithToken(routeToken, callback);

// Or with display options.
DisplayOptions displayOptions = new DisplayOptions();
navigator.setDestinationsWithToken(routeToken, displayOptions, callback);

Note: You can configure a maximum of 25 waypoints.

How route tokens and the Navigation SDK interact

Here's how the Navigation SDK handles your planned route:

• Overrides any previously set destinations.

• Uses the vehicle starting location.

• Adjusts for road and traffic conditions. See Why a planned route might not be followed exactly.

• Uses the routing options set in your route token instead of the following settings in your app, including when it calculates a new route during the trip:

  • RoutingOptions.avoidHighways
  • RoutingOptions.avoidTolls
  • RoutingOptions.avoidFerries
  • Navigator.setLicensePlateRestrictionInfo
  • The travel mode set in your app

• Follows these settings when it calculates or adjusts the route:

  • Route objectives from your route token, such as eco routing or the shortest route. If the Navigation SDK has to adjust the route, it uses the route objectives that you specified when you requested the route token.
  • Waypoint-related options from your route token, such as the side-of-road preference.

Note: With setDestinationsWithToken, you don't pass waypoints, so the Navigation SDK uses the destinations and waypoint options from your route token. To set waypoint options, such as the side-of-road preference or vehicle stopovers, use the sideOfRoad and vehicleStopover fields on the waypoints in your Routes API request. The origin is always the device's location, so options that you set on the origin in your Routes API request don't apply.