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](https://developers.google.com/maps/documentation/geocoding/navigation-point-tokens). 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](https://developers.google.com/maps/documentation/geocoding/navigation-point-tokens) response.

2. Specify that `navigationPointToken` when you create a `GMSNavigationWaypoint`.

> [!NOTE]
> **Note:** You can't use a navigation point token together with a location or a Place ID in the same waypoint. If you do, the request fails with an error message.

<br />

### Swift

<br />

    // 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)
    }

<br />

### Objective-C

<br />

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

<br />

<br />

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

<br />

> [!NOTE]
> **Note:** If your app uses a version of the Navigation SDK earlier than 11.3, use the deprecated `setDestinations:routeToken:callback:` method instead, and pass a `GMSNavigationWaypoint` with the same navigation point token that you used to create the route 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](https://developers.google.com/maps/documentation/routes/specify_location#navigation_point_token)
and [Get a route token](https://developers.google.com/maps/documentation/routes/route_token). To learn how to
plan a route using a route token, see
[Plan a route](https://developers.google.com/maps/documentation/navigation/ios-sdk/route-customizations).

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.

<br />

![Rideshare or delivery use case diagram](https://developers.google.com/static/maps/documentation/navigation/ios-sdk/images/navigation-point-token-diagram.svg) Diagram of a rideshare or delivery use case

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

<br />

### Swift

<br />

    // 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)
    }

<br />

### Objective-C

<br />

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

<br />

<br />

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

| Specification | `location` | `placeID` | `navigationPointToken` | Routing behavior | Destination highlighting |
|---|---|---|---|---|---|
| Location coordinates only | set | absent | absent | Routes to road segment nearest to the defined coordinates | Shown if destination can be inferred with high confidence |
| Place ID only | absent | set | absent | Routes to the default navigation point for the Place ID | From Place ID |
| Navigation point token only | absent | absent | set | Routes to the precise navigation point represented by the token | From destination defined in original [destinations method of the Geocoding API](https://developers.google.com/maps/documentation/geocoding/navigation-point-tokens) request |
| Location coordinates and Place ID combined | set | set | absent | Routes to road segment nearest to the defined coordinates | From Place ID, though not shown if Place ID is too far from the latitude/longitude coordinates |