Route to navigation points

The Navigation SDK for iOS offers enhanced ways to specify waypoints, or navigation points, providing more accurate routing and a better arrival experience, especially for destinations with multiple entrances or specific navigation points. You can route to precise locations using a navigationPointToken, which is a string that encodes a location and additional route context. You can also combine latitude and longitude coordinates with a Place ID for added context.

Background

Before v10.10, you could define a Waypoint using either location coordinates or a Place ID. While sometimes effective, routing solely to a latitude and longitude can sometimes lead to suboptimal drop-off or pick-up points, particularly for large venues, parks, or buildings with multiple entrances. The result might snap to the nearest road segment, which may not be the most convenient or correct access point.

The enhanced waypoint options address this by allowing you to provide more context.

Use a navigation point token

For the most precise routing to specific access points such as entrances, loading docks, or designated pick-up areas, you can use a navigationPointToken.

This token is obtained by calling the Destinations method of the Geocoding API. It represents a specific, routable navigation point associated with a place.

To specify a navigation point token:

1. Obtain a navigationPointToken from the SearchDestinations method of the Geocoding API response.

2. Specify that navigationPointToken when you create a GMSNavigationWaypoint.

// Create a waypoint using a navigation endpoint token
let waypointTwo = GMSNavigationWaypoint(
  navigationPointToken: "ChIJALijSXPhQkARHmIozCCbXsASEgkFVjYHGH6PgBFrbM7wl3..",
  title: "Sydney Opera House")

// Route to the waypoint
navigator.setDestinations([waypointTwo]) { [weak self] routeStatus in
   self?.handleRouteCallback(status: routeStatus)
}

GMSNavigationWaypoint *waypointTwo =
    [[GMSNavigationWaypoint alloc] initWithNavigationPointToken:@"sampleNavigationPointToken"
                                                          title:@"Sydney Opera House"];

Use navigation point tokens and route tokens

You can retrieve a navigation point token through the Geocoding API, use it in a Routes API request to get a route token, and then pass only the route token to the Navigation SDK. The route token keeps the precision of the navigation point token. This is useful in scenarios such as rideshare or delivery, where you use the Routes API to calculate a trip price and you want the precision of a navigation point token.

With the route token, the Navigation SDK starts navigation on the same route that you used to calculate the price. This reduces the risk of longer or shorter routes being used for the trip, which can create "price shocks."

For more information about navigation point tokens and route tokens in the Routes API, see Specify locations for a route and Get a route token. To learn how to plan a route using a route token, see Plan a route.

The following diagram shows how a rideshare or delivery app would use navigation point tokens and route tokens together. Starting with version 11.3, the driver app passes only the route token to the Navigation SDK in step 7.

Combine Place ID and location

Starting with v10.10, you can provide both a Place ID and location coordinates when creating a waypoint. This method is useful when you want to specify a precise point (the location) while still providing the context of the overall place (the Place ID). This allows the Navigation SDK to provide a richer arrival experience by highlighting the destination building or showing nearby points of interest related to the Place ID.

// Create a waypoint using both the latlng and placeID
let waypoint = GMSNavigationWaypoint(
  location: CLLocationCoordinate2DMake(-33.85657945261524, 151.21535034203333),  
  placeID: "ChIJ3S-JXmauEmsRUcIaWtf4MzE",
  title: "Sydney Opera House")

// Route to the waypoint
navigator.setDestinations([waypoint]) { [weak self] routeStatus in
   self?.handleRouteCallback(status: routeStatus)
}

CLLocationCoordinate2D location = CLLocationCoordinate2DMake(47.67, -122.20);
GMSNavigationWaypoint *waypoint = [[GMSNavigationWaypoint alloc] initWithLocation:placeID:coordinate title:@"waypoint from location and placeiD"];

Considerations

When you provide both placeID and location:

• The route primarily targets the specified location.
• The placeID provides context that enhances the arrival experience.
• Fallback: If the SDK determines that the provided placeID corresponds to a feature that's too far from the given location, it ignores the placeID. In this scenario, routing proceeds to the location only, and the place-specific arrival experience enhancements aren't available.

Summary of valid waypoint configurations