Navigate a route

Follow this guide to plot a route within your app to a single destination, using the Navigation SDK for iOS.

Overview

  1. Integrate the Navigation SDK into your app, as described in the Set up your project section.
  2. Configure a GMSMapView.
  3. Prompt the user to accept the terms and conditions, and authorize location services and background notifications.
  4. Create an array containing one or more destinations.
  5. Define a GMSNavigator to control turn-by-turn navigation.

See the code

Prompt the user for the necessary authorizations

Before using the Navigation SDK, the user must agree to the terms and conditions, and authorize the use of location services, which is required for navigation. If your app will run in the background, it must also prompt the user to authorize guidance alert notifications. This section shows how to display the required authorization prompts.

Authorize location services

The Navigation SDK uses location services, which requires user authorization. To enable location services and display the authorization dialog, take these steps:

  1. Add the NSLocationAlwaysUsageDescription key to Info.plist.
  2. For the value, add a short explanation of why your app requires location services. For example: "This app needs permission to use location services for turn-by-turn navigation."

  3. To display the authorization dialog, call requestAlwaysAuthorization() of the location manager instance.

Swift

self.locationManager.requestAlwaysAuthorization()

Objective-C

[_locationManager requestAlwaysAuthorization];

Authorize alert notifications for background guidance

The Navigation SDK needs user permission to provide alert notifications when the app is running in the background. Add the following code to prompt the user for permission to display these notifications:

Swift

UNUserNotificationCenter.current().requestAuthorization(options: [.alert]) {
  granted, error in
    // Handle denied authorization to display notifications.
    if !granted || error != nil {
      print("User rejected request to display notifications.")
    }
}

Objective-C

// Request authorization for alert notifications.
UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
UNAuthorizationOptions options = UNAuthorizationOptionAlert;
[center requestAuthorizationWithOptions:options
                      completionHandler:
 ^(
   BOOL granted,
   NSError *_Nullable error) {
     if (!error && granted) {
       NSLog(@"iOS Notification Permission: newly Granted");
     } else {
       NSLog(@"iOS Notification Permission: Failed or Denied");
     }
   }];

Accept the terms and conditions

Use the following code to show the terms and conditions dialog, and enable navigation when the user accepts the terms. Note that this example includes the code for location services and guidance alert notifications (shown previously).

Swift

  let termsAndConditionsOptions = GMSNavigationTermsAndConditionsOptions(companyName: "Ride Sharing Co.")

  GMSNavigationServices.showTermsAndConditionsDialogIfNeeded(
    with: termsAndConditionsOptions) { termsAccepted in
    if termsAccepted {
      // Enable navigation if the user accepts the terms.
      self.mapView.isNavigationEnabled = true
      self.mapView.settings.compassButton = true

      // Request authorization to use location services.
      self.locationManager.requestAlwaysAuthorization()

      // Request authorization for alert notifications which deliver guidance instructions
      // in the background.
    UNUserNotificationCenter.current().requestAuthorization(options: [.alert]) {
      granted, error in
        // Handle rejection of notification authorization.
        if !granted || error != nil {
          print("Authorization to deliver notifications was rejected.")
        }
      }
    } else {
      // Handle rejection of terms and conditions.
    }
  }

Objective-C

GMSNavigationTermsAndConditionsOptions *termsAndConditionsOptions = [[GMSNavigationTermsAndConditionsOptions alloc] initWithCompanyName:@"Ride Sharing Co."];

[GMSNavigationServices
  showTermsAndConditionsDialogIfNeededWithOptions:termsAndConditionsOptions
  callback:^(BOOL termsAccepted) {
   if (termsAccepted) {
     // Enable navigation if the user accepts the terms.
     _mapView.navigationEnabled = YES;
     _mapView.settings.compassButton = YES;

     // Request authorization to use the current device location.
     [_locationManager requestAlwaysAuthorization];

     // Request authorization for alert notifications which deliver guidance instructions
     // in the background.
     UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
     UNAuthorizationOptions options = UNAuthorizationOptionAlert;
     [center requestAuthorizationWithOptions:options
                           completionHandler:
     ^(
       BOOL granted,
       NSError *_Nullable error) {
         if (!error && granted) {
           NSLog(@"iOS Notification Permission: newly Granted");
         } else {
           NSLog(@"iOS Notification Permission: Failed or Denied");
         }
       }];
   } else {
     // Handle rejection of the terms and conditions.
   }
 }];

Create a route and start guidance

To plot a route, call the Navigator’s setDestinations() method with an array containing one or more destinations (GMSNavigationWaypoint) to visit. If successfully computed, the route is shown on the map. To start guidance along the route, beginning with the first destination, set isGuidanceActive to true in the callback.

The following example shows:

  • Creating a new route with two destinations.
  • Starting guidance.
  • Enabling background guidance notifications.
  • Simulating travel along the route (optional).
  • Setting the camera mode to "follow" (optional).

Swift

func startNav() {
  var destinations = [GMSNavigationWaypoint]()
  destinations.append(GMSNavigationWaypoint.init(placeID: "ChIJnUYTpNASkFQR_gSty5kyoUk",
                                                 title: "PCC Natural Market")!)
  destinations.append(GMSNavigationWaypoint.init(placeID:"ChIJJ326ROcSkFQRBfUzOL2DSbo",
                                                 title:"Marina Park")!)

  mapView.navigator?.setDestinations(destinations) { routeStatus in
    self.mapView.navigator?.isGuidanceActive = true
    self.mapView.locationSimulator?.simulateLocationsAlongExistingRoute()
    self.mapView.cameraMode = .following
  }
}

Objective-C

- (void)startNav {
  NSArray<GMSNavigationWaypoint *> *destinations =
  @[[[GMSNavigationWaypoint alloc] initWithPlaceID:@"ChIJnUYTpNASkFQR_gSty5kyoUk"
                                             title:@"PCC Natural Market"],
    [[GMSNavigationWaypoint alloc] initWithPlaceID:@"ChIJJ326ROcSkFQRBfUzOL2DSbo"
                                             title:@"Marina Park"]];

  [_mapView.navigator setDestinations:destinations
                             callback:^(GMSRouteStatus routeStatus){
                               [_mapView.locationSimulator simulateLocationsAlongExistingRoute];
                               _mapView.navigator.guidanceActive = YES;
                               _mapView.cameraMode = GMSNavigationCameraModeFollowing;
                             }];
}

To learn about Place IDs please refer to Place IDs.

Set travel mode

Travel mode determines which type of route will be fetched, and the way that the user's course is determined. You can set one of four travel modes for a route: driving, cycling, walking, and taxi. In driving and taxi mode, the user's course is based on the direction of travel; in cycling and walking mode the course is represented by the direction the device is facing.

Set the travelMode property of the map view, as shown in the following example:

Swift

self.mapView.travelMode = .cycling

Objective-C

_mapView.travelMode = GMSNavigationTravelModeCycling;

Set roads to avoid

Use the avoidsHighways and avoidsTolls BOOL properties to avoid highways and/or toll roads along a route.

Swift

self.mapView.navigator?.avoidsTolls = true

Objective-C

_mapView.navigator.avoidsTolls = YES;

PlaceID finder

You can use the PlaceID Finder to find place IDs to use for route destinations. Add a destination from a placeID with GMSNavigationWaypoint.

Floating text

You can add floating text anywhere in your app, as long as the Google attribution isn't covered. The Navigation SDK doesn't support anchoring the text to a latitude/longitude on the map, or to a label. For more information, see Info windows.