Starting navigation

The Navigation SDK for iOS is only available upon request. Contact Sales to get started.

This guide explains how to start turn-by-turn navigation and retrieve route progress information, such as the remaining travel time and traveled distance. For this example, we utilize an online route.

Project setup

Configure the project according to the project setup guide and import the necessary frameworks using the following instructions, based on your preferred package manager:

Swift Package Manager

Open your App’s target and navigate to General > Frameworks, Libraries, and Embedded Content.
Add the following TomTomSDK libraries from the provided code snippet. Once the project is set up, import the mentioned frameworks into your code.

1
import CoreLocation
2
import TomTomSDKCommon
3
import TomTomSDKLocationProvider
4
import TomTomSDKNavigation
5
import TomTomSDKNavigationEngines
6
import TomTomSDKNavigationOnline
7
import TomTomSDKNavigationTileStore
8
import TomTomSDKRoute
9
import TomTomSDKRoutePlanner
10
import TomTomSDKRoutePlannerOnline
11
import TomTomSDKRoutingCommon

CocoaPods

Open your project’s Podfile and add the required modules to your application’s target:

1
TOMTOM_SDK_VERSION = '0.71.1'
2

3
target 'YourAppTarget' do
4
  use_frameworks!
5
  pod 'TomTomSDKCommon', TOMTOM_SDK_VERSION
6
  pod 'TomTomSDKLocationProvider', TOMTOM_SDK_VERSION
7
  pod 'TomTomSDKNavigation', TOMTOM_SDK_VERSION
8
  pod 'TomTomSDKNavigationEngines', TOMTOM_SDK_VERSION
9
  pod 'TomTomSDKRoute', TOMTOM_SDK_VERSION
10
  pod 'TomTomSDKRoutePlanner', TOMTOM_SDK_VERSION
11
  pod 'TomTomSDKRoutePlannerOnline', TOMTOM_SDK_VERSION
12
  pod 'TomTomSDKRouteReplannerDefault', TOMTOM_SDK_VERSION
13
end

Install the dependencies by executing the following commands in the project directory:
```
1
pod repo update tomtom-sdk-cocoapods
2
pod install --repo-update
```

Once the project is set up and the navigation module is added to your target, import the following frameworks:

1
import CoreLocation
2
import TomTomSDKCommon
3
import TomTomSDKLocationProvider
4
import TomTomSDKNavigation
5
import TomTomSDKNavigationEngines
6
import TomTomSDKNavigationOnline
7
import TomTomSDKNavigationTileStore
8
import TomTomSDKRoute
9
import TomTomSDKRoutePlanner
10
import TomTomSDKRoutePlannerOnline
11
import TomTomSDKRoutingCommon

Start by initializing a RoutePlanner and a TomTomNavigation object to build an example of navigating a route.

An OnlineRoutePlanner .
A TomTomNavigation object.

To make it easier to follow this guide, make sure to place all the following code snippets in the above-mentioned class.

1
class NavigationExample {
2
    private let routePlanner = OnlineRoutePlanner(apiKey: "YOUR_TOMTOM_API_KEY")
3
    private var navigation: TomTomNavigation!
4
}

Before starting navigation with a route, you need to plan the route and set up a location provider to receive location updates along the route.

First, plan a Route between two locations. Refer to the Planning a route guide if you want to learn more about how to plan a Route .

1
typealias PlanRouteResult = Result<(Route?, RoutePlanningOptions), Error>
2
private func planRoute(completionHandler: @escaping (PlanRouteResult) -> ()) {
3
    do {
4
        // Create itinerary.
5
        let amsterdam = ItineraryPoint(
6
            coordinate: CLLocationCoordinate2D(
7
                latitude: 52.37616,
8
                longitude: 4.90828
9
            )
10
        )
11
        let rotterdam = ItineraryPoint(
12
            coordinate: CLLocationCoordinate2D(
13
                latitude: 51.90546,
14
                longitude: 4.46662
15
            )
16
        )
17
        let itinerary = Itinerary(origin: amsterdam, destination: rotterdam)
18

19
        // Create RoutePlanningOptions based on itinerary.
20
        let routePlanningOptions = try RoutePlanningOptions(
21
            itinerary: itinerary,
22
            guidanceOptions: GuidanceOptions()
23
        )
24

25
        // Request a route based on the previously created options.
26
        routePlanner.planRoute(
27
            options: routePlanningOptions,
28
            onRouteReady: nil,
29
            completion: { result in
30
                switch result {
31
                case let .success(routePlanningResponse):
32
                    let result = (
33
                        routePlanningResponse.routes?.first,
34
                        routePlanningOptions
35
                    )
36
                    completionHandler(.success(result))
37
                case let .failure(error):
38
                    print(error.localizedDescription)
39
                    completionHandler(.failure(error))
40
                }
41
            }
42
        )
43
    } catch {
44
        completionHandler(.failure(error))
45
    }
46
}

Once you have retrieved the route, create and enable the LocationProvider . Refer to the Built-in location providers and the Location module guides for more information.

1
let simulatedLocationProvider = SimulatedLocationProvider(
2
    delay: Measurement<UnitDuration>(value: 0.5, unit: .seconds),
3
    adjustToCurrentTime: true
4
)
5
simulatedLocationProvider.updateCoordinates(
6
    route.geometry,
7
    interpolate: true
8
)
9
simulatedLocationProvider.enable()

