Turn-by-turn navigation

VERSION 0.13.0
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 RoutePlanningOptions 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.

let navigationOptions = NavigationOptions(activeRoutePlan: routePlan)
navigation.start(navigationOptions: navigationOptions)

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.

let navigationOptions = NavigationOptions(activeRoutePlan: routePlan)
navigation.update(navigationOptions: navigationOptions)

Navigation RoutePlan updates can be observed. A replanning notification is sent via NavigationRouteObserver::func 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 didReplanRoute(replannedRoute: 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 NavigationProgressObserver::func didUpdateProgress(progress: RouteProgress). It provides the current RouteProgress, which contains, among other things, the arrival time and the remaining distance along the route.

1func didUpdateProgress(progress: RouteProgress) {
2    let currentPosition: CLLocation = progress.currentGeoLocation.location
3    let arrivalTime: Measurement<UnitDuration> = progress.arrivalTime
4    let distanceAlongRoute: Measurement<UnitLength> = progress.distanceAlongRoute
5    let additionalInformation: String? = progress.extras
6}

Route deviations

The Navigation module detects when the user is not tracking a route and has diverged from the navigated route. Whenever a deviation is detected, the notification is sent via NavigationRouteObserver::func didDeviateFromRoute(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 from which the user deviated.

1func didDeviateFromRoute(currentRoute: Route, location: GeoLocation) {
2    /* YOUR CODE GOES HERE */
3}

The new route is planned using the RoutePlanningOptions 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 three methods:

1func didUpdateInstructions(instructions: [GuidanceInstruction]) {
2    /* YOUR CODE GOES HERE */
3}
4

5func didUpdateDistanceToNextInstruction(
6    distance: Measurement<UnitLength>,
7    instructions: [GuidanceInstruction],
8    currentPhase: InstructionPhase
9) {
10    /* YOUR CODE GOES HERE */
11}
12

13func didGenerateAnnouncement(announcement: GuidanceAnnouncement, shouldPlay: Bool) {
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 didStartLaneGuidance(laneGuidance: LaneGuidance) {
2    /* YOUR CODE GOES HERE */
3}
4

5func didEndLaneGuidance(laneGuidance: 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 NavigationArrivalObserver::func didArriveAtDestinationOn(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 didArriveAtDestinationOn(route: Route) {
2    /* YOUR CODE GOES HERE */
3}

Waypoint arrival

The Route being followed can contain route stops the driver wants to visit before arriving at the destination. These stops, called waypoints, are included in routeStops as instances of the type that conforms to the protocol RouteStop. You can find more details on waypoints in the Waypoints and custom routes guide.

The Navigation module uses the generated RouteProgress to detect that the user has arrived at a waypoint. Once waypoint arrival is detected it triggers NavigationArrivalObserver. This means that the ArrivalDetectionEngine has successfully detected an arrival at the waypoint.