Navigation SDK for Android Reference (1.1.0)
All modules /  libnavigation-core / com.mapbox.navigation.core / MapboxNavigation


@UiThread class MapboxNavigation

Mapbox Navigation Core SDK

An entry point for interacting with the Mapbox Navigation SDK.

Only one instance of this class should be used per application process. Use MapboxNavigationProvider to easily manage the instance across lifecycle.

Feel free to visit our docs pages and examples before diving in!

The MapboxNavigation implementation can enter into a couple of internal states:

The SDK starts off in an Idle state.


Whenever the startTripSession is called, the SDK will enter the Free Drive state starting to request and propagate location updates via the LocationObserver.

This observer provides 2 location update values in mixed intervals - either the raw one received from the provided LocationEngine or the enhanced one map-matched internally using SDK's native capabilities.

In Free Drive mode, the enhanced location is computed using nearby to user location's routing tiles that are continuously updating in the background. This can be configured using the OnboardRouterOptions in the NavigationOptions.

If the session is stopped, the SDK will stop listening for raw location updates and enter the Idle state.


A route can be requested with requestRoutes. If the request is successful and returns a non-empty list of routes in the RoutesObserver, the first route at index 0 is going to be chosen as a primary one.

If the SDK is in an Idle state, it stays in this same state even when a primary route is available.

If the SDK is already in the Free Drive mode or entering it whenever a primary route is available, the SDK will enter the Active Guidance mode instead and propagate meaningful RouteProgress.

If a new routes request is made, or the routes are manually cleared, the SDK automatically fall back to either Idle or Free Drive state.

You can use setRoutes to provide new routes, clear current ones, or change the route at primary index 0.


navigationOptions - a set of NavigationOptions used to customize various features of the SDK. Use defaultNavigationOptionsBuilder to set default options



Mapbox Navigation Core SDK

MapboxNavigation(navigationOptions: NavigationOptions)



a set of NavigationOptions used to customize various features of the SDK. Use defaultNavigationOptionsBuilder to set default options

val navigationOptions: NavigationOptions



API used to artificially add debug events to logs.

fun addHistoryEvent(eventType: String, eventJsonProperties: String): Unit


Start observing faster routes for a trip session via FasterRouteObserver

fun attachFasterRouteObserver(fasterRouteObserver: FasterRouteObserver): Unit


Stop observing the possibility of faster routes.

fun detachFasterRouteObserver(): Unit


Get currently set RerouteController.

fun getRerouteController(): RerouteController?


Get a list of routes.

fun getRoutes(): List<DirectionsRoute>


Return the current TripSession's state. The state is TripSessionState.STARTED when the session is active, running a foreground service and requesting and returning location updates. The state is TripSessionState.STOPPED when the session is inactive.

fun getTripSessionState(): TripSessionState


After arriving at a stop, this can be used to manually decide when to start navigating to the next stop. Use the ArrivalController to control when to call navigateNextRouteLeg.

fun navigateNextRouteLeg(): Boolean


Call this method whenever this instance of the MapboxNavigation is not going to be used anymore and should release all of its resources.

fun onDestroy(): Unit


Send user feedback about an issue or problem with the Navigation SDK.

fun postUserFeedback(feedbackType: String, description: String, feedbackSource: String, screenshot: String?, feedbackSubType: Array<String>? = emptyArray(), appMetadata: AppMetadata? = null): Unit


Registers ArrivalObserver. Monitor arrival at stops and destinations. For more control of arrival at stops, see setArrivalController.

fun registerArrivalObserver(arrivalObserver: ArrivalObserver): Unit


Registers BannerInstructionsObserver. The updates are available whenever SDK is in an Active Guidance state. The SDK will push this event only once per route step.

fun registerBannerInstructionsObserver(bannerInstructionsObserver: BannerInstructionsObserver): Unit


Registers LocationObserver. The updates are available whenever the trip session is started.

fun registerLocationObserver(locationObserver: LocationObserver): Unit


Registers OffRouteObserver. The updates are available whenever SDK is in an Active Guidance state and detects an off route event.

fun registerOffRouteObserver(offRouteObserver: OffRouteObserver): Unit