Now you can set up the navigation with the OnlineTomTomNavigationFactory.Configuration using:

Your TomTom API key
The previously created location provider
A RoutePlanner to be used to update the active route plan or to replan after deviation.

1
let tileStore: NavigationTileStore
2
do {
3
    tileStore = try NavigationTileStore(
4
        config: NavigationTileStoreConfiguration(apiKey: "YOUR_TOMTOM_API_KEY")
5
    )
6
} catch {
7
    print("Cannot create Tile Store: \(error)")
8
    return
9
}
10

11
let navigationConfiguration = OnlineTomTomNavigationFactory
12
    .Configuration(
13
        navigationTileStore: tileStore,
14
        locationProvider: simulatedLocationProvider,
15
        routePlanner: routePlanner
16
    )

Next, create the TomTomNavigation object with the previous configuration.

1
self.navigation = try! OnlineTomTomNavigationFactory
2
    .create(configuration: navigationConfiguration)

Start receiving route progress updates during navigation by implementing the NavigationProgressObserver protocol and adding it to the initialized TomTomNavigation object.

1
extension NavigationExample: NavigationProgressObserver {
2
    func didUpdateProgress(progress: TomTomSDKNavigationEngines.RouteProgress) {
3
        /* Your code goes here */
4
    }
5
}

1
self.navigation.addProgressObserver(self)

To start navigation along a route, pass the NavigationOptions object which sets the active route to the above-created route.

1
let routePlan = RoutePlan(
2
    route: route,
3
    routePlanningOptions: routePlanningOptions
4
)
5
let navigationOptions = NavigationOptions(activeRoutePlan: routePlan)
6

7
do {
8
    try self.navigation.start(navigationOptions: navigationOptions)
9
} catch {
10
    print("start navigation error: \(error)")
11
}

Combine all the previous snippets into the following format:

1
func prepareAndStartNavigation() throws {
2
    planRoute { [weak self] result in
3
        switch result {
4
        case let .success(planRouteResult):
5
            guard let self,
6
                  let route: Route = planRouteResult.0
7
            else { return }
8
            let routePlanningOptions: RoutePlanningOptions = planRouteResult.1
9

10
            // Initialize the simulated location provider and enable it.
11
            let simulatedLocationProvider = SimulatedLocationProvider(
12
                delay: Measurement<UnitDuration>(value: 0.5, unit: .seconds),
13
                adjustToCurrentTime: true
14
            )
15
            simulatedLocationProvider.updateCoordinates(
16
                route.geometry,
17
                interpolate: true
18
            )
19
            simulatedLocationProvider.enable()
20

21
            // Configure navigation.
22
            let tileStore: NavigationTileStore
23
            do {
24
                tileStore = try NavigationTileStore(
25
                    config: NavigationTileStoreConfiguration(apiKey: "YOUR_TOMTOM_API_KEY")
26
                )
27
            } catch {
28
                print("Cannot create Tile Store: \(error)")
29
                return
30
            }
31

32
            let navigationConfiguration = OnlineTomTomNavigationFactory
33
                .Configuration(
34
                    navigationTileStore: tileStore,
35
                    locationProvider: simulatedLocationProvider,
36
                    routePlanner: routePlanner
37
                )
38

39
            // Create an instance of navigation
40
            // based on the previous configuration.
41
            self.navigation = try! OnlineTomTomNavigationFactory
42
                .create(configuration: navigationConfiguration)
43

44
            // Add a progress observer to the navigation instance.
45
            self.navigation.addProgressObserver(self)
46

47
            // Start navigation on the planned route.
48
            let routePlan = RoutePlan(
49
                route: route,
50
                routePlanningOptions: routePlanningOptions
51
            )
52
            let navigationOptions = NavigationOptions(activeRoutePlan: routePlan)
53

54
            do {
55
                try self.navigation.start(navigationOptions: navigationOptions)
56
            } catch {
57
                print("start navigation error: \(error)")
58
            }
59
        case let .failure(error):
60
            print("route planning error: \(error.localizedDescription)")
61
        }
62
    }
63
}

Once you have started the navigation session, TomTomNavigation will:

Track locations using the LocationProvider .
Process the incoming locations and publish navigation events with data, such as map-matched locations or route guidance. To retrieve this data, you must add the appropriate observers to TomTomNavigation .

Retrieving route progress information

Once navigation has started you can observe route progress updates through the NavigationProgressObserver.didUpdateProgress(progress:) callback and retrieve the travelled distance and the remaining travel time. The following snippet prints information to validate the route progress updates.

1
func didUpdateProgress(progress: TomTomSDKNavigationEngines.RouteProgress) {
2
    print("Distance along the route: \(progress.distanceAlongRoute)")
3
    print("Remaining travel time: \(progress.remainingTime)")
4
}

In addition to route progress updates, you can also listen to and handle events for route updates, deviations, route and lane guidance, waypoint arrival and reaching a destination. Refer to the Turn-by-turn navigation guide to find out more about supported navigation events.

Next steps

Now that you know how to start navigation with a route and have learnt about navigation events, here are the recommendations on what to explore next: