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:

Parameter	Description
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.

Example

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

ArrayList <Waypoint> destinations = Lists.newArrayList();
Waypoint waypoint1 =
   Waypoint.builder()
      .setLatLng(10, 20)
      .setTitle("title")
      .setVehicleStopover(true)
      .build();
destinations.add(waypoint1);
Waypoint waypoint2 =
   Waypoint.builder()
      .setPlaceId("ChIJYV-J-ziuEmsRIMyoFaMedU4")
      .setTitle("title")
      .setVehicleStopover(true)
       .build()
destinations.add(waypoint2);

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

CustomRoutesOptions customRoutesOptions =
   CustomRoutesOptions.builder()
      .setRouteToken(routeToken)
      .setTravelMode(CustomRoutesOptions.TravelMode.TWO_WHEELER)
      .build();

// Existing flow to get a Navigator.
NavigationApi.getNavigator(...);
// 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);