Navigation concepts explained

Navigation is the process of turning a user's changing position into useful information about the road ahead. With the HERE SDK, an application can guide a user along a calculated route or track a map-matched position without a route. The SDK supplies navigation data and events; the application decides how to turn those events into a safe, understandable experience.

This topic explains the architecture before you follow the navigation app tutorial or the more detailed navigation guide.

Turn-by-turn guidance and tracking

Turn-by-turn guidance, often abbreviated as TBT or simply guidance, compares the user's position with a Route. It produces route progress, upcoming maneuvers, deviation information, and other road-related events so that the application can help the user reach a destination.

Tracking mode follows the user's map-matched position without a route. It can provide information about the current road and available warnings, but it does not produce route progress or maneuver events that depend on a route. Tracking is useful when an application wants to show the user's position and road context without giving directions to a destination.

Both modes depend on a steady stream of location updates. The difference is whether a Route is set on the navigation component.

The building blocks

The following components form the navigation pipeline:

Position updates and positioning: A positioning solution determines where the device is and reports new locations over time. The Positioning guide explains permissions, accuracy, and device location sources.
LocationEngine: The HERE SDK source for device locations. It can use available positioning technologies and notify the application as new locations arrive. An application can also use another location provider, as long as it supplies compatible Location updates.
Location: A time-stamped observation of the device. Its coordinates describe the position; bearingInDegrees describes the horizontal direction of travel; speedInMetersPerSecond describes the current speed; and time records when the location was determined. Accuracy values and the source can provide additional context. Frequent, current, and complete values improve map matching and navigation events.
Route: A path through the road network, normally obtained from the RoutingEngine. It contains the geometry and sections that define the trip, along with information such as length and estimated duration. A route is required for guidance, but not for tracking.
Navigator: A headless navigation component. It consumes location updates, map-matches them, and publishes navigation events without rendering a navigation map view. Use it when the application owns the map and navigation presentation.
VisualNavigator: The navigation component with visual navigation support. It provides the navigation logic of Navigator and can control a MapView to render the route, location indicator, and other navigation visuals. It also supports visual interpolation between location updates.
LocationSimulator: A development and test location source. It can generate a sequence of locations from a Route or GPX track at a configured interval, allowing an application to replay a trip without driving.

The navigation components are decoupled from positioning: a LocationEngine, a simulator, or another provider can supply the updates. The Navigator or VisualNavigator then processes those updates and emits events for the application.

The guidance flow

A guidance experience usually follows this sequence:

Obtain a Route, either by calculating one with the RoutingEngine or by receiving one from another source. See Get started with Routing.
Start a real location source such as the LocationEngine, or use a LocationSimulator during development.
Create a Navigator or VisualNavigator.
Connect the location source to the navigation component and register the event listeners that the application needs.
Set the Route on the navigation component. The component can now compare incoming locations with the route and produce guidance events.
Present the resulting progress, maneuver, lane, road sign, voice, and warning information in the application.

Guidance is driven by incoming locations, not by the route alone. The navigation component map-matches each suitable update and uses it to determine progress and the next road events. A realistic update frequency matters: the Navigator API reference recommends at least one update per second, and inaccurate or stale updates can delay or distort events.

The tracking flow

Tracking uses the same location pipeline but does not set a route:

Create a Navigator or VisualNavigator.
Start the LocationEngine, LocationSimulator, or another location source.
Connect location updates and the listeners that are useful without a route.
Consume the map-matched location and road-related information to update the application experience.

Tracking does not become guidance merely because locations are being delivered. The application enters guidance by setting a Route. It can return to tracking by removing the route while keeping the location source and appropriate route-independent listeners active. See Start and stop tracking for the platform details.

From navigation events to an application experience

The HERE SDK provides events and data; it does not prescribe the application's user interface or notification policy.

