Navigation SDK for Android v2

Initialize the SDK

Navigation applications require many types of data that are constantly updated to provide information to the user. To being accessing this data you need to initialize the Navigation SDK and start a trip session. Then, you can use this data to power two kinds of navigation experiences: passive navigation (also known as free-drive mode) or active guidance (or turn-by-turn navigation).

Initialize the Navigation SDK

There are two steps you need to complete to initialize the Navigation SDK and begin receiving data:

  • Create a MapboxNavigation object, which is the entry point for interacting with the Navigation SDK.
  • Start a trip session, which allows you to start consuming and processing data.

Create the MapboxNavigation object

The MapboxNavigation object is the primary entity of the Navigation SDK and the producer of the majority of the data needed in a navigation application.

MapboxNavigation instance

MapboxNavigation is a singleton-like object, there should only be one instance running per application process. This object can be safely used across different activities and fragments, or accessed from a ViewModel. The instance can also be safely destroyed and recreated if needed.

To create the object use the MapboxNavigationProvider and pass the NavigationOptions. The MapboxNavigationProvider ensures you will only have one MapboxNavigation instance in your application.

val navigationOptions = NavigationOptions.Builder(this)
val mapboxNavigation = MapboxNavigationProvider.create(navigationOptions)

You can also use MapboxNavigationProvider to access MapboxNavigation anywhere in your application using the retrieve() function.

fun registerObservers() {
    if (MapboxNavigationProvider.isCreated()) {

Whenever your navigation experience ends, you should destroy the instance:

fun onCleared() {

Once the MapboxNavigation object is initialized, the Navigation SDK starts in an internal idle state. There's no location data being consumed or processed and no updates are generated.

Start a trip session

To start consuming and processing data, you need to start a trip session using startTripSession():

Location permissions

Starting a trip session requires user location permissions. Read more about how to request the permissions in the Android developer documentation.

When you start a session, the MapboxNaivgation object will:

  1. Request raw location updates from the LocationEngine provided in the NavigationOptions. Read more about using default and custom location engines in the Device location guide.
  2. Process the incoming raw location updates and deliver various data observers updates with processed data.

When a trip session is running, there's also an Android foreground service running and displaying a notification so the Navigation SDK can keep receiving raw location updates, even if the app is minimized.

To shutdown the foreground location service and stop data processing, you need to stop a session by calling:

Pricing and trip sessions

Learn what is a billable lifecycle of a session, how sessions are counted, and how does that impact your usage costs in the Pricing documentation.

Types of navigation

Once you've started a trip session, your users can use the Navigation SDK for either free-drive mode or active guidance.


Free-drive mode, also referred to as passive navigation, is a unique Mapbox Navigation SDK feature that allows drivers to take advantage of some navigation features without selecting a route and following turn-by-turn instructions to a set destination.

You can center the map on the driver’s current location as their location changes and proactively provide drivers with relevant information about nearby places and roads including traffic, incidents, and points of interest. For example, free-drive mode might be helpful to drivers who are in areas they are familiar with and do not need turn-by-turn instructions, but may want to avoid congested roads.

The Navigation SDK goes into an internal free-drive state when a trip session is started and no route has been selected. At the same time, the Navigation SDK will start downloading and caching a road graph. An up-to-date road graph is necessary to effectively enhance the device location, match it to a road-based on raw GPS signal, and power other features of the Navigation SDK.

You'll begin receiving user device location updates via the LocationObserver or the MapMatcherResultObserver.

You'll also be able to take advantage of electronic horizon and learn about road objects around the device's location, you can read more about it in the Electronic horizon guide.

Active guidance

Active guidance is likely what comes to mind when you think about a typical turn-by-turn navigation experience: a user receives turn-by-turn instructions as they progress along the route. If a trip session is running and a route is selected, the Navigation SDK goes into an internal active guidance state. You can read more about how to retrieve and manage a route to a destination in the Route generation.

At this point, you'll begin receiving route progress updates via the RouteProgressObserver. You will receive information about navigation instructions (voice and text) that can be used to guide the user. The SDK will also track the device location for potential off-route events and automatically reroute whenever necessary.