Turn-by-turn navigation

VERSION 0.2.1455
PUBLIC PREVIEW

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

Turn-by-turn navigation is navigation along a provided route. It provides information about the next maneuvers and the progress along the current route. First, add the navigation module to your project and set up a Navigation object. Read how to do this in the Quickstart guide.

Starting navigation

Once the Navigation object is initialized, you can start navigation. Turn-by-turn navigation requires a RoutePlan for navigation to follow. RoutePlan consists of a Route and a RoutingOptions object. More details on how to plan a Route can be found in the Planning a route guide.

routePlan = RoutePlan(route: route, routingOptions: options)

Now the prepared RoutePlan can be used to start navigation. To do this, call the start(routePlan: RoutePlan) method on your Navigation object.

navigation.start(routePlan: routePlan)

Navigation also supports manually stopping navigation. The Navigation.stop() method stops the current navigation session and clears all data related to it.

navigation.stop()

If navigation has not been started, the stop method will have no effect.

Updating the route

Once Navigation is started, you can change the RoutePlan being followed at any time.

navigation.update(routePlan: routePlan)

Navigation RoutePlan updates can be observed. A replanning notification is sent via TomTomNavigationDelegate::func tomTomNavigation(_ navigation: Navigation, didReplanRoute replannedRoute: Route, reason: RouteReplanningReason). The provided replannedRoute represents the new Route that navigation will follow. The reason parameter indicates why the route was updated. More details about route replanning can be found in the Continuous replanning and route deviation guide.

1func tomTomNavigation(_: Navigation, didReplanRoute _: Route, reason _: RouteReplanningReason) {
2 /* YOUR CODE GOES HERE */
3}

Route progress

The position-dependent data fields are contained in the RouteProgress. Some examples are position on route (offset from the beginning) and remaining travel time. These fields are updated on every position update roughly once per second. You can listen for changes to route progress. A progress notification is sent via TomTomNavigationDelegate::func tomTomNavigation(_ navigation: Navigation, didUpdateProgress: RouteProgress). It provides the current RouteProgress, which contains, among other things, the arrival time and the remaining distance along the route.

1func tomTomNavigation(_: Navigation, didUpdateProgress routeProgress: RouteProgress) {
2 let currentPosition: CLLocation = routeProgress.currentPosition.location
3 let arrivalTimeInSeconds: TimeInterval = routeProgress.arrivalTimeInSeconds
4 let distanceAlongRouteInMeters: Double = routeProgress.distanceAlongRouteInMeters
5 let additionalInformation: String? = routeProgress.extras
6}

Route deviations

The Navigation module detects when the user has diverged from the navigated route. Whenever a deviation is detected, the notification is sent via TomTomNavigationDelegate::func tomTomNavigation(_ navigation: Navigation, didDeviateRoute currentRoute: Route, location: GeoLocation). The location provided by the callback is the localization where the deviation from the route was detected. The currentRoute parameter is the Route that the user deviated from.

1func tomTomNavigation(_: Navigation, didDeviateRoute _: Route, location _: GeoLocation) {
2 /* YOUR CODE GOES HERE */
3}

The new route is planned using the RoutingOptions that were set for the RoutePlan used to start or update navigation. More details about automatic replanning can be found in the replanning on deviation section.

You can disable automatic replanning on deviation and provide a new RoutePlan manually using the Navigation.update(routePlan: RoutePlan) method. Details are described in the Continuous replanning and route deviation guide.

Route guidance

While navigating, Navigation generates a guidance update after each location change. Generated guidance consists of the next instructions, the distance to a maneuver, and an announcement if the distance is in a suitable range. The generated guidance notifications are sent via 3 methods:

1func tomTomNavigation(_: Navigation, didUpdateInstructions _: [GuidanceInstruction]) {
2 /* YOUR CODE GOES HERE */
3}
4
5func tomTomNavigation(_: Navigation, didGenerateAnnouncement _: GuidanceAnnouncement) {
6 /* YOUR CODE GOES HERE */
7}
8
9func tomTomNavigation(
10 _: Navigation,
11 didUpdateDistanceToNextInstruction _: Measurement<UnitLength>,
12 instructions _: [GuidanceInstruction]
13) {
14 /* YOUR CODE GOES HERE */
15}

Lane level guidance

The Navigation has built-in support to generate lane guidance. Lane guidance is generated for each LaneSection object in a Route. More details on how to request a route with a LaneSection are described in the Route sections guide.

The LaneGuidance object consists of:

  • lanes - An object that consists of a list with directions and an optional lane direction the driver should follow.
  • laneSeparators - A list of lane separators.
  • routeOffsetInMeters - The distance from the start of the route to the start of the lanes.
  • lengthInMeters - Length of the lane section.

The generated lane level guidance notifications are sent via 2 methods:

1func tomTomNavigation(_: Navigation, didStartLaneGuidance _: LaneGuidance) {
2 /* YOUR CODE GOES HERE */
3}
4
5func tomTomNavigation(_: Navigation, didEndLaneGuidance _: LaneGuidance) {
6 /* YOUR CODE GOES HERE */
7}

Arrival experience

The Navigation module detects that the user has arrived at the destination. Whenever an arrival is detected, the notification is sent via TomTomNavigationDelegate::func tomTomNavigation(_ navigation: Navigation, didArriveAtDestinationOnRoute route: Route). At that point the navigation might be stopped or the event might be handled in other way like f.e. only displaying some notification for the user but keep navigating.

1func tomTomNavigation(_: Navigation, didArriveAtDestinationOnRoute _: Route) {
2 /* YOUR CODE GOES HERE */
3}