Registers an observer that gets notified whenever the route changes and provides the list of alerts on this new route, if there are any. The alerts returned here are equal to the ones available in RouteProgress.upcomingRouteAlerts, but they capture the whole route (not only what's ahead of us) and don't have the UpcomingRouteAlert.distanceToStart data.

fun registerRouteAlertsObserver(routeAlertsObserver: RouteAlertsObserver): Unit


Registers RouteProgressObserver. The updates are available whenever the trip session is started and a primary route is available.

fun registerRouteProgressObserver(routeProgressObserver: RouteProgressObserver): Unit


Registers RoutesObserver. The updates are available when a new list of routes is set. The route at index 0, if exist, will be treated as the primary route for 'Active Guidance'.

fun registerRoutesObserver(routesObserver: RoutesObserver): Unit


Registers TripSessionStateObserver. Monitors the trip session's state.

fun registerTripSessionStateObserver(tripSessionStateObserver: TripSessionStateObserver): Unit


Registers VoiceInstructionsObserver. The updates are available whenever SDK is in an Active Guidance state. The SDK will push this event only once per route step.

fun registerVoiceInstructionsObserver(voiceInstructionsObserver: VoiceInstructionsObserver): Unit


Requests a route using the provided Router implementation. If the request succeeds and the SDK enters an Active Guidance state, meaningful RouteProgress updates will be available.

fun requestRoutes(routeOptions: RouteOptions, routesRequestCallback: RoutesRequestCallback? = null): Unit


API used to retrieve logged location and route progress samples for debug purposes.

fun retrieveHistory(): String


API used to retrieve the SSML announcement for voice instructions.

fun retrieveSsmlAnnouncementInstruction(index: Int): String?


Set your own controller to determine when drivers arrived at stops via ArrivalController. Use navigateNextRouteLeg to manually move navigator to the next stop. To reset to the automatic arrival controller, call setArrivalController.

fun setArrivalController(arrivalController: ArrivalController? = AutoArrivalController()): Unit


Set RerouteController that's automatically invoked when user is off-route.

fun setRerouteController(rerouteController: RerouteController? = defaultRerouteController): Unit


Set a list of routes.

fun setRoutes(routes: List<DirectionsRoute>): Unit


Starts listening for location updates and enters an Active Guidance state if there's a primary route available or a Free Drive state otherwise.

fun startTripSession(): Unit


Stops listening for location updates and enters an Idle state.

fun stopTripSession(): Unit


API used to enable/disable location and route progress samples logs for debug purposes.

fun toggleHistory(isEnabled: Boolean): Unit


Unregisters ArrivalObserver.

fun unregisterArrivalObserver(arrivalObserver: ArrivalObserver): Unit


Unregisters BannerInstructionsObserver.

fun unregisterBannerInstructionsObserver(bannerInstructionsObserver: BannerInstructionsObserver): Unit


Unregisters LocationObserver.

fun unregisterLocationObserver(locationObserver: LocationObserver): Unit


Unregisters OffRouteObserver.

fun unregisterOffRouteObserver(offRouteObserver: OffRouteObserver): Unit


Unregisters the route alerts observer.

fun unregisterRouteAlertsObserver(routeAlertsObserver: RouteAlertsObserver): Unit


Unregisters RouteProgressObserver.

fun unregisterRouteProgressObserver(routeProgressObserver: RouteProgressObserver): Unit


Unregisters RoutesObserver.

fun unregisterRoutesObserver(routesObserver: RoutesObserver): Unit


Unregisters TripSessionStateObserver.

fun unregisterTripSessionStateObserver(tripSessionStateObserver: TripSessionStateObserver): Unit


Unregisters VoiceInstructionsObserver.

fun unregisterVoiceInstructionsObserver(voiceInstructionsObserver: VoiceInstructionsObserver): Unit


Sends an event to improve navigation positioning. See SensorEventEmitter to register

fun updateSensorEvent(sensorEvent: SensorEvent): Unit

Companion Object Functions


Returns a pre-build set of NavigationOptions with smart defaults.

fun defaultNavigationOptionsBuilder(context: Context, accessToken: String?): Builder