Plan a route

Page Summary

• Route tokens let you plan routes in advance, optimizing for factors like time, fuel, or safety, and can be generated using the Routes, Routes Preferred, or Route Optimization API.

• While the Navigation SDK attempts to follow the planned route, real-world conditions may cause deviations; it dynamically adjusts while prioritizing the specified route objectives.

• You create a route token via the Routes, Routes Preferred, or Route Optimization API, then pass it to the Navigation SDK's setDestinations method alongside your waypoints.

• The Navigation SDK prioritizes the route token's plan but dynamically adapts to real-time conditions, potentially leading to variations between the planned and actual route.

• Always request a fresh route token for each trip and anticipate potential route adjustments to ensure smooth navigation and accurate estimations.

Note: Updates to how the Navigation SDK follows planned routes, including the new betterRouteTimeTolerance field, are rolling out gradually and will be available to all projects by October 22, 2026. Until then, the Routes API might reject requests that include betterRouteTimeTolerance.

At times, you might want to plan the route your app provides to users. Using a route token from the Routes API, Routes Preferred 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, Routes Preferred 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, Routes Preferred API, or Route Optimization API request for a new route token.

How route tokens work

You can use the Routes API, Routes Preferred API, or Route Optimization API to plan a route using route objectives. You can pass a route token returned from any 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, Routes Preferred 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, Routes Preferred 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.

   • Routes Preferred API: computeCustomRoutes. For more information about requesting a route token in the Routes Preferred API, see Plan a route.

   • 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 or Routes Preferred 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, like entrances, loading docks, or designated pick-up areas, in your route token by 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:

   let 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 mapView.navigator.setDestinations. Specify the same destination waypoints that you used when creating the route token:

   mapView.navigator?.setDestinations([waypoint1, waypoint2], routeToken: routeToken, callback: {...})
   

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

   The setDestinations method passes the status of the request to its callback. If it finds a route from the user's location to the given destination, the status is .OK (GMSRouteStatusOK).

Multi-stop scenarios

You can configure a maximum of 25 waypoints.

The setDestinations method does not support multi-stop journeys. Use continueToNextDestinationWithCompletion() to advance the waypoint to the next leg of the journey.

Caution: Calling the continueToNextDestinationWithCompletion() method can sometimes result in an incorrect arrival event, where the just-completed destination appears to be re-selected.

Example

The following code examples demonstrate how to retrieve a planned route.

Swift

let location = CLLocationCoordinate2D(latitude: 47.67, longitude: -122.20)
let waypoint1 = GMSNavigationWaypoint(location: location, title: "waypoint from location")!
let waypoint2 = GMSNavigationWaypoint(placeID: "samplePlaceID", title: "waypoint from Place ID")!

let routeToken = "route token returned by Routes API"
mapView.navigator?.setDestinations([waypoint1, waypoint2], routeToken: routeToken, callback: {...})

Objective-C

CLLocationCoordinate2D location = CLLocationCoordinate2DMake(47.67, -122.20);
GMSNavigationWaypoint *waypoint1 = [[GMSNavigationWaypoint alloc] initWithLocation:location title:@"waypoint from location"];
GMSNavigationWaypoint *waypoint2 = [[GMSNavigationWaypoint alloc] initWithPlaceID:@"samplePlaceID"
                                                                            title:@"waypoint from Place ID"];
NSString *routeToken = @"route token returned by Routes API";

[mapView.navigator setDestinations:@[waypoint1, waypoint2]
                        routeToken:routeToken
                          callback:^(GMSRouteStatus routeStatus){...}];

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:

  • avoidsHighways
  • avoidsTolls
  • avoidsFerries
  • licensePlateRestriction
  • 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 app, such as the side-of-road preference. Use the same waypoint-related options that you specified when you requested the route token.