Route generation

SDKs covered:
Navigation SDK
Navigation UI SDK
Route generation and the Navigation UI SDK

This guide does not describe any specific options in the Navigation UI SDK, but, the concepts described in this guide are important to understand if you are using the Navigation UI SDK. You will need to provide either a valid DirectionsRoute object or both an origin and destination Point object to the NavigationView. If you provide both, only the DirectionsRoute will be used.

For details on default and custom route styling using the Navigation UI, see Map and application design.

The core Navigation SDK uses routes generated by the Mapbox Directions API. The Navigation SDK's NavigationRoute class wraps the MapboxDirections class with parameters that must be set in order for a navigation session to successfully begin.

You can use the NavigationRoute.Builder class to create a new request to the Mapbox Directions API. There are over a dozen methods that can be used to customize your request, but only three are required:

  • accessToken
  • origin
  • destination

The response will be a NavigationRoute object, which you can use to display a route on a map or start a navigation sequence.

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

Request a route in a specific direction

Consider the direction a user’s device is facing, and request a route starting in a specific direction. To receive a route that starts off in the same direction the user is already traveling, pass in the user’s location bearingvalue (between 0 and 355 degrees).

If you need to request a route that's continuing along the path that the user is traveling, specify a bearing and a tolerance that determines how far you are willing to deviate from the provided bearing. This is useful for off-route scenarios.

Device location: In the adjacent diagram, the blue dot with white stroke is the device location.

Bearing: The bearing tells you the direction a user's device is facing. It is an angle clockwise from true north between 0 and 359. For example, if the device is facing north, the bearing will be 0°, and if the user is facing due east, the bearing will be 90°. In the adjacent diagram, the pink arrow is the direction that the device is facing (which is due west or 270°).

Tolerance: Tolerance is the range of degrees by which a route can deviate from the bearing angle and still be recommended. The semi-transparent blue area illustrates tolerance. In this example tolerance is 90° (45° in either direction from the bearing angle).

This can be applied to the origin, waypoints, and the destination using NavigationRoute:

// An Android Location object
double bearing = Float.valueOf(location.getBearing()).doubleValue();
double tolerance = 90d;
.origin(origin, bearing, tolerance)

Specify a side of the road to approach

You can state from which side of the road to approach a waypoint by adding approaches to the NavigationRoute builder. There are three options found in DirectionsCriteria.ApproachesCriteria:

  • "unrestricted" (default): the route can approach waypoints from either side of the road.
  • "curb": the route will be returned so that on arrival, the waypoint will be found on the side that corresponds with the driving_side of the region in which the returned route is located.
  • null: if no option is specified, it is translated internally to "", which has the same result as setting an approach to "unrestricted".

If provided, the list of approaches must be the same length as the list of waypoints (including the origin and the destination) and in that particular order (origin, waypoints, destination).

If a re-route occurs and approaches were used to fetch the DirectionsRoute that was originally provided to the NavigationView, the new route fetched will take the same approaches criteria into account.

NavigationRoute.Builder builder = NavigationRoute.builder(context)
builder.addApproaches("unrestricted", "curb", "curb");;

Include multiple stops

If your navigation involves several pick-up and drop-off points, you can add up to 25 coordinates (including the origin and destination) to the NavigationRoute builder using the driving profile or three coordinates using the driving-traffic profile. These coordinates are treated as stops in between the origin and destination Points (in the order that you add them — the first waypoint is the first stop):

NavigationRoute.Builder builder = NavigationRoute.builder(context)
for (Point waypoint : waypoints) {

More about route generation

Read more about route generation in:

  • Localization: Customize the language and units of measurement returned for both text and voice instructions or use the language preferences set on the device.
  • Offline routing: Provide routing functionality from the Navigation SDK in non-connected environments.