Offline routing

help
Downloading offline routing packs

Offline routing pack downloads are restricted to Mapbox Enterprise customers. If you're interested in moving to an Enterprise plan, contact us!

Mapbox offline navigation provides routing functionality from the Navigation SDK in non-connected environments. In areas of no cellular connectivity, or on a device with no SIM card, end 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. Offline routing moves the routing engine and the routing data from the server onto the end user’s device, so there’s no need to make HTTP API calls for routing information.

In order to implement offline routing in your own app, you will need to:

  1. Add the offline dependency to your application.
  2. Update your application to use NavigationDirections.downloadTiles(in:version:session:completionHandler:), which allows the app to download the data needed for offline routing.
  3. Make routing requests with the new NavigationDirections.

These steps are described in this guide, along with example code.

Download the routing data

To use offline routing, your application will need to download routing data from Mapbox. (Note that only Enterprise customers can download offline routing packs.) This routing data can be downloaded via the SDK by using the NavigationDirections.fetchAvailableOfflineVersions(completionHandler:).

Preferably, the most recent version returned from the previous call should be passed into NavigationDirections.downloadTiles(in:version:session:completionHandler:), followed by NavigationDirections.unpackTilePack(at:outputDirectoryURL:progressHandler:completionHandler:).

NavigationDirections.shared.fetchAvailableOfflineVersions { (versions, error) in
// Grab the most recent version and pass to downloadTiles
NavigationDirections.shared.downloadTiles(in: coordinateBounds, version: version, completionHandler: { (url, response, error) in
guard let url = url else {
return assert(false, "Unable to locate temporary file")
}
let outputDirectory = Bundle.mapboxCoreNavigation.suggestedTilePath(for: version)
outputDirectory?.ensureDirectoryExists()
NavigationDirections.unpackTilePack(at: url, outputDirectory: outputDirectory!, progressHandler: { (totalBytes, bytesRemaining) in
// Show unpacking progress
}, completionHandler: { (result, error) in
// Completed, dismiss UI
})
}).resume()
}.resume()

Make routing requests

Once the routing data is downloaded, you will be able to make routing requests with the new NavigationDirections.

let tilePath = Bundle.mapboxCoreNavigation.suggestedTilePath(for: "{version}")
let directions = NavigationDirections(accessToken: "foo")
directions.configureRouter(tilesURL: tilePathURL) { (numberOfTiles) in
// Verify that numberOfTiles > 0
}

Depending on your use case, it may be appropriate to pass true or false into the call to NavigationDirections.calculate(_:offline:completionHandler:). For example, it may be preferable for some applications to operate fully offline, while others may prefer to retrieve directions from the server with up-to-date traffic information when possible.

Rerouting

In the event of a reroute, you will need to use the offline mechanism to calculate a new route.

In order to achieve this:

  1. Implement NavigationViewControllerDelegate.navigationViewController(_:shouldRerouteFrom:) or MapboxNavigationService.router(_:shouldRerouteFrom:).
  2. Return false.
  3. Start calculating the route offline using directions.calculate(options, offline:true) and update the route accordingly.

Example use

navigationViewController.navigationService.route = newRoute

When the SDK detects that the user has diverged from the route, the offline navigator will offer a new route to their original destination. Having routing data on the client device means new routes are generated without having to go back to the server to calculate and retrieve a route. As long as the user is still within the boundaries of the offline routing data they can trigger a re-route event or request a new route anywhere within the dataset.

Estimated local storage and memory benchmarks

In addition to the storage required by the routing data, the device will also need to to store the map data needed for visual display. For more information on managing offline download size, see the Mobile offline troubleshooting guide.

Local storage estimates

The road network density of given geographic areas varies widely, but we have provided a list of benchmark estimates below, created via a bounding box encompassing the region listed. As the data needs to be uncompressed on disk for faster routing, non-compressed estimates are shown. Download sizes will be smaller after compression.

Example region sizeRouting dataMap data (z1-7,12)
Washington, DC41MB120B
San Francisco (city and county)57MB20MB
California377MB400MB
New York (state)475MB300MB
USA (minus HI and AK)3.8GB5GB
United Kingdom663MB290MB

Memory estimates

For a typical route calculation in a geographic area, the amount of memory needed will vary depending on the complexity of route generation in that area. The following estimates were created using data from some of the largest cities to give a worst-case value.

Region sizeRAM needed
San Francisco (city and county)100MB
California150MB
USA (minus HI and AK)250MB