Plan Offline Routes

Use this section of guide to configure the routing strategy and send route requests through NBNavigation so that the application can use online routing, offline routing, or a fallback strategy based on data availability and network conditions.

Set the Routing Strategy

1
NBNavigation.setRuntimeConfig(
2
    RouteMode.SMART,
3
    NBNavigation.getDownloadNetworkPolicy()
4
)

Mode	Behavior
`SMART`	Selects a source based on network connectivity and local offline-data availability
`ONLINE_PREFERRED`	Tries online routing first, then offline routing after a failure or timeout
`OFFLINE_PREFERRED`	Tries offline routing first, then online routing after a failure or timeout
`ONLINE_ONLY`	Uses only the online routing service
`OFFLINE_ONLY`	Uses only local/downloaded routing data

ONLINE_ONLY is the default route mode. Applications that require offline routing must explicitly switch to SMART by calling setRuntimeConfig(RouteMode.SMART, NBNavigation.getDownloadNetworkPolicy()). setRuntimeConfig() updates both the route mode and the process-wide download network policy, so pass the current policy when changing only the route mode.

Runtime configuration resets when the application process restarts and must be reapplied during startup. An Android network is considered available only when it has both the “INTERNET” and “VALIDATED” capabilities. Use OFFLINE_ONLY for offline acceptance testing or when online route requests are explicitly prohibited.

Send a Route Request

1
NBNavigation.fetchRoute(
2
    origin,
3
    destination,
4
    "en",
5
    object : NextbillionRoutingCallback {
6
        override fun onRoutingReady(routes: List<DirectionsRoute>) {
7
            routes.firstOrNull()?.let(::startNavigation)
8
        }
9
 
10
        override fun onRoutingError(throwable: Throwable) {
11
            showOfflineError("Route request failed", throwable)
12
        }
13
    }
14
)

The simplified overload uses car, metric units, the current departure time, and requests up to two alternative routes. Use RouteRequestParams for other travel modes, waypoints, avoidances, or vehicle parameters. The origin, destination, and roads traversed by an offline route must all be within downloaded road-network coverage.

For both online and offline requests, the success callback returns a standard DirectionsRoute. The existing route-preview and NavigationView flows do not need source-specific branches.

Calculating a route and starting live navigation are separate steps. Before starting real navigation, request the required runtime permissions and verify that every route region required by the trip has complete road-network data.

Determine the Actual Route Source

1
NBNavigation.fetchRoute(
2
    params,
3
    object : NBNavigation.SourceAwareRoutingCallback {
4
        override fun onRoutingReady(
5
            routes: List<DirectionsRoute>,
6
            source: RouteSource
7
        ) {
8
            showRouteSource(source)
9
            routes.firstOrNull()?.let(::startNavigation)
10
        }
11
 
12
        override fun onRoutingError(throwable: Throwable) {
13
            showOfflineError("Route request failed", throwable)
14
        }
15
    }
16
)