Navigation is only available with the Navigate license.
The HERE SDK enables you to build a comprehensive turn-by-turn navigation experience. With this feature, your app can check the current device location against a calculated route and get navigational instructions just-in-time.  Key features include: * **Automated rendering**: A tailored navigation map view can be optionally rendered with the `VisualNavigator`. Once `startRendering()` is called, it will add a preconfigured `MapMarker3D` instance in form of an arrow to indicate the current direction - and incoming location updates are smoothly interpolated. In addition, the map orientation is changed to the best suitable default values. * **Tracking mode**: Even without having a route to follow, the HERE SDK supports a tracking mode, which provides information about the current street, the map-matched location and other supporting details such as speed limits. * **Real-time instructions**: Voice guidance is provided with maneuver notifications that can be fed as a `String` into any platform TTS (Text-To-Speech) solution. * **Support for warners**: Stay aware with a comprehensive warner system that includes alerts on speed limits, truck restrictions, road signs and many more. * **Offline support**: Almost all navigation features work also without an internet connection when [offline map](android-offline-maps.md) data has been cached, installed or preloaded: only a few features require an online connection, for example, when using the `DynamicRouteEngine` to search online for traffic-optimized routes. The basic principle of turn-by-turn navigation is to frequently receive a location including speed and bearing values. These values are then matched to a street and compared to the desired route. A maneuver instruction is given to let you orient where you are and where you want to go next. When leaving the route, you can be notified of the deviation in meters. This notification can help you to decide whether or not to calculate a new route. And finally, a location simulator allows you to test route navigation during the development phase. > #### Note > > Application developers using turn-by-turn navigation are required to thoroughly test their applications in all expected usage scenarios to ensure safe and correct behavior. Application developers are responsible for warning app users of obligations including but not limited to: > > * Do not follow instructions that may lead to an unsafe or illegal situation. > * Obey all local laws. > * Be aware that using a mobile phone or some of its features while driving may be prohibited. > * Always keep hands free to operate the vehicle while driving. > * Make road safety the first priority while driving. ## How does it work? 1. There are two main entry points to start with navigation: 1. The `Navigator` class provides all functionality to react on `Location` data. It provides guidance instructions to follow a route accompanied with an extensive warner system that provides all kind of information along the road. The latter is also available in tracking mode without following a route. 2. The `VisualNavigator` class provides the same features as the headless `Navigator`, but offers a pre-configured 3D map view experience on top. On top, it provides junction views and other optional visual elements. 2. `Location` data needs to be provided. Use your own solution - or use the HERE SDK: The [Get Locations](android-get-locations.md) guide provides all the details. 3. Voice guidance is supported by giving textual instructions with optional phoneme support and natural guidance information. These strings can be used with any available TTS feature (third-party or native OS). 4. Use the `RoutePrefetcher` to optimize the experience in low connectivity situations, or download and install [offline maps](android-offline-maps.md) to navigate completely without an internet connection. For more information on prefetching map data, [see](android-offline-maps-options.md#prefetch-map-data). ## Initialize the Navigator or VisualNavigator With the `VisualNavigator` the HERE SDK provides a ready-made visual experience to start guidance. This component creates a map view with all the required bits to show the progress while advancing on a route. Optionally, you can customize the view or render it completely on your own with the headless `Navigator`. You can initialize the `Navigator` in the same way as the `VisualNavigator`: ```java Java try { visualNavigator = new VisualNavigator(); } catch (InstantiationErrorException e) { throw new RuntimeException("Initialization of VisualNavigator failed: " + e.error.name()); } ``` ```kotlin Kotlin try { visualNavigator = VisualNavigator() } catch (e: InstantiationErrorException) { throw RuntimeException("Initialization of VisualNavigator failed: " + e.error.name) } ``` ## Listen for navigation events Before you can start to navigate to a destination, you need two things: 1. A `Route` to follow. The `Route` must be set to the `Navigator` or `VisualNavigator` instance to start navigation. 2. A location source that periodically tells the `Navigator` or `VisualNavigator` instance where you are. Unless you have already calculated a route, create one: getting a `Route` instance is shown [here](android-routing.md). If you only want to start the app in tracking mode, you can skip this step. > #### Note > > During turn-by-turn navigation, you will get all `Maneuver` information from the `Navigator` or the `VisualNavigator` instance - synced with your current `Location`. As long as you navigate, do not take the `Manuever` data from the `Route` object directly. The below code snippet shows all the code that is needed to start simulated guidance using simulated `Location` events taken from the `Route`. It uses the `VisualNavigator` instance, so that the HERE SDK will take over the rendering part until `stopRendering()` is called: ```java Java private void startGuidance(Route route) { try { // Without a route set, this starts tracking mode. visualNavigator = new VisualNavigator(); } catch (InstantiationErrorException e) { throw new RuntimeException("Initialization of VisualNavigator failed: " + e.error.name()); } // This enables a navigation view including a rendered navigation arrow. visualNavigator.startRendering(mapView); // Hook in one of the many listeners. Here we set up a listener to get instructions on the maneuvers to take while driving. // For more details, please check the "Navigation" example app and the Developer Guide. visualNavigator.setEventTextListener((EventText eventText) -> { Log.d("ManeuverNotifications", eventText.text); }); // Set a route to follow. This leaves tracking mode. visualNavigator.setRoute(route); // VisualNavigator acts as LocationListener to receive location updates directly from a location provider. // Any progress along the route is a result of getting a new location fed into the VisualNavigator. setupLocationSource(visualNavigator, route); } private void setupLocationSource(LocationListener locationListener, Route route) { try { // Provides fake GPS signals based on the route geometry. locationSimulator = new LocationSimulator(route, new LocationSimulatorOptions()); } catch (InstantiationErrorException e) { throw new RuntimeException("Initialization of LocationSimulator failed: " + e.error.name()); } locationSimulator.setListener(locationListener); locationSimulator.start(); } ``` ```kotlin Kotlin private fun startGuidance(route: Route?) { try { // Without a route set, this starts tracking mode. visualNavigator = VisualNavigator() } catch (e: InstantiationErrorException) { throw RuntimeException("Initialization of VisualNavigator failed: " + e.error.name) } // This enables a navigation view including a rendered navigation arrow. visualNavigator!!.startRendering(mapView!!) // Hook in one of the many listeners. Here we set up a listener to get instructions on the maneuvers to take while driving. // For more details, please check the "Navigation" example app and the Developer's Guide. visualNavigator!!.eventTextListener = EventTextListener { eventText: EventText -> Log.d("Maneuver text", eventText.text) } // Set a route to follow. This leaves tracking mode. visualNavigator!!.route = route // VisualNavigator acts as LocationListener to receive location updates directly from a location provider. // Any progress along the route is a result of getting a new location fed into the VisualNavigator. setupLocationSource(visualNavigator!!, route) } private fun setupLocationSource(locationListener: LocationListener, route: Route?) { try { // Provides fake GPS signals based on the route geometry. locationSimulator = LocationSimulator(route!!, LocationSimulatorOptions()) } catch (e: InstantiationErrorException) { throw RuntimeException("Initialization of LocationSimulator failed: " + e.error.name) } locationSimulator!!.listener = locationListener locationSimulator!!.start() } ``` This code excerpt will start a guidance view and it will print maneuver instructions to the console until you have reached the destination defined in the provided `route` (for the full code including declarations see the [NavigationQuickStart](https://github.com/heremaps/here-sdk-examples) example app.). Note that the maneuver instructions are meant to be spoken to a driver and they may contain strings like "Turn left onto Invalidenstraße in 500 meters.". More detailed maneuver instructions are also available - they are showed in the sections below. Note that above we are using the simulation feature of the HERE SDK to acquire location updates. Of course, you can also feed real location updates into the `VisualNavigator`. > #### Note > > Unlike for other engines, the `VisualNavigator` or the `Navigator` will automatically try to download online data when reaching regions that have not been cached, installed or preloaded beforehand. And vice versa, both components will make use of offline map data when it is available on a device - even if an online connection is available. ## Feed locations into a navigator As shown above, you need to provide `Location` instances - as navigation is not possible without getting frequent updates on the current location. Let's take another look on how to fed non-simulated as well as simulated `Location` data into the system. The navigation component is decoupled from positioning: new locations can be provided by implementing a platform-specific positioning solution, using an external provider, leveraging the HERE Positioning feature of the HERE SDK, or setting up a location simulator.  Note that you can set any `Location` source as "location provider". Only `onLocationUpdated()` has to be called on the `Navigator` or `VisualNavigator`. It is the responsibility of the developer to feed in valid locations into the `VisualNavigator`. For each received location, the `VisualNavigator` will respond with appropriate events that indicate the progress along the route, including maneuvers and a possible deviation from the expected route. The resulting events depend on the accuracy and frequency of the provided location signals. When using HERE Positioning, we recommend using `LocationAccuracy.NAVIGATION`, as this provides the best results in a navigation context. > All events are given based on a map-matched location - this is done automatically by the HERE SDK which incorporates calling the `MapMatcher` component to match a raw location signal to the nearest road. Note that for the `MapMatcher` to work properly, it's required to set the `Location.time` parameter, otherwise, the location will be ignored. It is recommended to also provide `bearing` and `speed` parameters for each `Location` object. A positioning provider implementation using HERE Positioning can be found on GitHub for both [Java](https://github.com/heremaps/here-sdk-examples/blob/master/examples/latest/navigate/android/Java/Navigation/) and [Kotlin](https://github.com/heremaps/here-sdk-examples/tree/master/examples/latest/navigate/android/Kotlin/NavigationKotlin). It provides simulated `Location` events with the `HEREPositioningSimulator` class and non-simulated `Location` events with the `HEREPositioningProvider` class. We recommend to follow the [Positioning](android-get-locations.md) guide to discover more details on all supported HERE Positioning features. Both, the `Navigator` and the `VisualNavigator` classes conform to the `LocationListener` interface that defines the `onLocationUpdated()` method to receive locations: ```java Java // Now visualNavigator will receive locations from the HEREPositioningProvider. // Choose a suitable accuracy for the navigation use case. herePositioningProvider.startLocating(visualNavigator, LocationAccuracy.NAVIGATION); ``` ```kotlin Kotlin // Now visualNavigator will receive locations from the HEREPositioningProvider. // Choose a suitable accuracy for the navigation use case. herePositioningProvider.startLocating(visualNavigator, LocationAccuracy.NAVIGATION) ``` Optionally, set the route you want to follow - unless you plan to start in tracking mode: ```java Java visualNavigator.setRoute(route); ``` ```kotlin Kotlin visualNavigator.route = route ``` ## Start and stop guidance While turn-by-turn navigation automatically starts when a `route` is set and the `herePositioningProvider` is started, stopping navigation depends on the possible scenario: Either, you want to stop navigation and switch to tracking mode (see below) to receive map-matched locations while still following a path - or you want to stop navigation without going back to tracking mode. For the first case, you only need to set the current `route` to `null`. This will only stop propagating all turn-by-turn navigation related events, but keep the ones alive to receive map-matched location updates and, for example, speed warning information. Note that propagation of turn-by-turn navigation events is automatically stopped when reaching the desired destination. Once you set a `route` again, all turn-by-turn navigation related events will be propagated again. If you want to stop navigation without going back to tracking mode - for example, to get only non-map-matched location updates directly from a location provider - it is good practice to stop getting all events from the `VisualNavigator`. For this you should set all listeners individually to `null`. You can reuse your location provider implementation to consume location updates in your app. With HERE positioning you can set multiple `LocationListener` instances. When you use the `VisualNavigator`, call `stopRendering()`. Once called, the `MapView` will be no longer under control by the `VisualNavigator`: * Settings, like map orientation, camera distance or tilt, which may have been altered during rendering are no longer updated. They will keep the last state before `stopRendering()` was called. For example, if the map was tilted during guidance, it will stay tilted. Thus, it is recommended to apply the desired camera settings after `stopRendering()` is called. * The map will no longer move to the current location - even if you continue to feed new locations into the `VisualNavigator`. * The default or custom location indicator owned by the `VisualNavigator` will be hidden again. * Note that all location-based events such as the `RouteProgress` will be still delivered unless you unsubscribe by setting a null listener - see above. > #### Note > > Since the `VisualNavigator` operates on a `MapView` instance, it is recommended to call `stopRendering()` before destroying a `MapView`. In addition, it is recommended to stop `LocationSimulator` and `DynamicRoutingEngine` in case they were started before. However, when a `MapView` is paused, it is not necessary to also stop the `VisualNavigator`. The `VisualNavigator` stops automatically to render when the `MapView` is paused and it starts rendering when the `MapView` is resumed (when the `VisualNavigator` was rendering before). ## Start and stop tracking While you can use the `VisualNavigator` class to start and stop turn-by-turn navigation, it is also possible to switch to a tracking mode that does not require a route to follow. This mode is also often referred to as the "driver's assistance mode". It is available for all transport modes - except for public transit. Public transit routes may lead to unsafe and unexpected results when being used for tracking. Although all other transport modes are supported, tracking is most suitable for vehicle transport modes. To enable tracking, you only need to call: ```java Java visualNavigator.setRoute(null); herePositioningProvider.startLocating(visualNavigator, LocationAccuracy.NAVIGATION) ``` ```kotlin Kotlin visualNavigator.route = route herePositioningProvider.startLocating(visualNavigator, LocationAccuracy.NAVIGATION) ``` Here we enable getting real GPS locations, but you could also play back locations from any route using the `LocationSimulator` (as shown above). Of course, it is possible to initialize the `VisualNavigator` without setting a `route` instance - if you are only interested in tracking mode you don't need to set the route explicitly to null. > #### Note > > Note that in tracking mode you only get events for listeners such as the `NavigableLocationListener` or the `SpeedWarningListener` that can fire without the need for a route to follow. In general, all warners are supported. Other listeners such as the `RouteProgressListener` do not deliver events when a route is not set. > > This enables you to keep your listeners alive and to switch between free tracking and turn-by-turn-navigation on the fly. > > Consult the API Reference for an overview to see which listeners work in tracking mode. Tracking can be useful, when drivers already know the directions to take, but would like to get additional information such as the current street name or any speed limits along the trip. When tracking is enabled, it is also recommended to enable the `SpeedBasedCameraBehavior`: ```java Java visualNavigator.setCameraBehavior(new SpeedBasedCameraBehavior()); ``` ```kotlin Kotlin visualNavigator.cameraBehavior = SpeedBasedCameraBehavior() ``` This camera mode is automatically adjusting the camera's location to optimize the map view based on the current driving speed. In order to stop following the camera, call: ```java Java visualNavigator.setCameraBehavior(null); ``` ```kotlin Kotlin visualNavigator.cameraBehavior = null ``` This can be also useful during guidance, if you want to temporarily enable gesture handling. It is recommended to automatically switch back to tracking if turn-by-turn navigation is ongoing - in order to not distract a driver. ## Get maneuver progress events During navigation, you typically want to attach a few listeners to get notified about the route progress, current location, and the next maneuver to take. The HERE SDK provides many different listeners for different purposes. Below, we show how to get progress events: ```java Java // Notifies on the progress along the route including maneuver instructions. visualNavigator.setRouteProgressListener(new RouteProgressListener() { @Override public void onRouteProgressUpdated(@NonNull RouteProgress routeProgress) { List