GoogleNavigation Framework Reference

GMSNavigator

@interface GMSNavigator : NSObject

This is the main class of the Google Navigation SDK for iOS and provides methods for controlling navigation to a destination and accessing route and progress information.

This class does not support subclassing.

This class is not thread-safe. All methods must be called from the main thread.

Destinations and Routes

  • Sets multiple destinations for navigation, overriding any previously set destinations.

    The provided callback will be called with GMSRouteStatusOK if a route is found from the device’s location to the given destination. If a new destination is set before a route is found, then the request will be canceled, and the callback will be called with GMSRouteStatusCanceled. If a route cannot be found for any other reason, the callback will be called with an appropriate error status.

    The callback will always be dispatched asynchronously on the main queue.

    Declaration

    Swift

    func setDestinations(_ destinations: [GMSNavigationWaypoint], callback: @escaping GMSRouteStatusCallback)

    Objective-C

    - (void)setDestinations:(nonnull NSArray<GMSNavigationWaypoint *> *)destinations
               callback:(nonnull GMSRouteStatusCallback)callback;

  • Sets multiple destinations for navigation, overriding any previously set destinations. The returned routes are calculated using routing options.

    Declaration

    Swift

    func setDestinations(_ destinations: [GMSNavigationWaypoint], routingOptions: GMSNavigationRoutingOptions, callback: @escaping GMSRouteStatusCallback)

    Objective-C

    - (void)setDestinations:(nonnull NSArray<GMSNavigationWaypoint *> *)destinations
         routingOptions:(nonnull GMSNavigationRoutingOptions *)routingOptions
               callback:(nonnull GMSRouteStatusCallback)callback;

    Parameters

    destinations

    An array of destination waypoints.
    routingOptions

    The options that influence routing logic (routing strategy).
    callback

    Called when a route from the consumer’s location to the provided destination(s) is found, or fails to be found for a reason indicated by the RouteStatus.

  • Sets multiple destinations for navigation, using a route token to navigate on a precomputed route. Routes will be the same, modulo changes to the driver starting location and to road/traffic conditions. Re-routes will still occur based on the routing options encoded in the token.

    Only GMSNavigationTravelModeDriving and GMSNavigationTravelModeTwoWheeler are supported when you use the route token to start a navigation session. Configure the travel mode by setting travelMode. The call will fail if the current travel mode is unsupported, and a GMSRouteStatusTravelModeUnsupported will be returned in the callback.

    Declaration

    Swift

    func setDestinations(_ destinations: [GMSNavigationWaypoint], routeToken: String, callback: @escaping GMSRouteStatusCallback)

    Objective-C

    - (void)setDestinations:(nonnull NSArray<GMSNavigationWaypoint *> *)destinations
             routeToken:(nonnull NSString *)routeToken
               callback:(nonnull GMSRouteStatusCallback)callback;

    Parameters

    destinations

    An array of destination waypoints, should be the same as the destinations given to RoutesPreferred API to get the route token.
    routeToken

    A route token string returned by RoutesPreferred API. Routing options specified in RoutesPreferred API are encoded in this route token, and will be used to regenerate the precomputed route or a new route when reroute happens.
    callback

    Called when a route from the consumer’s location to the provided destination(s) is found, or fails to be found for a reason indicated by the RouteStatus.

  • Returns route information based on the routing strategy: default best or shorter route. This method is only available to Mobility Services customers who are billed by Google on a per-transaction basis. Returns a nil value if the project lacks permission to call this API.

    Declaration

    Swift

    func getRouteInfo(forDestination destination: GMSNavigationWaypoint, with routingOptions: GMSNavigationRoutingOptions, callback: @escaping GMSRouteInfoCallback)

    Objective-C

    - (void)getRouteInfoForDestination:(nonnull GMSNavigationWaypoint *)destination
                withRoutingOptions:
                    (nonnull GMSNavigationRoutingOptions *)routingOptions
                          callback:(nonnull GMSRouteInfoCallback)callback;

    Parameters

    destination

    The destination waypoint.
    routingOptions

    The options used to fetch the route info. The routing strategy and alternate routes strategy are ignored since this method returns the route information for all routing strategies.
    callback

    The callback called when routes information are received.

  • Deprecated

    Use one of the -setDestinations:… methods instead.

    Deprecated. Call one of the -setDestinations:... methods with the new list of destinations instead.

    Pops the first destination from the current list of destinations. Following this call, guidance will be toward the next destination, if any.

    Declaration

    Swift

    func continueToNextDestination() -> GMSNavigationWaypoint?

    Objective-C

    - (nullable GMSNavigationWaypoint *)continueToNextDestination;

    Return Value

    the waypoint guidance is now heading towards, or nil if there are no more waypoints left.

  • Clears all previously set destinations and removes any calculated routes from the map. If guidance is active, this will automatically stop it.

    Declaration

    Swift

    func clearDestinations()

    Objective-C

    - (void)clearDestinations;

  • Whether to avoid highways when generating routes to destinations. Defaults to NO.

    Declaration

    Swift

    var avoidsHighways: Bool { get set }

    Objective-C

    @property (nonatomic) BOOL avoidsHighways;

  • Whether to avoid toll roads when generating routes to destinations. Defaults to NO.

    Declaration

    Swift

    var avoidsTolls: Bool { get set }

    Objective-C

    @property (nonatomic) BOOL avoidsTolls;

  • Whether to avoid ferries when generating routes to destinations. Defaults to YES.

    Declaration

    Swift

    var avoidsFerries: Bool { get set }

    Objective-C

    @property (nonatomic) BOOL avoidsFerries;

  • Set license plate restriction with current driver’s last digit of license plate and country code. This allows us to route around certain types of road restrictions which are based on license plate number. This will only apply to setDestinations calls made after this value is set. Ideally you’d set this immediately after getting the navigator.

    Set to nil if there is no license plate restriction. Default to nil.

    Declaration

    Swift

    var licensePlateRestriction: GMSNavigationLicensePlateRestriction? { get set }

    Objective-C

    @property (nonatomic, nullable) GMSNavigationLicensePlateRestriction *licensePlateRestriction;

