Route generation
Before a user can begin turn-by-turn navigation with your application, you must provide the Navigation SDK with a route. You can generate a route from the Mapbox Directions API using the Navigation SDK by providing both an origin and a destination Point
object. There are several ways you can customize the returned route and how it is displayed in your application including:
- Adding stops (or waypoints) between the origin and destination.
- Making sure the route begins in the direction in which the driver is already traveling to prevent needing a u-turn.
- Specifying the side of the road to approach when arriving at the destination or at stops along the route.
If you need complete route customization, you can provide a custom already-generated route that is not from the Mapbox Directions API, then transform it into the correct format to be used with the Navigation SDK using the Mapbox Java SDK's Map Matching wrapper. For instructions on this process, see the Use a custom route section.
DirectionsRoute
and a pair of coordinates (origin and destination), only the DirectionsRoute
will be used.Request a route
The Navigation SDK uses routes generated by the Mapbox Directions API. After you’ve created a MapboxNavigation
object, you can use its requestRoutes()
method to request routes from the Mapbox Directions API.
The method requires a built RouteOptions
object as defined in the Mapbox Java SDK's Directions wrapper. The RouteOptions
class has convenient methods for setting the various route parameters. You can find full descriptions of each parameter in the Directions API documentation.
You can use the Java SDK's RouteOptions.builder
class to create a RouteOptions
class as you create a new route request. There are many methods that can be used to customize your request, two of which are required:
coordinatesList()
origin
: aPoint
objectdestination
: aPoint
object
applyDefaultNavigationOptions()
: if you don't want to customize other options, explicitly use the defaults
mapboxNavigation.requestRoutes(
RouteOptions.builder()
.applyDefaultNavigationOptions()
.coordinatesList(listOf(originPoint, destinationPoint))
.build()
)
The origin
and destination
are Point
coordinates that need to be in a single list of Point
s. The origin
should be the first Point
in the list and the destination
should be the last Point
. If there are any other Point
s in the list between the origin
and destination
, these Point
s are considered waypoints.
Fetch routes by specifying two coordinates in RouteOptions
and passing those options to MapboxNavigation
's requestRoutes
method.
Include waypoint stops
If your navigation experience involves several stops along the way to the final destination, you can add up to 25 coordinates (including the origin and destination) to the RouteOptions
builder. The coordinates are treated as stops between the origin and destination Points
in the order that you add them (the first waypoint Point
is the first stop along the route):
mapboxNavigation.requestRoutes(
RouteOptions.builder()
.applyDefaultNavigationOptions()
.coordinatesList(listOf(originPoint, firstWaypoint, secondWaypoint, thirdWaypoint, destinationPoint))
.build()
)
Request a route in a specific direction
The Navigation SDK can make a Directions API request that takes into account the direction the device is facing. The returned route will be ideal for the device's particular bearing.
Device location: In the adjacent diagram, the blue dot with white stroke is the device location.
Bearing: The bearing tells you the direction that a 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 device 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).
The RouteOptions.builder()
's bearingsList()
method is a list of Bearing
objects where each specifies angle clockwise from true north between 0 and 359 and tolerance, which is the range of degrees by which the angle can deviate (recommended value is 45 or 90).
If the bearingsList()
method is used, the list of Bearing
objects must be the same length as the list of Point
s passed through the coordinates()
method. But you can skip a coordinate and show its position in the Bearing
list with the null
value.
mapboxNavigation.requestRoutes(
RouteOptions.builder()
.applyDefaultNavigationOptions()
.coordinatesList(listOf(originPoint, destinationPoint))
.bearingsList(
listOf(
Bearing.builder()
.angle(originLocation.bearing.toDouble())
.degrees(45.0)
.build(),
null
)
)
.build()
)
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 RouteOptions
builder. There are three options found in the DirectionsCriteria
class:
"unrestricted"
(default): the route can approach waypoints from either side of the road. UseDirectionsCriteria.APPROACH_UNRESTRICTED
."curb"
: Return the route in a way that, upon arrival, the waypoint is located on the side corresponding to thedriving_side
of the region where the route is situated. UseDirectionsCriteria.APPROACH_CURB
.null
: if no option is specified, it is translated internally to""
, which has the same result as setting an approach to"unrestricted"
. Usenull
.
If provided, the list of approaches must be the same length as the list of coordinates (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 first DirectionsRoute
, the new route fetched will take the same approaches
criteria into account.
mapboxNavigation.requestRoutes(
RouteOptions.builder()
.applyDefaultNavigationOptions()
.coordinatesList(listOf(originPoint, firstWaypoint, secondWaypoint, thirdWaypoint, destinationPoint))
.approachesList(listOf(DirectionsCriteria.APPROACH_UNRESTRICTED,
DirectionsCriteria.APPROACH_UNRESTRICTED, DirectionsCriteria.APPROACH_CURB, null, DirectionsCriteria.APPROACH_CURB))
.build()
)
Add silent waypoints
Unlike other waypoints that are treated as a stops between route's legs, silent waypoints will influence the route so the user passes through the waypoint without specifically mentioning it in maneuver instructions.
By default all coordinates specified in the coordinatesList
are waypoints.
If you want to specify that one or more coordinates in the list should be treated as silent waypoints, use RouteOption.Builder
's waypointIndicesList
method.
List the index of each coordinate (as it is in coordinatesList
) that should be treated as a waypoint and omit the index of coordinates that should be treated as silent waypoints.
For example, if you want a route that passes through the originPoint
, silentWaypoint
, and destinationPoint
, but you don't want the driver to stop at the middle coordinate, then specify listOf(0, 2)
as waypointIndicesList
.
mapboxNavigation.requestRoutes(
RouteOptions.builder()
.applyDefaultNavigationOptions()
.coordinatesList(listOf(originPoint, silentWaypoint, destinationPoint))
.waypointIndicesList(listOf(0, 2))
.build(),
callback
)
The Navigation SDK will build a route through all three coordinates but the silentWaypoint
won't be mentioned anywhere.
Assign names to waypoints
You can assign a name to any waypoint using RouteOption.Builder
's waypointNamesList
method.
Waypoint names are used in the maneuver UI component and voice instructions.
The example below shows how to generate a route that begins at an originPoint
and stops at "Gas station"
and then "Work"
.
mapboxNavigation.requestRoutes(
RouteOptions.builder()
.applyDefaultNavigationOptions()
.coordinatesList(listOf(originPoint, gasStationWaypoint, workWayPoint))
.waypointNamesList(listOf("", "Gas station", "Work"))
.build(),
callback
)
waypointIndicesList
and waypointNamesList
.Check the status of a route request
The Navigation SDK's mapboxNavigation.requestRoutes()
method requires two parameters: a RouteOptions
object and a NavigationRouterCallback
interface object. The Navigation SDK’s NavigationRouterCallback
interface provides methods, which inform you about the status of a route request.
private val routesReqCallback = object : NavigationRouterCallback {
override fun onRoutesReady(
routes: List<NavigationRoute>,
routerOrigin: RouterOrigin
) {
mapboxNavigation.setNavigationRoutes(routes)
}
override fun onCanceled(routeOptions: RouteOptions, routerOrigin: RouterOrigin) {
}
override fun onFailure(reasons: List<RouterFailure>, routeOptions: RouteOptions) {
}
}
Add the NavigationRouterCallback
object to the mapboxNavigation.requestRoutes()
method:
mapboxNavigation.requestRoutes(
RouteOptions.builder()
.applyDefaultParams()
.coordinatesList(listOf(originPoint, destinationPoint))
.build(),
routesReqCallback
)
Route request/response models
The request/response models provide 2 types of API: Static and Dynamic. Static is used for stable features of Mapbox Directions API, Dynamic for unlisted, experimental, or Developer Preview features.