Route Tokens

When you are determining the best route for a ridesharing trip, the fastest route may not always be the best option. You may want to customize your route. The Routes Preferred API lets you customize a route by specifying a route objective using the ComputeCustomRoutes method.

When you create a custom route, the Routes Preferred API generates a route token. You can then pass the token to the Navigation SDK for Android and retrieve the custom route.

For more information on creating a custom route, see Create Custom Routes.

Retrieving a custom route

You can retrieve a custom route by passing a route token to the Navigation SDK for Android using the Navigator.setDestinations method.

setDestinations(List<Waypoint> destinations, CustomRoutesOptions customRoutesOptions, DisplayOptions displayOptions);

The custom route overrides any previously set destinations. It uses the corresponding driver starting location, and road and traffic conditions.

Navigator.setDestinations takes the following parameters:

destinations The new destination list to be set.
customRoutesOptions The options that will be used to retrieve a precomputed route, based on a token returned by the Routes Preferred API.
displayOptions The options that will be used to display the route.

The Navigator.setDestinations method returns the status of the request. If a route is found from the user's location to the given destination, it returnsRouteStatus.OK.


The following code example demonstrates how to retrieve a custom route.

ArrayList <Waypoint> destinations = Lists.newArrayList();
Waypoint waypoint1 =
      .setLatLng(10, 20)
Waypoint waypoint2 =

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

CustomRoutesOptions customRoutesOptions =

// Existing flow to get a Navigator.
// Existing flow for requesting routes.
ListenableResultFuture<RouteStatus> routeStatusFuture =
          navigator.setDestinations(destinations, customRoutesOptions);

// Or with display options.
DisplayOptions displayOptions = new DisplayOptions();

ListenableResultFuture<RouteStatus> routeStatusFuture =
          navigator.setDestinations(destinations, customRoutesOptions, displayOptions);