Guidance

  • Whether turn-by-turn guidance is currently enabled. If guidanceActive is YES, but no route is currently available then guidance will start when a route becomes available. This property will be set to NO if clearDestinations is called, or we arrive at a waypoint.

    Declaration

    Swift

    var isGuidanceActive: Bool { get set }

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite,
          getter=isGuidanceActive) BOOL guidanceActive;

  • Whether guidance should automatically stop when -navigator:didArriveAtWaypoint: is called.

    When NO, the navigation header and footer will continue to be shown after arrival. The navigation header will continue to show the final guidance step and the navigation footer will continue to update the remaining time and distance until a time/distance of 0 is reached. Additionally, -navigator:didUpdateRemainingTime and -navigator:didUpdateRemainingDistance updates will continue. Explicitly set guidanceActive to NO to stop guidance and remaining time/distance updates.

    When YES, guidanceActive will automatically be set to NO upon arrival.

    Defaults to YES.

    Declaration

    Swift

    var stopGuidanceAtArrival: Bool { get set }

    Objective-C

    @property (nonatomic) BOOL stopGuidanceAtArrival;

  • The minimum change in estimated time to the next destination that will trigger the -navigator:didUpdateRemainingTime: method to be called.

    If this is set to NSTimeIntervalMax, then time update callbacks will be disabled. If this is set to a negative value, then the default threshold of one second will be used. Defaults to one second.

    Note

    This value is ignored if no listeners implement navigator:didUpdateRemainingTime:.

    Declaration

    Swift

    var timeUpdateThreshold: TimeInterval { get set }

    Objective-C

    @property (nonatomic) NSTimeInterval timeUpdateThreshold;

  • The minimum change in estimated distance to the next destination that will trigger the -navigator:didUpdateRemainingDistance: method to be called.

    If this is set to CLLocationDistanceMax, then distance update callbacks will be disabled. If this is set to a negative value, then the default threshold of one meter will be used. Defaults to one meter.

    Note

    This value is ignored if no listeners implement navigator:didUpdateRemainingDistance:.

    Declaration

    Swift

    var distanceUpdateThreshold: CLLocationDistance { get set }

    Objective-C

    @property (nonatomic) CLLocationDistance distanceUpdateThreshold;

  • Returns the estimated time to the next destination. This will be updated based on the current device position whilst guidance is active.

    Declaration

    Swift

    var timeToNextDestination: TimeInterval { get }

    Objective-C

    @property (nonatomic, readonly) NSTimeInterval timeToNextDestination;

    Return Value

    CLTimeIntervalMax if no route is available.

  • Returns the estimated distance to the next destination. This will be updated based on the current device position whilst guidance is active.

    Declaration

    Swift

    var distanceToNextDestination: CLLocationDistance { get }

    Objective-C

    @property (nonatomic, readonly) CLLocationDistance distanceToNextDestination;

    Return Value

    CLLocationDistanceMax if no route is available.

  • Returns the delay category to the next destination. This will be updated based on the current device position whilst guidance is active.

    Declaration

    Swift

    var delayCategoryToNextDestination: GMSNavigationDelayCategory { get }

    Objective-C

    @property (nonatomic, readonly) GMSNavigationDelayCategory delayCategoryToNextDestination;

    Return Value

    GMSNavigationDelayCategoryNoData if no route is available or traffic data is unavailable.

  • Returns the estimated time to the given waypoint, or CLTimeIntervalMax if the waypoint is not part of the current route. This is updated based on the current device position while guidance is active.

    Declaration

    Swift

    func time(to waypoint: GMSNavigationWaypoint) -> TimeInterval

    Objective-C

    - (NSTimeInterval)timeToWaypoint:(nonnull GMSNavigationWaypoint *)waypoint;

    Return Value

    CLTimeIntervalMax if the provided waypoint is not a destination in the current route.

  • Returns the estimated distance to the given waypoint, or CLLocationDistanceMax if the waypoint is not part of the current route. This will be updated based on the current device position whilst guidance is active.

    Declaration

    Swift

    func distance(to waypoint: GMSNavigationWaypoint) -> CLLocationDistance

    Objective-C

    - (CLLocationDistance)distanceToWaypoint:
    (nonnull GMSNavigationWaypoint *)waypoint;

    Return Value

    CLLocationDistanceMax if the provided waypoint is not a destination in the current route.

  • The current leg of the journey. This GMSRouteLeg will have its starting position as the most recent known (road-snapped) position of the device.

    Declaration

    Swift

    var currentRouteLeg: GMSRouteLeg? { get }

    Objective-C

    @property (nonatomic, readonly, nullable) GMSRouteLeg *currentRouteLeg;

  • An array of route legs where each leg corresponds to a destination that was set.

    Declaration

    Swift

    var routeLegs: [GMSRouteLeg]? { get }

    Objective-C

    @property (nonatomic, readonly, nullable) NSArray<GMSRouteLeg *> *routeLegs;

  • The path that the user has traveled in the most recent guidance session, defined as the last time guidanceActive was set to YES. The path consists of road-snapped locations returned by the GMSRoadSnappedLocationProvider and simplified to produce line segments. Note: The system polls the client for GPS signals to obtain location data. Poor GPS signal can result in further interpolation, which might produce less precise routes. This path is empty if guidance has never started.

    Declaration

    Swift

    var traveledPath: GMSPath { get }

    Objective-C

    @property (nonatomic, readonly) GMSPath *_Nonnull traveledPath;