Maneuvers and event text: Maneuver events describe what is coming on the route. Event text provides localized text intended for presentation or speech. The voice guidance guide explains how event text can be used with a text-to-speech engine.
Voice guidance: The HERE SDK provides maneuver notification text, while the application integrates a text-to-speech solution and decides when spoken output should interrupt or defer other audio.
Route progress and arrival: Route progress communicates the user's progress through the route, including the next maneuver and remaining distance or duration. An arrival event lets the application finish or transition the guidance experience.
Route deviation and rerouting: A deviation event tells the application that the user is no longer following the route. The HERE SDK does not choose the application's rerouting policy. The application can wait for confirmation, calculate a new route, return to the existing route, or continue with an appropriate explanation. See Handle route deviations.
Lane guidance and road signs: Lane assistance helps the application show which lanes support the next maneuver. Road sign information can provide additional context. These events are useful only when the application presents them clearly and at the right time. See Get lane assistance.
Warnings and alerts: The navigation components can provide speed-limit and speed-status information, truck restrictions, safety cameras where available, road signs, traffic-related events, and other warning systems. The warner guide describes the available categories and their limitations. Some warning systems are also available in tracking mode.

An application must decide which events and warnings to show, how to prioritize simultaneous notifications, and how to present them without distracting the user. A warning from the SDK is information for the application to evaluate; it is not a substitute for observing the road, obeying local laws, or making safe driving decisions.

Which entry point should I use?

Choose Navigator when the application needs navigation logic and wants to render or compose the entire experience itself. It is headless, so it can fit an existing map and UI architecture.

Choose VisualNavigator when the application wants the same navigation logic together with ready-made visual navigation behavior, such as route rendering, a location indicator, camera behavior, and visual interpolation. The application still owns the surrounding UI and is responsible for deciding which event information to expose.

Both entry points use the same route and location concepts and support guidance and tracking. The choice is primarily about who owns the visual navigation presentation.

A conceptual lifecycle

Use this lifecycle as a planning checklist:

Initialize the HERE SDK and complete the required application setup.
Obtain or calculate a route, unless the application starts in tracking mode. Review Get started with Routing.
Start a location source: use the device through LocationEngine, or use LocationSimulator for repeatable playback.
Create the entry point: choose Navigator for headless logic or VisualNavigator for logic plus a visual navigation experience.
Connect locations and listeners for map-matched locations, route progress, maneuvers, arrival, deviations, lanes, road signs, voice text, and the warning systems relevant to the application.
Start guidance or tracking by supplying locations and, for guidance, setting the Route.
Handle lifecycle events such as pausing a screen, changing routes, reaching the destination, switching between guidance and tracking, or losing a location source.
Stop and clean up: stop navigation-related listeners and the LocationSimulator when they are no longer needed; stop rendering for a VisualNavigator before its MapView is destroyed; and release application-owned resources.

The exact lifecycle details vary by platform and application architecture. The navigation app tutorial shows one complete implementation path.

Development and testing

Navigation depends on movement through space and time. Test location updates should be frequent enough to exercise map matching, maneuvers, deviations, and arrival. They should also contain realistic coordinates, timestamps, bearing, and speed where available. A route with only a few widely spaced or stale updates can hide timing and presentation problems.

LocationSimulator can replay a Route or GPX track without driving. This is useful for repeatable tests of route progress, maneuver timing, arrival, route deviation handling, voice text, lane guidance, and warning prioritization. It also makes it easier to reproduce a particular point in a trip while developing the UI.

Simulation is not a complete substitute for field testing. Use real devices and real-world conditions to verify GNSS behavior, permissions, background and screen lifecycle behavior, tunnels and signal loss, map data availability, audio focus, device performance, battery use, traffic conditions, and the clarity of the final experience. Test the application in every transport scenario it supports.

Navigation applications have safety responsibilities. Users must keep their attention on the road, follow local laws, and never treat SDK instructions or alerts as permission to make an unsafe maneuver. The application design must leave the final driving decision with the user and should avoid presenting information in a way that encourages unsafe device interaction.

How the pieces fit together

LocationEngine or LocationSimulator
              |
              v
          Location updates
              |
              v
   Navigator or VisualNavigator <---- Route (guidance only)
              |
              v
 Map matching, progress, maneuvers,
 deviations, lanes, signs, voice text, warnings
              |
              v
     Application decisions and UI

For a broader introduction, start with Get started with Navigation. Then continue with Get started with Positioning, Add voice guidance, Stay aware with warners, and Get started with offline maps. For trips with unreliable connectivity, also review prefetching map data.