Navigation SDK for Android

Custom routes

In some cases, you may want your user to navigate along a route that doesn't match the Mapbox Directions API route's structure, while still using the Mapbox Navigation SDK. Mapbox Java SDK's Map Matching API wrapper is an appropriate tool for turning your custom route into a route that the Navigation SDK can process.

Map match to generate a route

Map matching is the art of taking coordinates and aligning them along a road network. After providing coordinates to the Java SDK's MapboxMapMatching.builder(), the Java SDK makes the request to the Mapbox Map Matching API, and then the API returns a route that can be used in the Navigation SDK for Android.


Map matching to create a route is only possible for the initial route. Making a Map Matching API call while in turn-by-turn navigation isn't possible because the Navigation SDK's internal logic checks whether the device has gone off the intended route. If so, it automatically requests a new route from the Mapbox Directions API. This off-route requesting would clash with making another Map Matching API call as the device is moving.

To get started with creating a map matched DirectionsRoute, first install the Java SDK's services module into your project.

Your MapboxMapMatching request will need a List of Point geometry objects that represent the custom route you want to match with the road network.

val singlePoint = Point.fromLngLat()

Create a MapboxMapMatching request:

val mapboxMapMatchingRequest = MapboxMapMatching.builder()

If successful, the response will have a matched route. Convert this route to a DirectionsRoute and give it to the already-instantiated MapboxNavigation object:

mapboxMapMatchingRequest.enqueueCall(object : Callback<MapMatchingResponse> {
    override fun onResponse(call: Call<MapMatchingResponse>, response: Response<MapMatchingResponse>) {
        if (response.isSuccessful) {
            response.body()?.matchings()?.let { matchingList ->
                matchingList[0].toDirectionRoute().apply {
    override fun onFailure(call: Call<MapMatchingResponse>, throwable: Throwable) {
Map matching

See how to use the Java SDK's Map Matching API wrapper to match points to the world's road and path network.

Was this page helpful?