Navigation SDK for Android

Current version: v0.36.0 View changelog

  • Off-route detection
  • Timed instructions
  • Snap-to-route
  • Route progress information
  • Traffic routing

The Navigation SDK for Android allows you to build a complete in-app navigation experience. With the Navigation SDK you get the power of the Mapbox Directions API along with a collection of features that are critical when building navigation applications for Android, including:

  • Detecting the direction a device is facing and start the route
  • Providing voice instruction announcements
  • Displaying real-time user progress to their destination
  • Detecting when a user goes off-route
  • Specifying which side of the road to approach a waypoint

Available SDKs

There are two SDKs that can be used to integrate navigation into your Android application, the core Navigation SDK and the Navigation UI SDK:

  • The core Navigation SDK is where the logic lives for generating routes, tracking progress, receiving instructions, and more. You can use this directly via the MapboxNavigation class or through the Navigation UI SDK.
  • Built on top of the core Navigation SDK (meaning the Navigation SDK is included when you add the Navigation UI SDK as a dependency), the Navigation UI SDK consumes data from the core SDK and arranges it in default UI components that have various customization options. You can use this directly via the NavigationView and NavigationLauncher classes without touching the core MapboxNavigation class directly in your application's code.
  • The core Navigation SDK and the Navigation UI SDK can be used together if you want to use a mixture of the Mapbox-provided UI components and your own custom UI fed data from the core Navigation SDK.

Product capabilities

This documentation contains information for both the core Navigation SDK and the Navigation UI SDK across a variety of topics:

Installation

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

help
Using nightly builds and beta versions

You can also use the nightly build/SNAPSHOT or the beta version if one is available. Find more information about how to do this inside the Navigation SDK's GitHub repository.

Learn how to install the core Navigation SDK and request your first route using NavigationRoute.

Add the dependency

help
Add the core Navigation SDK only when not using the Navigation UI SDK

If you're using the Navigation UI SDK, you don't have to declare the Mapbox Navigation SDK as well. If you only declare the Navigation UI SDK in your project's Gradle file, the Mapbox Navigation SDK will automatically be included.

  1. Start Android Studio.
  2. Open up your app's build.gradle file.
  3. Make sure that your project's minSdkVersion is at API 14 or higher.
  4. Under dependencies, add a new build rule for the latest mapbox-android-navigation.
  5. Click the Sync Project with Gradle Files near the toolbar in Studio.
allprojects {
    repositories {
        ...
        maven { url 'https://mapbox.bintray.com/mapbox' }
    }
}

dependencies {
  implementation 'com.mapbox.mapboxsdk:mapbox-android-navigation:0.36.0'
}

Get an access token

If you don't have a Mapbox account: sign up and navigate to your Account page. For quick development and testing, you can use your default public token. Later in development, you may want to create an access token specifically for this project. Find more details on managing access tokens in our guide on how access tokens work.

After you've added the Navigation SDK as a dependency inside your Android project, open the string.xml file, create a new string, and paste the access token. Then, pass this into the Navigation SDK.

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
MapboxNavigation navigation = new MapboxNavigation(context, YOUR_MAPBOX_ACCESS_TOKEN);
...
}

Set up permissions

The Navigation SDK makes use of the Android manifest merge feature to reduce the need to include any Navigation SDK requirements inside your application's manifest file. You'll need to include either the fine or coarse location permission for navigation to work properly. The user location permission should also be checked during runtime using the PermissionsManager if your app targets the Android API 23 or higher.

For optimal navigation results, use the fine location permission, which gives a more precise fix on the user's current location.

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Request a route

Now that you have created a way for the MapboxNavigation object to get the user's location, you can create a route using NavigationRoute. Pass in an origin, destination, and a callback to handle the response. Inside the onResponse, you can draw the directions route on a map or show time and distance using the full directions response.

help
More about route generation

Find more detailed information about requesting routes in the Route generation guide.

// From Mapbox to The White House
Point origin = Point.fromLngLat(-77.03613, 38.90992);
Point destination = Point.fromLngLat(-77.0365, 38.8977);
NavigationRoute.builder(context)
.accessToken(YOUR_MAPBOX_ACCESS_TOKEN)
.origin(origin)
.destination(destination)
.build()
.getRoute(new Callback<DirectionsResponse>() {
@Override
public void onResponse(Call<DirectionsResponse> call, Response<DirectionsResponse> response) {
}
@Override
public void onFailure(Call<DirectionsResponse> call, Throwable t) {
}
});

The Navigation UI SDK is the fastest way to get a navigation UI into your application.

Add the dependency

This dependency is different from the one used to compile the core Mapbox Navigation SDK, but it will still include everything from the core Mapbox Navigation SDK. If you're using the Navigation UI SDK, you don't have to declare the Mapbox Navigation SDK. If you only declare the Navigation UI SDK in your project's Gradle file, the Mapbox Navigation SDK will automatically be included.

repositories {
  mavenCentral()
  maven { url 'https://mapbox.bintray.com/mapbox' }
}

dependencies {
  implementation 'com.mapbox.mapboxsdk:mapbox-android-navigation-ui:0.36.0'
}

Launch the Navigation UI

With either a DirectionsRoute from NavigationRoute (see Request a route above) or two Point objects (origin and destination), you can launch the UI with NavigationLauncher from within your Activity.

// Route fetched from NavigationRoute
DirectionsRoute route = ...
boolean simulateRoute = true;
// Create a NavigationLauncherOptions object to package everything together
NavigationLauncherOptions options = NavigationLauncherOptions.builder()
.directionsRoute(route)
.shouldSimulateRoute(simulateRoute)
.build();
// Call this method with Context from within an Activity
NavigationLauncher.startNavigation(this, options);

Prevent memory leaks

Regardless of which SDK you are using, you should override the onDestroy lifecycle method, end the navigation session (if it's running), and use the MabpoxNavigation#onDestroy method inside your application's activity. Doing this prevents any memory leaks and ensures proper shutdown of the service.

@Override
protected void onDestroy() {
super.onDestroy();
// End the navigation session
navigation.onDestroy();
}

Testing and development

There are a few methods that can be helpful when developing and testing your application.

Replay a DirectionsRoute

The Navigation SDK includes a ReplayRouteLocationEngine, which allows you to replay a given DirectionsRoute (mainly for testing, so you don't always have to code in a car). After retrieving a DirectionsRoute, you can create a replay engine and pass it to MapboxNavigation.

MapboxNavigation navigation = ...
DirectionsRoute routeToReplay = ...
ReplayRouteLocationEngine replayEngine = new ReplayRouteLocationEngine();
replayEngine.assign(routeToReplay);
navigation.setLocationEngine(replayEngine);
navigation.startNavigation(routeToReplay);

Turn on debug logging

Turn on debug logging using MapboxNavigationOptions:

MapboxNavigationOptions options = MapboxNavigationOptions.builder()
.isDebugLoggingEnabled(true)
.build();
MapboxNavigation mapboxNavigation = new MapboxNavigation(this, accessToken, options);