Developer

Starting navigation

VERSION 0.28.2
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

  1. Configure the project as described in the project setup guide.
  2. Open your project’s Podfile and add the required modules to your application’s target: 
    1TOMTOM_SDK_VERSION = '0.28.2'
    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
  3. Install the dependencies by executing the following commands in the project directory: 
    pod repo-art update tomtom-sdk-cocoapods
    pod install --repo-update
  4. 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

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(progressPoints: .all)
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 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    routingOptions: routePlanningOptions
4)
5let navigationOptions = NavigationOptions(activeRoutePlan: routePlan)
6self.navigation.start(navigationOptions: navigationOptions)

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                routingOptions: routePlanningOptions
45            )
46            let navigationOptions = NavigationOptions(activeRoutePlan: routePlan)
47            self.navigation.start(navigationOptions: navigationOptions)
48        case let .failure(error):
49            print("route planning error: \(error.localizedDescription)")
50        }
51    }
52}

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 didUpdateProgress callback of the NavigationProgressObserver implementation 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.arrivalTime)")
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: