Navigation SDK for Android

The Navigation SDK for Android v1.0.0 is in public beta and is subject to changes.

Navigation SDK for Android

Current version: v1.0.0-rc.2 View changelog

  • Flexible modularization
  • Free-drive mode
  • Accurate positioning
  • Scaled pricing with no commitments

The Navigation SDK for Android allows you to build a complete navigation experience with the power of the Mapbox Directions API. The Navigation SDK provides a collection of features that are critical when building navigation projects, including:

  • Navigation routes
  • Accurate device location updates
  • Voice instruction announcements
  • Real-time user progress to their destination
  • Off-route detection


You'll need to add the Navigation SDK as a dependency before developing your project.

Migrating from the current Navigation SDK

Read Mapbox's migration guide on GitHub if your project is using the current stable "legacy" Mapbox Navigation SDK for Android and you want to transition it to this beta version of the Navigation SDK for Android.

Including the Maps SDK

The core Navigation SDK doesn't include the Mapbox Maps SDK for Android, so if you're planning to display navigation information on top of a map, you'll need to add the Mapbox Maps SDK as a dependency before developing your project. Read the Maps SDK installation docs to get started.

Configure credentials

Before installing the Mapbox Navigation SDK, you will need to gather the appropriate credentials. The Navigation SDK requires two pieces of sensitive information from your Mapbox account. If you don't have a Mapbox account: sign up and navigate to your Account page. You'll need:

  • A public access token: From your account's tokens page, you can either copy your default public token or click the Create a token button to create a new public token.
  • A secret access token with the Navigation:Download scope:

    1. From your account's tokens page, click the Create a token button.
    2. From the token creation page, give your token a name and make sure the box next to the Navigation:Download scope is checked.
    3. Click the Create token button at the bottom of the page to create your token.
    4. The token you've created is a secret token, which means you will only have one opportunity to copy it somewhere secure.

You should not expose these access tokens in publicly-accessible source code where unauthorized users might find them. Instead, you should store them somewhere safe on your computer and take advantage of Gradle properties to make sure they're only added when your app is compiled. Once this configuration step has been completed, you will be able to reference your credentials in other parts of your app.

Configure your secret token

  1. Find or create a file in your Gradle user home folder. The folder can be found at «USER_HOME»/.gradle. Once you have found or created the file, its path should be «USER_HOME»/.gradle/ You can read more about Gradle properties in the official Gradle documentation.
  2. Add the following key-value pairs to your file:

    1. MAPBOX_USERNAME=mapbox

Configure your public token

There are many ways to configure your public access token. Many of the examples and code snippets on this site assume your token in stored in a file in your project with other string values. If you would like to manage your public access token this way, open your project's R.strings.xml file and add the following string resource:

<string name="mapbox_access_token">MAPBOX_ACCESS_TOKEN</string>

If you ever need to rotate your access token, you'll then update the token in your R.strings.xml file.

Add the dependency

To add the Navigation SDK as a dependency, you will need to configure your build to download the Navigation SDK from Mapbox directly. This requires a valid username and password.

  1. Open your project in Android Studio.

  2. Open up your module-level build.gradle file.

  3. The Navigation SDK uses Java 8 features. To enable Java 8 in your project, add the following compileOptions.

    android {
        compileOptions {
            sourceCompatibility JavaVersion.VERSION_1_8
            targetCompatibility JavaVersion.VERSION_1_8
  4. Make sure that your project's minSdkVersion is at API 19 or higher.

    android {
        defaultConfig {
            minSdkVersion 19
  5. Under dependencies, add a new build rule for the latest mapbox-android-navigation.

    dependencies {
        implementation 'com.mapbox.navigation:core:1.0.0-rc.2'
  6. Open up your project-level build.gradle file. Declare the Mapbox Downloads API's navigation/android/maven endpoint in the repositories block. To download the Navigation SDK dependency, you must authenticate your request with a valid username and password. In the previous section, you added these to a file in your Gradle user home folder.

    allprojects {
        repositories {
            maven {
                url ''
                authentication {
                credentials {
                    username =['MAPBOX_USERNAME'] ?: ""
                    password =['MAPBOX_DOWNLOADS_TOKEN'] ?: ""
  7. Because you've edited your Gradle files, Android Studio will ask you whether you want to sync the Gradle files. You can sync now.

Using nightly builds and beta versions

You can also use a SNAPSHOT version of the Navigation SDK if you want access to bug fixes or features that have not been packaged in an official release yet. Find more information about how to do this inside the Navigation SDK's GitHub repository.

Handle location permissions

The Navigation SDK makes use of the Android manifest merge feature. The Navigation SDK's manifest file already has both the course and fine location permission lines, which means you don't have to declare any location permissions inside your project's manifest file or in some other way.

If your project targets Android API 23 or higher, make sure to check the user location permission in runtime using the Mapbox Core Library for Android's PermissionsManager interface.

Set NavigationOptions

The NavigationOptions class exposes several preferences you might have for your users' turn-by-turn navigation experience. Examples include whether twelve vs. twenty-four ("military time") format should be used and the increment size for rounding distances.

NavigationOptions has a Builder class, which helps you explore what methods are available for setting specific options.

val navigationOptions = NavigationOptions.Builder()

The MapboxNavigation class' static defaultNavigationOptions() method will create navigation options for you if you don't feel that your project needs to customize anything. It only needs a Context object and your Mapbox access token.

val mapboxNavigation = MapboxNavigation.defaultNavigationOptions(context, getString(R.string.mapbox_access_token))

Once created, the NavigationOptions object should be used as a method parameter when creating a MapboxNavigation object.

Create a MapboxNavigation object

Creating a MapboxNavigation object is the first step in interacting with and customizing a navigation session. It's used to request routes, register various Navigation SDK observers, and make other navigation-related decisions.

Create and use only one instance of this class in your project.

The static defaultNavigationOptions() method is the quickest way to create a MapboxNavigation object. It only needs a Context object and your Mapbox access token.

val mapboxNavigation = MapboxNavigation.defaultNavigationOptions(context, getString(R.string.mapbox_access_token))

Alternatively, use the MapboxNavigation's constructor if you'd like to set the various options yourself:

val mapboxNavigation = MapboxNavigation(

Don’t forget to call mapboxNavigation.onDestroy() when the MapboxNavigation instance is no longer needed. This will typically be called in your project's onDestroy() lifecycle method. Destroying the MapboxNavigation instance will automatically release Navigation SDK resources such as unregistering from any observers you might have registered with the MapboxNavigation instance.

override fun onDestroy() {

If you're using a fragment, call mapboxNavigation.onDestroy() inside the fragment's onDestroyView() method instead of onDestroy():

override fun onDestroyView() {


Please see the Pricing by products guide for more information on pricing and billing. Depending on what you're building with the Navigation SDK for Android, your project may be eligible for alternative pricing options.

Was this page helpful?