TomTomSDKNavigation

  • TomTomArrivalDetectionEngine checks if the driver has reached the destination or waypoint.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public class TomTomArrivalDetectionEngine : ArrivalDetectionEngine
  • Engine that instantiates the update of the data store used for navigation.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public protocol DataStoreMaintenanceEngine : ManageableEngine
  • The DefaultTomTomNavigation object defines the functionality of the navigation.

    Important

    DefaultTomTomNavigation isn’t thread-safe and it’s recommended to make API calls always on the same thread.
    See more

    Declaration

    Swift

    @available(*, deprecated, message: "This API is deprecated and will be removed with the next major release.")
    public class DefaultTomTomNavigation : TomTomNavigation
  • Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public protocol MainNavigationEngines
  • NavigationStartError contains information about any problems that occur during navigation. The detailed meaning of each error is provided via the message variable.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public enum NavigationStartError : Error
  • The TomTomNavigation protocol defines the functionality of the navigation.

    Important

    The current implementation of this API isn’t thread-safe and it’s recommended to make API calls always on the same thread.

    Important

    This is a Public Preview API. It may be changed or removed at any time.

    See more

    Declaration

    Swift

    public protocol TomTomNavigation : AnyObject
  • Represents the NavigationEvent published by TomTomNavigation\eventPublisher.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public enum NavigationEvent
  • Defines the error cases that can occur while generating guidance steps.

    See more

    Declaration

    Swift

    public enum GuidanceEngineError : Error
  • TomTomGuidanceEngine generates Guidance using the list of TomTomSDKRoute.Instructions supplied within NavigationSnapshot.activeRoute.

    TomTomGuidanceEngine depends on the TomTomSDKRoute.Announcements included in the supplied TomTomSDKRoute.Instructions. The engine continuously checks the active route progress to provide up-to-date Guidance information. When the vehicle reaches an announcement point, the generated Guidance includes the GuidanceAnnouncement to be announced. Note that the set of supported languages may differ between different GuidanceEngines.

    TomTomGuidanceEngine should only be used with the online routing client that uses TomTomSDKRoutePlanner.GuidanceOnlineAPIVersion.v1 as the TomTomSDKRoutePlanner.GuidanceOptions.guidanceVersion. This is because the instructions from offline and the online routing client configured with TomTomSDKRoutePlanner.GuidanceOnlineAPIVersion.v1 are designed to be used by the DynamicGuidanceEngine and do not contain static announcement information.

    See more

    Declaration

    Swift

    public class TomTomGuidanceEngine : GuidanceEngine
  • Creates a DynamicGuidanceEngine.

    DynamicGuidanceEngine generates dynamic Guidance for the TomTomSDKRoute.Instructions supplied within NavigationSnapshot.activeRoute.

    To generate dynamic Guidance, DynamicGuidanceEngine takes various parameters into account. These parameters include, but are not limited to:

    • Distance to the next maneuver.
    • Current speed of the vehicle.
    • Free-flow speed of the road between the current position and the next maneuver.
    • Traffic situation ahead.

    So, unlike TomTomGuidanceEngine, DynamicGuidanceEngine does not depend on TomTomSDKRoute.Announcement information that may or may not be included in the TomTomSDKRoute.Instruction. It continuously checks the active route progress to provide up-to-date Guidance information. Once the vehicle reaches an announcement point, the generated Guidance includes the (GuidanceAnnouncement) to be announced.

    Another difference between DynamicGuidanceEngine and TomTomGuidanceEngine is that DynamicGuidanceEngine uses TomTom’s advanced verbal instruction messages to synthesize GuidanceAnnouncements dynamically on the fly. Note that the set of supported languages may differ between different GuidanceEngines.

    DynamicGuidanceEngine can be used to provide turn-by-turn navigation with any routing client (offline, online with TomTomSDKRoutePlanner.GuidanceOptions.guidanceVersion v1 or v2).

    See more

    Declaration

    Swift

    public class TomTomDynamicGuidanceEngine : GuidanceEngine
  • The type of an individual trigger that appears on the route.

    The trigger may be differentiated by its distance to the maneuver point. Although, this type doesn’t provide any distance information, it describes a triggering point by its location on the route. For example:

    • follow trigger is in range 30...20 km from the maneuver point.
    • faraway trigger is in range 12...10 km from the maneuver point.
    • early trigger is in range 5...4 km from the maneuver point.
    • main trigger is in range 1.2...1 km from the maneuver point.
    • confirmation trigger is in range 50...20 meters from the maneuver point.

      Important

      This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public enum TriggerType : CaseIterable, Hashable
    extension TriggerType: Comparable
  • Configurations for triggering guidance.

    This outlines the configurations that can be used to trigger guidance for navigation instructions. Guidance instructions include both visual and audio components, which provide accurate and practical assistance to the user.

    As the user approaches the maneuver point, there are four distinct ‘Instruction Stages’ at which audio information is communicated:

    • Far away
    • Early instruction
    • Main instruction
    • Confirmation

    The default configurations for each of these TriggeringPoints is accessed using the GuidanceTriggeringConfig struct, which provides functions for retrieving configurations for each of the default attribute combinations. By using these configurations, developers can ensure that the distance to maneuver displayed in the navigation instruction panel corresponds to the spoken distance in the audio instruction, providing a more seamless and effective user experience.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public struct GuidanceTriggeringConfig
  • Holds collection of TriggeringConfigVariants.

    Use TriggeringConfig to initialize GuidanceTriggeringConfig with the configuration for guidance announcments. The configuration is an array of TriggeringConfigVariants; it defines all the parameters for all types of roads, regions, instructions types, and at what distances to be triggered. Additionally, the TriggeringConfig instance may validate an input list internally, allowing the developer to identify the problems during initialization.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public struct TriggeringConfig
  • Defines a variant for which a trigger should be generated. The most vital part of the instance is the triggeringPoints property where TriggerType is the key, and TriggeringPoint is the value associated with that key.

    For example, the following variant will be applicable for a trigger where the road is controlled access, for all countries, for comprehensive mode, only for roundabout instructions, and it has one triggering point (follow).

    TriggeringConfigVariant(
       roadTypes: [.controlledAccess],
       regions: [.restOfTheWorld],
       announcementModes: [.comprehensive],
       instructionTypes: [.roundabout],
       triggeringPoints: [
           .follow: TriggeringPoint(
               recommendedDistance: TriggeringDistances(
                   defaultDistance: Measurement.tt.kilometers(1000.0)
               ),
               messageDuration: 2
           )
       ]
    )
    

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public struct TriggeringConfigVariant : Hashable, Equatable
  • Holds one or more triggering distances.

    By default, the distance specified in defaultDistance is the triggering distance. In case custom triggering distances are to be used in the US and/or UK, corresponding values can be specified in customDistanceUS and customDistanceUK respectively.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public struct TriggeringDistances : Hashable, Equatable
  • The types of instruction that are defined for different configuration variants.

    The navigation system invokes guiding instructions for every maneuver to show the driver along the route. Driving instructions that get triggered have a type which is announced visually and audibly.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public enum TriggeringInstructionType : Hashable, CaseIterable
  • Defines a point on the route, where a trigger should be exposed.

    Triggering point is associated with TriggerType based on distance to the maneuver. For example, the following trigger must be triggered on the route at least 13 kilometers or at most 10 kilometers to the maneuver point.

     TriggeringPoint(
           recommendedDistance: TriggeringDistances(
               defaultDistance: Measurement.tt.kilometers(10.0)
           ),
           earliestDistance: TriggeringDistances(
               defaultDistance: Measurement.tt.kilometers(13.0)
           ),
           recommendedTime: 370,
           messageDuration: 0,
           isAudible: false
      )
    

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public struct TriggeringPoint : Hashable, Equatable
  • A region for which the triggering config variant is applicable.

    If you want to differentiate the triggers based on the country, you should specify the region while declaring config variants.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public enum TriggeringRegion : Hashable, CaseIterable
  • Defines types of unit system handling.

    See more

    Declaration

    Swift

    public struct UnitSystemType : Equatable
  • Provides access to current registered engines and allows updating them.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public protocol NavigationEngineRegistry : AnyObject
  • The NavigationEngines protocol defines all engines that can be used by the TomTomSDKNavigation module.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public protocol NavigationEngines : MainNavigationEngines, RouteNavigationEnginesProvider
  • Errors which may be thrown during navigation creation.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public enum NavigationFactoryError : LocalizedError
  • Informs the caller about announcements and instructions update events.

    The method TomTomSDKNavigationEngines.GuidanceEngine.generateGuidance(navigationSnapshot:) generates the guidance with instructions and distance. Based on the guidance result, the methods of the observers are called.

    The protocol provides the interface for handling several events like changes in instructions, generation of announcements, and changes in distance to the next instruction.

    To observe the guidance changes, first implement this interface to create an observer, for example:

    class CustomGuidanceUpdateObserver: GuidanceUpdateObserver {
    
        func didChangeInstructions(instructions: [GuidanceInstruction]) {
            // Add code here that handles the changes of instructions.
        }
    
        func didGenerateAnnouncement(announcement: GuidanceAnnouncement, shouldPlay: Bool) {
            // Add code here that handles a new generate announcement.
        }
    
        func didChangeDistanceToNextInstruction(
            distance: Measurement<UnitLength>,
            instructions: [GuidanceInstruction],
            currentPhase: InstructionPhase
        ) {
            // Add code here that handles a change of distance to new instruction.
        }
    }
    

    Then add the observer using addGuidanceUpdateObserver(_:). To stop observation of the guidance changes, remove the observer using removeGuidanceUpdateObserver(_:).

    See more

    Declaration

    Swift

    public protocol GuidanceUpdateObserver : Observer
  • Informs the caller about changes in lane guidance. This interface provides an observer for when lane guidance starts and ends.

    The LaneGuidanceUpdateObserver interface provides the methods that are called when lane guidance shall appear and disappear, respectively. These methods facilitate efficient and dynamic update of lane guidance information during a journey.

    To observe the lane guidance changes, first implement this interface to create an observer, for example:

    class CustomLaneGuidanceObserver: LaneGuidanceUpdateObserver {
        func didStartLaneGuidance(laneGuidance: LaneGuidance) {
            // Add code here that handles the lane guidance starting
        }
    
        func didEndLaneGuidance(laneGuidance: LaneGuidance) {
            // Add code here that handles the lane guidance ending
        }
    }
    

    Then add the observer using addLaneGuidanceUpdateObserver(_:). To stop observation of the lane guidance changes, remove the observer using removeLaneGuidanceUpdateObserver(_:).

    Note

    To ensure these methods are called, the Route passed to TomTomNavigation must contain valid LaneSections. This code is used within the context of a navigation system where lane guidance is crucial for the user experience and journey accuracy.
    See more

    Declaration

    Swift

    public protocol LaneGuidanceUpdateObserver : Observer
  • An observer that receives navigation map matching events. Check the MapMatchingEngine documentation for more information on map-matching.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public protocol LocationMapMatchingObserver : Observer
  • Informs the caller that the active route has changed. The active route is the only followed route for which the navigation provides guidance.

    The active route is changed when:

    • The navigation is started with a route using the start() method with NavigationOptions as an argument.
    • Navigation has completed a replanning and a new route is set as the active route.
    • The navigation is updated using the update(navigationOptions:) method. Note, if update(navigationOptions:) is called on the current active route, this observer will not receive an active route changed notification.
    • A better route proposal is accepted using the selectActiveRoute(routeId:) method.
    • A better route proposal is accepted by steering onto it.

    To receive notifications for active route changes, first implement an observer object that conforms to NavigationActiveRouteChangeObserver, for example:

    class RouteObserver: NavigationActiveRouteChangeObserver { ... }
    

    In order to complete conformance, the observer object must implement the following callback:

    func didChangeActiveRoute(route:) {
        // add code here that handles the active route being changed
    }
    

    This callback function could render the new active route in a different color on the map, for example.

    The NavigationActiveRouteChangeObserver is called after the addition of the route to the navigation and prior to the removal of the old active route. Hence, it is called after the NavigationRouteAddObserver and before the NavigationRouteRemoveObserver.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public protocol NavigationActiveRouteChangeObserver : Observer
  • An observer that receives navigation events of arrival at destination.

    Destination arrival is detected by the TomTomSDKNavigationEngines/ArrivalDetectionEngine. On arrival detection, navigation continues in turn-by-turn mode until it’s stopped or switched into free-driving mode.

    To be notified about the destination arrival event while navigating, first implement the NavigationDestinationArrivalObserver protocol:

    class NavigationDestinationArrivalObserverImpl: NavigationDestinationArrivalObserver {
        func didArriveAtDestination(route: TomTomSDKRoute.Route) {
            // Add code here that handles arrival at a destination.
        }
    }
    

    Then add this observer using addDestinationArrivalObserver(_:).

    To stop receiving the destination arrival event, remove the observer using removeDestinationArrivalObserver(_:).

    See more

    Declaration

    Swift

    public protocol NavigationDestinationArrivalObserver : Observer
  • An observer that receives navigation error events.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public protocol NavigationErrorObserver : Observer
  • An observer that receives navigation guidance events.

    See more

    Declaration

    Swift

    @available(*, deprecated, message: "This API is deprecated and will be removed with the next major release.\nPlease use TomTomSDKNavigation.GuidanceUpdateObserver and TomTomSDKNavigation.LaneGuidanceUpdateObserver instead.")
    public protocol NavigationGuidanceObserver : Observer
  • An observer that receives navigation progress events.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public protocol NavigationProgressObserver : Observer
  • Informs the caller that a route has been added to the navigation session.

    A new route can be added to the session under the following circumstances:

    • When navigation has started with a route using the start() method with NavigationOptions as an argument.
    • When navigation is updated using the update(navigationOptions:) method. Note, if the new route is identical, which means it has the same Route/id as the current active route, it will not trigger the observer.
    • When navigation finds a better route and the TomTomSDKNavigationEngines/BetterProposalAcceptanceMode is set to either TomTomSDKNavigationEngines/BetterProposalAcceptanceMode/manual or TomTomSDKNavigationEngines/BetterProposalAcceptanceMode/unreachableOnly.
    • When navigation finds a reachable route and TomTomSDKNavigationEngines/BetterProposalAcceptanceMode is set to TomTomSDKNavigationEngines/BetterProposalAcceptanceMode/manual.
    • When navigation finds a reachable route, due to the navigated route being unreachable, and TomTomSDKNavigationEngines/BetterProposalAcceptanceMode is set to TomTomSDKNavigationEngines/BetterProposalAcceptanceMode/unreachableOnly so that the reachable route is automatically applied.
    • When the TomTomSDKNavigationEngines/BetterProposalAcceptanceMode is set to TomTomSDKNavigationEngines/BetterProposalAcceptanceMode/automatic and the proposed route is automatically applied.
    • When navigation automatically replans and adds the newly planned route to the session.
    • When the preferredLanguage is set and the replanning with the new language has completed.

    To receive notifications of a route being added to the session, first implement an observer object that conforms to NavigationRouteAddObserver, for example:

    class RouteObserver: NavigationRouteAddObserver { ... }
    

    In order to complete conformance, the observer object must implement the following callback:

    func didAddRoute(route: options: reason:) {
        // add code here that handles the route being added to the session
    }
    

    This callback function could render the newly added route on the map, for example.

    Next, add this observer with navigation using addRouteAddObserver(_:). To stop notifications of a route being added to the session, remove the observer using removeRouteAddObserver(_:).

    Please note that NavigationRouteAddObserver is triggered only when the replanned route differs from the current active route in terms of geometry. Events like route refresh and increment update of guidance instructions will not trigger this observer. For these scenarios the NavigationRouteUpdateObserver is called.

    The complementary observer that notifies on the removal of routes from the session is NavigationRouteRemoveObserver.

    Important

    The addition of a route to the session does not necessarily make it active. To receive notifications of changes to the active route, use the NavigationActiveRouteChangeObserver.

    Important

    This is a Public Preview API. It may be changed or removed at any time.

    See more

    Declaration

    Swift

    public protocol NavigationRouteAddObserver : Observer
  • Defines the reasons why a route was added to the navigation session.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public struct RouteAddedReason : RawRepresentable, Hashable
  • Informs the caller that the active or proposed route has been removed from the navigation session.

    The active route is removed from the session when:

    The proposed route is removed from the session when:

    • The user is not following the route, as reported by NavigationRouteTrackingStateUpdateObserver resulting in the proposed route being placed in the TomTomSDKNavigationEngines/RouteTrackingState/unfollowedRoutes list.
    • The navigation has finished planning a new route due to replanning initiated by the navigation.
    • The navigation is updated using the update(navigationOptions:) method. Note, if the update(navigationOptions:) is called with the same route as the proposed one, this observer will not be triggered.

    To receive notifications of a route being removed from the session, first implement an observer object that conforms to NavigationRouteRemoveObserver, for example:

    class RouteObserver: NavigationRouteRemoveObserver { ... }
    

    /// In order to complete conformance, the observer object must implement the following callback:

    func didRemoveRoute(route: reason:) {
        // add code here that handles the route being removed from the session
    }
    

    This callback function could remove a rendered route from the map, for example.

    Next, add this observer with navigation using addRouteRemoveObserver(_:). To stop notifications of a route being removed from the session, remove the observer using removeRouteRemoveObserver(_:).

    The complementary observer that provides updates on the addition of routes to the session is NavigationRouteAddObserver. Note, during navigation in turn by turn mode there will always be one active route. Therefore, any removal of the current active route will always be preceded by an NavigationActiveRouteChangeObserver call, with details of the new active route.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public protocol NavigationRouteRemoveObserver : Observer
  • Defines the reasons why a route was removed from the navigation session.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public struct RouteRemovedReason : RawRepresentable, Hashable
  • An observer that receives route tracking state updates.

    The information about the route state is represented by TomTomSDKNavigationEngines/RouteTrackingState. When the driver deviates or returns to the active route, the navigation engine sends route-tracking state updates to the observer.

    To be notified about the route state update while navigating, first implement the NavigationRouteTrackingStateUpdateObserver protocol:

    class NavigationRouteTrackingStateUpdateObserverImpl: NavigationRouteTrackingStateUpdateObserver {
        func didUpdateRouteTrackingState(routeTrackingState: RouteTrackingState) {
            // Add code here that handles the route state update.
        }
    }
    

    To start receiving route tracking state updates, become an observer using TomTomSDKNavigation/TomTomNavigation/addRouteTrackingStateUpdateObserver(_:): To stop receiving route tracking state updates, remove the previously added observer using TomTomSDKNavigation/TomTomNavigation/removeRouteTrackingStateUpdateObserver(_:):

    See more

    Declaration

    Swift

    public protocol NavigationRouteTrackingStateUpdateObserver : Observer
  • Informs the caller that the current route has been updated.

    The current route is updated under the following circumstances:

    • When the route data is refreshed with data from the replanned route.
    • When instructions and lane guidance are incrementally updated for the current route.

    To receive notifications of a route being updated, first implement an observer object that conforms to NavigationRouteUpdateObserver, for example:

    class RouteObserver: NavigationRouteUpdateObserver { ... }
    

    In order to complete conformance, the observer object must implement the following callback:

    func didUpdateRoute(route: reason:) {
        // add code here that handles the route being updated
    }
    

    Next, add this observer with navigation using TomTomNavigation/addRouteUpdateObserver(_:)`. To stop notifications of a route being updated, remove the observer usingTomTomNavigation/removeRouteUpdateObserver(_:)“.

    Please note that the NavigationRouteUpdateObserver is triggered only when the route is updated. It means that the route geometry is preserved. When a route update happens the active route does not change, therefore the NavigationActiveRouteChangeObserver is not called. To receive notifications of route changes that result in the geometry change, refer to the NavigationRouteAddObserver, NavigationRouteRemoveObserver and the NavigationActiveRouteChangeObserver.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public protocol NavigationRouteUpdateObserver : Observer
  • Defines the reasons why a route was updated during the navigation session.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public struct RouteUpdatedReason : RawRepresentable, Hashable
  • An observer that can receive navigationState change events.

    The navigation state changes when the navigation session is started, resumed, stopped, or updated from from free driving to active guidance.

    For more information on navigation states, see the NavigationState and navigationState documentation.

    To be informed of navigation state updates implement NavigationStateChangeObserver:

    class StateChangeObserver: NavigationStateChangeObserver {
        func didChangeNavigationState(navigationState: NavigationState) {
            // add code that handles navigation state changes
        }
    }
    

    Then add the observer using addNavigationStateChangeObserver(_:).

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public protocol NavigationStateChangeObserver : Observer
  • An observer that receives navigation events related with visiting waypoints.

    The waypoint arrival state changes are detected by the TomTomSDKNavigationEngines/ArrivalDetectionEngine. Different observer methods are called depending on what state has been detected by the TomTomSDKNavigationEngines/ArrivalDetectionEngine:

    To be notified about the waypoint arrival events while navigating, first implement the NavigationWaypointArrivalObserver protocol:

    class NavigationWaypointArrivalObserverImpl: NavigationWaypointArrivalObserver {
        func didArriveAtWaypoint(waypoint: RouteStop, on route: Route) {
            // Add code here that handles an arrival at a waypoint.
        }
    
        func didDepartFromWaypoint(waypoint: RouteStop, on route: Route) {
            // Add code here that handles a departure from a waypoint.
        }
    }
    

    Then add this observer using addWaypointArrivalObserver(_:).

    To stop receiving these events, remove the observer using removeWaypointArrivalObserver(_:).

    See more

    Declaration

    Swift

    public protocol NavigationWaypointArrivalObserver : Observer
  • SegmentsFilterError defines the errors that can occur while fetching the route progress.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public enum ProgressInterpolatorError : Error
  • Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public protocol SimpleEngineCommonCalculator
  • Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public struct SimpleEngineCalcResult