Developer

Starting navigation

VERSION 0.45.0
PUBLIC PREVIEW

The Navigation SDK for iOS is only available upon request. Contact us 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
  1. Open your App’s target and navigate to General > Frameworks, Libraries, and Embedded Content.
  2. Add the following TomTomSDK libraries from the provided code snippet. Once the project is set up, import the mentioned frameworks into your code.
1import CoreLocation
2import TomTomSDKCommon
3import TomTomSDKLocationProvider
4import TomTomSDKNavigation
5import TomTomSDKNavigationEngines
6import TomTomSDKNavigationOnline
7import TomTomSDKRoute
8import TomTomSDKRoutePlanner
9import TomTomSDKRoutePlannerOnline
10import TomTomSDKRouteReplannerDefault
11import TomTomSDKRoutingCommon
CocoaPods
  1. Open your project’s Podfile and add the required modules to your application’s target: 
    1TOMTOM_SDK_VERSION = '0.45.0'
    2

    3target '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
    13end
  2. Install the dependencies by executing the following commands in the project directory: 
    pod repo-art update tomtom-sdk-cocoapods
    pod install --repo-update
  3. Once the project is set up and the navigation module is added to your target, import the following frameworks: 
    1import CoreLocation
    2import TomTomSDKCommon
    3import TomTomSDKLocationProvider
    4import TomTomSDKNavigation
    5import TomTomSDKNavigationEngines
    6import TomTomSDKNavigationOnline
    7import TomTomSDKRoute
    8import TomTomSDKRoutePlanner
    9import TomTomSDKRoutePlannerOnline
    10import TomTomSDKRouteReplannerDefault
    11import TomTomSDKRoutingCommon

Starting navigation

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

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

1class NavigationExample {
2    private let routePlanner = OnlineRoutePlanner(apiKey: "YOUR_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 using RoutePlanningOptions. Refer to the Planning a route guide if you want to learn more about how to plan a Route.

1typealias PlanRouteResult = Result<(Route?, RoutePlanningOptions), Error>
2private 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.

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

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

  • Your TomTom API key
  • The previously created location provider
  • A RouteReplanner to be used for routing requests during replanning
1let routeReplanner = RouteReplannerFactory
2    .create(
3        routePlanner: self.routePlanner
4    )
5let navigationConfiguration = OnlineTomTomNavigationFactory
6    .Configuration(
7        locationProvider: simulatedLocationProvider,
8        routeReplanner: routeReplanner,
9        apiKey: "YOUR_API_KEY"
10    )

Next, create the TomTomNavigation object with the previous configuration.

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

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

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

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

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

7do {
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:

1func 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 start 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.start()
20

21            // Initialize the route replanner and configure navigation.
22            let routeReplanner = RouteReplannerFactory
23                .create(
24                    routePlanner: self.routePlanner
25                )
26            let navigationConfiguration = OnlineTomTomNavigationFactory
27                .Configuration(
28                    locationProvider: simulatedLocationProvider,
29                    routeReplanner: routeReplanner,
30                    apiKey: "YOUR_API_KEY"
31                )
32

33            // Create an instance of navigation
34            // based on the previous configuration.
35            self.navigation = try! OnlineTomTomNavigationFactory
36                .create(configuration: navigationConfiguration)
37

38            // Add a progress observer to the navigation instance.
39            self.navigation.addProgressObserver(self)
40

41            // Start navigation on the planned route.
42            let routePlan = RoutePlan(
43                route: route,
44                routePlanningOptions: routePlanningOptions
45            )
46            let navigationOptions = NavigationOptions(activeRoutePlan: routePlan)
47

48            do {
49                try self.navigation.start(navigationOptions: navigationOptions)
50            } catch {
51                print("start navigation error: \(error)")
52            }
53        case let .failure(error):
54            print("route planning error: \(error.localizedDescription)")
55        }
56    }
57}

Once you have started the navigation session, TomTomNavigation will:

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.

1func 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: