Offline maps

Applications built with the Mapbox Android SDK or Mapbox iOS SDK can download maps of pre-selected regions for use when the device lacks network connectivity.

Offline maps are useful for apps whose users expect to travel through areas with limited data connectivity or who want to save on cellular roaming charges while traveling abroad.

Offline caching

To create an offline cache, the Mapbox iOS and Android SDKs need:

  • A geographic bounding box.
  • A zoom level range.
  • A style URL (for example mapbox://styles/mapbox/light-v9).

If the application provides each of the above requirements, the Mapbox iOS or Android SDK can request all the required resources from Mapbox’s servers and will store them in a database on the device. Downloaded resources include:

Ambient caching

The Mapbox 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.

Working with offline caches

With the Mapbox iOS and Android SDKs, you can create offline regions, access a list of offline regions stored on the device, and remove offline regions that are no longer needed. When managing your offline regions, keep in mind:

  • An offline region cannot be modified after creation, but it is possible to create a new region with a modified definition and remove the existing region.
  • When you remove an offline region, resources that are shared with other offline regions will not be removed.

For more information on working with offline caches, check out the Mapbox Android and iOS SDK API documentation.

Updating offline resources

If the device has network connectivity, the Mapbox Android or iOS SDK will make periodic network requests to revalidate cached tiles and other resources if the Cache-Control or Expires HTTP response headers have expired. If an updated resource is available, it will replace the older version in the offline database.

When the SDK automatically updates offline map tiles, the offline region is not re-download from scratch. The offline tile update process is the same process as with regular map tiles: The map tile’s only downloaded if there’s a new version of that tile.

Tile ceiling & limits

An app can download multiple regions for offline use, but the total offline download is capped at a maximum tile count (or “ceiling”) across all downloaded regions. The tile ceiling is set to 6,000 tiles by default, but can be raised with an enterprise plan. The total tile count in an offline region is the sum of the tiles downloaded from each source in your style. For example, if you would like to download a region covering 10 tiles and your style includes one vector tile source and one raster tile source (see sample JSON below), the resulting tile count would be 20.

"sources": {
  "mapbox-streets": {
    "url": "mapbox://mapbox.mapbox-streets-v7",
    "type": "vector"
  },
  "mapbox-satellite": {
    "url": "mapbox://mapbox.satellite",
    "type": "raster",
    "tileSize": 256
  }
}

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.

To estimate the number of tiles needed to download a region offline, check out our offline tile count estimator. Please note that this only generates an estimate of the number of tiles needed to load a defined region offline. The size of the download will vary according to the location being downloaded and the style being used in your application.

Offline tile count estimator

You can create an unlimited number of offline regions. Your Mapbox-powered application will reuse tiles and resources that are required by multiple regions, conserving network traffic and disk space.

The Android and iOS SDKs do not limit the download speed of offline regions, nor do they limit the amount of disk space that may be 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.

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

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 existing 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 account for size savings from automatic resource sharing between multiple regions. We suggest benchmarking typical regions for your application to get the best estimate.

The Maps SDK downloads tiles when any connection is available, including over regular mobile data (2G, 3G, 4G, etc.). Because only individual highly-optimized tiles download, there’s no risk of the user incurring an unexpected 100MB download by opening the map in a region that’s already downloaded. That is, of course, unless the user is browsing 100MB worth of tiles.

The Mapbox iOS and Android SDKs do not include any built-in controls to prevent your users from downloading large offline resources over a cellular network. If you would like to provide your users with this option, we recommend tracking your app’s network connectivity type using the your platform of choice’s APIs, then activating or deactivating the download as desired.