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]
> **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](https://developers.google.com/maps/documentation/routes/route_token) in
Routes API and [Transition Polylines and Route
Tokens](https://developers.google.com/maps/documentation/route-optimization/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]
> **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]
> **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](https://developers.google.com/maps/documentation/routes/compute_route_directions)
     and [Get a route token](https://developers.google.com/maps/documentation/routes/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](https://developers.google.com/maps/documentation/route-optimization/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]
> **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](https://developers.google.com/maps/documentation/navigation/android-sdk/navigation-points#use_a_navigation_point_token).

### Step 2: Pass the route token to the Navigation SDK

<br />

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);

   <br />

   > [!NOTE]
   > **Note:** If your app uses a version of the Navigation SDK earlier than 8.1, use the deprecated [`setDestinations` methods that take `CustomRoutesOptions`](https://developers.google.com/maps/documentation/navigation/android-sdk/reference/com/google/android/libraries/navigation/Navigator#public-abstract-listenableresultfuturenavigator.routestatus-setdestinations-listwaypoint-destinations,-customroutesoptions-customroutesoptions,-displayoptions-displayoptions) 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]
> **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](https://developers.google.com/maps/documentation/navigation/android-sdk/customize-route#use-token-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](https://developers.google.com/maps/documentation/navigation/android-sdk/customize-route#token-execution-status).

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](https://developers.google.com/maps/documentation/navigation/android-sdk/customize-route#resolved-parameters).

#### 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.

<br />

### 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]
> **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](https://developers.google.com/maps/documentation/navigation/android-sdk/customize-route#not-followed).

<!-- -->

- **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]
> **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.