Offline routing

Downloading offline routing packs

Access to offline routing is 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.

Offline routing in the Navigation SDK example app

The Mapbox Navigation SDK for iOS includes a basic example of integrating offline routing in the included example app. You can refer to the example app for a complete example of integrating the steps described in this guide.

Test offline routing

Offline routing is restricted to Enterprise customers, and you need to get an Enterprise API token to download offline routing tiles for arbitrary regions. If you do not have an Enterprise access token but want to try out the feature and begin your integration, you can download routing tiles and generate routes on the Faroe Islands. If you don't have an Enterprise API token and try to download offline routing tiles for any region other than the Faroe Islands, you will receive an HTTP 402 response.

Offline maps and offline routing

To use offline routing with the Navigation SDK, we recommend that you also download offline map tiles with the Maps SDK for iOS. The Maps SDK enables you to create offline maps, access a list of offline maps stored on the device, and remove offline maps that are no longer needed. Or, you can allow your users to build up a local cache of map tiles passively as they use your app, but we recommend downloading offline map tiles for the optimal user experience. For more information on how to download offline maps, see the Offline maps documentation in the Maps SDK for iOS API reference.

Integrate offline routing in your app

Integrating offline routing in your app involves a few steps:

  1. Retrieve a list of available routing tile versions. 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:).
  2. Retrieve the latest offline routing tiles for a region. The most recent version returned from the previous call should be passed into NavigationDirections.downloadTiles(in:version:session:completionHandler:). If you receive an HTTP 422 error, this means you are attempting to retrieve a region that is too large. Reduce the size of the requested region or split the request into batches.

    • Note that Directions.downloadTiles(in:version:session:completionHandler:) only downloads routing tiles, not map tiles. Routing tiles do not correspond to a particular zoom level. Instead, road geometries are included at full resolution.
  3. Unpack the routing tiles onto local storage. Use NavigationDirections.unpackTilePack(at:outputDirectoryURL:progressHandler:completionHandler:) to unpack the routing tiles you downloaded onto local storage.
  4. Initialize the offline router. Once the routing data is downloaded and unpacked onto local storage, you will be able to make routing requests with the new NavigationDirections. Initialize the offline router with a pointer to the local location of the offline routing tiles, and store it on an instance variable or property with a strong reference.

Example use

// create a directions client and store it as a property
self.navigationDirections = NavigationDirections(accessToken: "foo")
// fetch available routing tile versions
self.navigationDirections.fetchAvailableOfflineVersions { (versions, error) in
let coordinateBounds = CoordinateBounds(southWest: CLLocationCoordinate2DMake(0, 0), northEast: CLLocationCoordinate2DMake(1, 1))
// download tiles using the most recent version
self.navigationDirections.downloadTiles(in: coordinateBounds, version: versions.first, completionHandler: { (url, response, error) in
guard let url = url else {
return assert(false, "Unable to locate temporary file")
}
let outputDirectory = Bundle.mapboxCoreNavigation.suggestedTileURL(for: version)
try? FileManager.default.createDirectory(at: outputDirectory, withIntermediateDirectories: true, attributes: nil)
// unpack downloaded routing tiles
NavigationDirections.unpackTilePack(at: url, outputDirectory: outputDirectory!, progressHandler: { (totalBytes, bytesRemaining) in
// Show unpacking progress
}, completionHandler: { (result, error) in
// configure the offline router with the output directory where the tiles have been unpacked
self.navigationDirections.configureRouter(tilesURL: outputDirectory) { (numberOfTiles) in
// Completed, dismiss UI
}
})
}).resume()
}.resume()

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 run fully offline, while others may prefer to retrieve directions from the server with up-to-date traffic information when possible.

Rerouting

If a reroute happens, you will need to use the offline mechanism to calculate a new route:

  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

The device will need to store both the routing data and 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. This table shows non-compressed estimates since the data will need to be uncompressed on disk for faster routing. 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
Was this page helpful?