Route generation
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.
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 accepts a built RouteOptions object. The RouteOptions class has convenient methods for setting the various route parameters available in the Directions API documentation. To set default route options, use defaultNavigationOptionsBuilder when creating your MapboxNavigation object.
You can use the 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, three of which are required:
accessToken()coordinates()origin: aPointobjectdestination: aPointobject
mapboxNavigation.requestRoutes(
RouteOptions.builder()
.accessToken(MAPBOX_TOKEN)
.coordinates(listOf(originPoint, destinationPoint))
.build()
)
The origin and destination Point coordinates need to be in a single list of Points. The origin should be the first Point in the list and the destination should be the last Point. If there are any other Points in the list between the origin and destination, these Points are considered waypoints.
Route request status
The mapboxNavigation.requestRoutes() method’s only required parameter is the built RouteOptions object. An optional second parameter is a RoutesRequestCallback interface object. The Navigation SDK’s RoutesRequestCallback interface provides methods, which inform you about the status of a route request.
private val routesReqCallback = object : RoutesRequestCallback {
override fun onRoutesReady(routes: List<DirectionsRoute>) {
}
override fun onRoutesRequestFailure(throwable: Throwable, routeOptions: RouteOptions) {
}
override fun onRoutesRequestCanceled(routeOptions: RouteOptions {
}
}
Add the RoutesRequestCallback object to the mapboxNavigation.requestRoutes() method:
mapboxNavigation.requestRoutes(
RouteOptions.builder()
.accessToken(MAPBOX_TOKEN)
.coordinates(listOf(originPoint, destinationPoint))
.geometries(RouteUrl.GEOMETRY_POLYLINE6)
.profile(RouteUrl.PROFILE_DRIVING)
.build(),
routesReqCallback
)
requestRoutes() affects the TripSessionState. If you call startTripSession() without calling requestRoutes(), you'll be in "Free Drive" state. If you call requestRoutes() after startTripSession(), you'll be in "Active Guidance" state.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()
.accessToken(MAPBOX_TOKEN)
.coordinates(listOf(originPoint, firstWaypoint, secondWaypoint, thirdWaypoint, destinationPoint))
.geometries(RouteUrl.GEOMETRY_POLYLINE6)
.profile(RouteUrl.PROFILE_DRIVING)
.build()
)
Changed routes
Use the Navigation SDK’s RouteObserver interface if you want to know when the routes list has changed.
private val routeObserver = object : RouteObserver {
override fun onRoutesChanged(routes: List<DirectionsRoute>) {
}
}
Register the RouteObserver interface with your already-instantiated MapboxNavigation object.
mapboxNavigation.registerRouteObserver(routeObserver)
Don’t forget to unregister the RouteObserver interface:
override fun onStop() {
super.onStop()
mapView.onStop()
mapboxNavigation.unregisterRoutesObserver(routeProgressObserver)
}
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 a double lists. The first double value in a single list, the bearing, should be an angle clockwise from true north between 0 and 355. The second value in a single list, the tolerance, should be 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 double pairs must be the same length as the list of Points passed through the coordinates() method. But, you can skip a coordinate and show its position in the double list with the null value.
mapboxNavigation.requestRoutes(
RouteOptions.builder()
.accessToken(MAPBOX_TOKEN)
.coordinates(listOf(originPoint, destinationPoint))
.profile(RouteUrl.PROFILE_DRIVING)
.bearingsList(listOf(listOf(bearing, tolerance)))
.build()
)
Request a route including the bearing value from the device's last known Location object:
mapboxMap.locationComponent.lastKnownLocation?.let { location ->
val lastKnownBearing = location.bearing
val tolerance = 90
mapboxNavigation.requestRoutes(
RouteOptions.builder()
.accessToken(MAPBOX_TOKEN)
.coordinates(listOf(originPoint, destinationPoint))
.profile(RouteUrl.PROFILE_DRIVING)
.bearingsList(listOf(listOf(lastKnownBearing, tolerance))
.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_sideof 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()
.accessToken(MAPBOX_TOKEN)
.coordinates(listOf(originPoint, firstWaypoint, secondWaypoint, thirdWaypoint, destinationPoint))
.profile(RouteUrl.PROFILE_DRIVING)
.approachesList(listOf(DirectionsCriteria.APPROACH_UNRESTRICTED,
DirectionsCriteria.APPROACH_UNRESTRICTED, DirectionsCriteria.APPROACH_CURB, null, DirectionsCriteria.APPROACH_CURB))
.build()
)
More about route generation
Read more about route generation in the Localization guide, which walks through how to customize the language and units of measurement returned for both text and voice instructions or use the language preferences set on the device.