Custom routes

SDKs covered:
Navigation SDK
Navigation UI SDK

In some cases, you may want to have the user stick to a specific route that doesn't fit into the scope covered by the Mapbox Directions API. For example, a parking finder app where you want to guide a user past specific blocks with parking, but also allow people to navigate on it with the Mapbox Navigation SDK for Android. The Mapbox Map Matching API is an appropriate fit for this situation.

Use a map matching response to generate a route

Map matching is the art of taking coordinates and aligning them along a road network. In the parking example above, you would provide coordinates to the device, the coordinates would be passed to the Mapbox Map Matching API, and then the API would return a route that can be used in the Navigation SDK for Android.

Here is an example of converting a MapboxMapMatching response into a DirectionsRoute:

.enqueueCall(new Callback<MapMatchingResponse>() {
public void onResponse(Call<MapMatchingResponse> call, Response<MapMatchingResponse> response) {
if (response.isSuccessful()) {
DirectionsRoute route = response.body().matchings().get(0).toDirectionRoute();
public void onFailure(Call<MapMatchingResponse> call, Throwable throwable) {

When using MapboxMapMatching with the Navigation UI SDK's NavigationView, you need to make a few changes to your setup to make sure re-routes are successful. A RouteListener must be added to your NavigationViewOptions and you must return false in the allowRerouteFrom callback. This will make sure that the NavigationView does not make a Directions API request. Instead, it will wait for the new DirectionsRoute provided by your map matching response.

public boolean allowRerouteFrom(Point offRoutePoint) {
// Fetch new route with MapboxMapMatching
// Create new options with map matching response route
NavigationViewOptions options = NavigationViewOptions.builder()
// Ignore internal routing, allowing MapboxMapMatching call
return false;

Map matching with MapboxNavigation

In the core Navigation SDK, MapboxMapMatching requests replace NavigationRoute requests. To start navigation initially or to restart navigation after an off-route event has been fired, you can make a map matching request and then convert the MapMatchingMatching response to a DirectionsRoute with MapMatchingMatching#toDirectionRoute.

navigation.addOffRouteListener(new OffRouteListener() {
public void userOffRoute(Location location) {
// Make the Map Matching request here
// Call MapboxNavigation#startNavigation with successful response
Was this page helpful?