Audio guidance

  • Determines whether voice guidance should be enabled for traffic and turn-by-turn alerts.

    Defaults to GMSNavigationVoiceGuidanceAlertsAndGuidance.

    Declaration

    Swift

    var voiceGuidance: GMSNavigationVoiceGuidance { get set }

    Objective-C

    @property (nonatomic) GMSNavigationVoiceGuidance voiceGuidance;

  • Determines what audio devices voice guidance may be played through.

    Defaults to GMSVoiceGuidanceAudioDeviceTypeBluetooth.

    Declaration

    Swift

    var audioDeviceType: GMSVoiceGuidanceAudioDeviceType { get set }

    Objective-C

    @property (nonatomic) GMSVoiceGuidanceAudioDeviceType audioDeviceType;

  • Determines whether the device should also vibrate when voice alerts are played.

    Declaration

    Swift

    var isVibrationEnabled: Bool { get set }

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite,
          getter=isVibrationEnabled) BOOL vibrationEnabled;

  • Determines whether UILocalNotifications containing guidance information will be presented when the app is in the background. Defaults to YES.

    Declaration

    Swift

    var sendsBackgroundNotifications: Bool { get set }

    Objective-C

    @property (nonatomic) BOOL sendsBackgroundNotifications;

  • The suggested lighting mode, based on the time of day and device location.

    Declaration

    Swift

    var suggestedLightingMode: GMSNavigationLightingMode { get }

    Objective-C

    @property (nonatomic, readonly) GMSNavigationLightingMode suggestedLightingMode;

  • Determines whether prompts for traffic, better routes and incidents should be displayed. Defaults to YES.

    Declaration

    Swift

    var shouldDisplayPrompts: Bool { get set }

    Objective-C

    @property (nonatomic) BOOL shouldDisplayPrompts;

  • GMSNavigationSpeedAlertOptions for customizing the triggering thresholds for GMSNavigationSpeedAlertSeverity.

    You can use this property to customize the speed alert triggering thresholds in percentage for both minor and major alerts. You can also use this method to customize the time based triggering threshold for major speed alert.

    By setting nil, you won’t receive any speeding feed data, and the NavSDK’s default speed alert will display: speed alert shows red text when the speed is more than 5 mph or 10 kph over the speed limit, and shows white text and red background when speeding more than 10 mph or 20kph.

    Declaration

    Swift

    var speedAlertOptions: GMSNavigationSpeedAlertOptions? { get set }

    Objective-C

    @property (nonatomic, nullable) GMSNavigationSpeedAlertOptions *speedAlertOptions;

Transaction IDs

  • Sets and logs to the server the ongoing transaction IDs that apply to the navigation events during the current navigation session. Transaction IDs will be cleared at the end of the navigation session. This method is only available to Mobility Services customers who are billed by Google on a per-transaction basis. Returns a nil value if the project lacks permission to call this API.

    Declaration

    Swift

    func setTransactionIDs(_ transactionIDs: [String], errorHandler: GMSNavigationTransactionIDErrorHandler? = nil)

    Objective-C

    - (void)setTransactionIDs:(nonnull NSArray<NSString *> *)transactionIDs
             errorHandler:
                 (nullable GMSNavigationTransactionIDErrorHandler)errorHandler;

    Parameters

    transactionIDs

    The transaction IDs that apply to the current navigation session. The transaction ID must be unique for each billable transaction. An individual transaction ID must contain at least one and at most 64 characters. The list can be empty when a transaction has ended (but the session is still ongoing).
    errorHandler

    A block that will be invoked asynchronously on the main thread if an error occurs when the transaction IDs are invalid.