Offline maps with Mapbox Mobile

Applications using Mapbox Mobile SDKs can render maps of pre-selected regions when the device lacks network connectivity (commonly referred to as “offline maps”) by downloading in advance the styles, tiles, and other resources necessary to render the map without a data connection. The end result is a fully functional Mapbox map in any style.

Offline maps are useful for apps whose users expect to travel to unconnected areas (a hike through the mountains) or want to save on roaming charges (downloading the city of Barcelona before a vacation). Offline maps can also be used to pre-cache map assets and mitigate anticipated performance or connectivity issues created by poor cell coverage.

Offline maps are fetched from Mapbox servers in advance: the mobile SDK expects a geographic bounding box, zoom level range, and style URL (for example mapbox://styles/mapbox/light-v9). The SDK downloads the style and associated resources, reporting the download progress along the way.

Tile ceiling & limits

An app can download multiple regions for offline use, but the total offline download is capped at a maximum tile count “ceiling” across all downloaded regions. The tile ceiling is set to 6,000 tiles by default but can be raised for paid plans. Use our Tile Count Estimator to calculate the number of tiles required by your offline use case. Six thousand tiles covers a region roughly the size of Greater London within the M25 at zoom levels 0–15 or the contiguous United States at zoom levels 0–9. The size of these tiles on disk will vary according to the selected style.

There is no limit to the number of offline regions that may be created. Your Mapbox-powered application will reuse tiles and resources that are required by multiple regions, conserving network traffic and disk space.

There is also no limit to the download speed of offline regions, nor to disk space used by offline resources. The effective limits will depend on the storage capacity of the mobile device and the speed of the network to which it is connected.

Our terms of service do not allow you or an end user to redistribute offline maps downloaded from Mapbox servers.

Availability

Offline maps are available starting with Mapbox Android SDK v4.0.0 (example code, package documentation) and Mapbox iOS SDK v3.2.0 (example code, API documentation).

Offline maps are not available for Mapbox GL JS. If you use a hybrid framework, check its documentation to determine whether offline maps are supported.

Using offline maps

Create an offline region

An offline region (known as an offline pack in the iOS SDK) is a specific area available for offline interactivity. It is defined by:

  • the style URL of the map style from which you’d like to create the offline map
  • a geographic bounding box of the offline region
  • a range of zoom levels at which you plan to display that region

You can also include any application-specific data you wish. This can be used to associate a name or description with the region, for display in your application interface.

An offline region cannot be modified after creation, but it is possible to create a new region with a modified definition and remove the previous region.

Download offline resources

Before a region can be used offline, the resources necessary for that region must be downloaded. Based on the parameters you specify when creating the region, the SDK calculates all necessary resources:

  • The style itself
  • Font and icon resources
  • TileJSON for all sources
  • Raster or vector tiles covering the region

The SDK provides your application control over starting and stopping the download, and applications can register to be notified of the progress of the download and any errors that occur.

Use offline resources

Offline use is designed to be transparent and hands-free. Offline resources are used automatically by your application whenever a map is required at a location and zoom level included in an offline region.

If the device has network connectivity, the Mapbox Mobile SDK will make periodic network requests in order to revalidate cached tiles and other resources if the Cache-Control or Expires HTTP response headers indicate that revalidation is desired. If an updated resource is available, it will replace the previous version in the offline database.

List offline regions

For each region, the API will provide the definition and additional data you supplied, if any.

In the iOS SDK, the MGLOfflineStorage’s packs property contains a canonical list of valid offline packs. An active offline pack’s status can be accessed via its state and progress properties. An inactive pack’s state is initially unknown. To calculate the state or progress, register for notifications about the pack’s progress changes (or KVO change notifications about the pack’s state or progress key path), then call the pack’s -requestProgress method.

In the Android SDK, use OfflineManager.listOfflineRegions(ListOfflineRegionsCallback callback) to list all available regions.

Removing offline regions

In the iOS SDK, use -[MGLOfflineStorage removePack:withCompletionHandler:] to remove an offline pack. Removing a pack causes it to become invalid, so remove any strong references to the pack before removing it from offline storage, and avoid calling methods on the pack after it is removed, including inside the completion handler.

In the Android SDK, use OfflineRegion.delete(OfflineRegionDeleteCallback callback) to remove an offline region.

When you remove an offline region, any resources that are required by that region, but not other regions, become eligible for removal from the offline database. Because the offline database is also used as a general purpose cache for map resources, such resources may not be immediately removed if the implementation determines that they remain useful for general performance of the map.

Network data and disk space

The total size of offline resources will vary from region to region depending on:

  • The geographic extent of the region
  • The zoom level range of the region
  • Feature count and density
  • The sources, fonts, and icons used by the style
  • The size of individual tiles required by the region
  • Whether the region overlaps with previously downloaded regions

For the default Mapbox Streets style, some typical total sizes are:

  • City of Barcelona: 83 MB
  • Greater London within the M25 at zoom levels 0–15: 120 MB
  • Contiguous United States at zoom levels 0–9: 290 MB

For Mapbox Satellite:

  • City of Barcelona: 45 MB
  • Greater London within the M25 at zoom levels 0–15: 400 MB
  • Contiguous United States at zoom levels 0–9: 315 MB

Note that these sizes are rough estimates; they do not reflect size savings from automatic resource sharing between multiple regions. For the most accurate numbers, we suggest benchmarking typical regions for your application.

Limiting offline downloads to wifi connections

Mapbox Mobile SDKs will download offline resources whenever directed to do so by the application. If you wish to limit downloads to periods when the device has wifi connectivity, monitor the network connectivity type using the appropriate platform APIs and activate or deactivate the download as desired.

Offline data format

At this time, the offline database format is private. In the future, we may publicly document the format and implement Mapbox Mobile APIs for consuming pre-built databases.

Ambient caching

The iOS and Android SDKs also automatically cache tiles and other resources that are requested during normal use of the app. These resources are stored in the same database as offline resources, but unlike offline resources, they are limited to 50 MB of space. When this limit is reached, the least-recently used resources that aren’t shared by an offline region will be evicted to make room for newer resources.

Additional questions? Ask our support team or learn more about How Mapbox Works.