Navigation SDK for Android v2


There are two main kinds of offline functionality: predictive caching and offline manager (which is coming soon). Predictive caching is fully automatic and based on the driver’s behavior. It allows offline navigation around the user’s current location, the destination, and the route itself.

Predictive caching

To use predictive caching, you will need to initialize a PredictiveCacheController and, optionally, configure a radius and cache size. Once these items are configured, the Navigation SDK will automatically create caches and make them available to the user.

In order to start caching map data, provide a PredictiveCacheController instance via setMapInstance. There can only be one instance of the map caching resources at a time.

predictiveCacheController = new PredictiveCacheController(mapboxNavigation);
Map style support for predictive caching

Predictive caching only supports map styles that do not use source compositing. You may need to check your style in Mapbox Studio to make sure source compositing is turned off. Default Mapbox styles (like Mapbox Streets and Mapbox Outdoors) have compositing turned on and will not work with predictive caching by default. To use a Default Mapbox style with predictive caching:

  1. Create a new style based on the template style you prefer.
  2. Turn off compositing in your style's settings.
  3. Publish your style.
  4. Reference your style in your application.

Predictive caching only supports sources hosted with Mapbox. These sources will have a URL starts with mapbox://.


The controller and its MapboxNavigation instance have a different lifecycle than the MapboxMap instance, so make sure to call removeMapInstance whenever the MapView is destroyed to avoid leaking references or downloading unnecessary resources.


When the navigation session is finished and predictive caching is no longer needed, call onDestroy to remove all map and navigation references.

protected void onDestroy() {
if (predictiveCacheController != null) {

Configure predictive caching

When predictive caching is enabled, the Navigation SDK will create a cache of data within three configurable boundaries, each with its own default value:

  1. Radius around the user's location. Defaults to 2,000 meters. Use currentLocationRadiusInMeters to configure this value.
  2. Buffer around the route. Defaults to 500 meters. Use routeBufferRadiusInMeters to configure this value.
  3. Radius around the destination. Defaults to 5,000 meters. Use destinationLocationRadiusInMeters to configure this value.

To configure predictive caching, pass values, in meters, to any of the PredictiveCacheLocationOptions.

mapboxNavigation = new MapboxNavigation(
new NavigationOptions.Builder(this)
new PredictiveCacheLocationOptions.Builder()

When predictive caching is enabled, the Navigation SDK will automatically stop caching data when a given cache size limit is reached. The default cache size limit is 50MB, but can be configured with cacheSize with ResourceOptions.

MapboxMapOptions mapboxMapOptions = new MapboxMapOptions(this, getResources().getDisplayMetrics().density, null);
ResourceOptions resourceOptions = new ResourceOptions.Builder()
.cachePath(getFilesDir().getAbsolutePath() + "/mbx.db")
.cacheSize(100_000_000L) // 100 MB
.tileStorePath(getFilesDir().getAbsolutePath() + "/maps_tile_store/")
mapView = new MapView(this, mapboxMapOptions);
// ...
predictiveCacheController = new PredictiveCacheController(mapboxNavigation);

Estimate predictive caching data use

Data usage depends on the configured radius and on map style. For the Mapbox Streets style, cache size is:

  • Berlin, 15km radius: 136 MB maps, 42 MB navigation
  • Chicago, 15km radius: 74 MB maps, 43 MB navigation
  • London, 15km radius: 145 MB maps, 90 MB navigation
  • Atlanta, 100 miles radius: 659 MB maps, 156 MB navigation

Offline manager

Offline manager coming soon

The offline manager feature in the Navigation SDK for Android is currently in development. When released, offline manager will allow users to create offline regions ahead of time, enabling routing functionality in non-connected environments. In areas of no cellular connectivity, or on a device with no SIM card, your users can use turn-by-turn navigation and request new routes. If they go off-route, the system can reroute and keep them headed to their destination without requiring network connectivity. The offline manager moves the routing engine and the routing data from the server onto the your user’s device, so there’s no need to make HTTP API calls for routing information.