Offline Data

Beta support for creating offline regions

The Offline Data API endpoints for creating and interacting with offline regions are in private beta, and are subject to potential changes.

If you're interested in using the Offline Data API, please reach out to us at offline@mapbox.com.

The Offline Data API supports the creation and management of offline regions. A region is a set of one or more packs of data. Each offline pack of data defines a geographic area, as well as configuration rules about how the offline pack should be generated for that area. For example, the region "Seattle" may contain two offline packs, one for map data and one for navigation data. To download and use the packs generated for offline regions, you need to use one of the Mapbox mobile SDKs (the Maps SDK for iOS, the Navigation SDK for iOS, the Maps SDK for Android, or the Navigation SDK for Android).

Token scopes

The Offline Data API endpoints can be accessed using access tokens that include the offline:read and offline:write scopes. The token you provide to create a region or refresh a region is used to create the offline packs so it must also include the scopes necessary for this. The scopes required for each endpoint are specified in the following sections.

To improve security, you should create new tokens for use with the Offline Data API with only the required scopes and not reuse these tokens elsewhere. See our recommendations on token scope security and about creating access tokens.

Create a region

Beta support for creating offline regions

To use the Mapbox Offline Data API, you must contact offline@mapbox.com to request access. The Mapbox Offline Data API endpoints for creating and interacting with offline regions are in private beta, and are subject to potential changes.

post
/offline-data/v1/{username}/regions/{region_id}
offline:write, fonts:read, style:read

Creates or updates a region. A region is a geographical area and configuration that specifies how the offline packs are to be generated for that area. This action will start an asynchronous job that builds offline packs using the requested region configuration. A number of different factors affect the processing time of the create job, including:

  • The size of the geographical area represented by the data that is being processed. For example, a small area within a city will be processed much faster than the whole city.
  • The zoom range as defined by configuration.maps.min_zoom and configuration.maps.max_zoom. Each additional zoom level creates four times as many tiles as the previous zoom level did. As an example, a maximum zoom level of 1 produces four tiles, while a maximum zoom level of 2 produces 16 tiles. Read more about zoom levels.
  • Whether a navigation pack is requested, as specified through configuration.navigation.
Required parametersDescription
usernameThe username of the account for which a region is being created.
region_idThe identifier for the region to be created. Limited to 32 characters. The only allowed special characters are - and _.

The request body must be a JSON object that contains the following properties:

Required request body propertyDescription
configurationThe configuration describes what map and navigation data will be included in the offline packs. For more information on how to create configurations, see the region configuration examples.
Optional request body propertyDescription
nameThe name of the region. The maximum length allowed is 100 characters.
descriptionThe description of the region. The maximum length allowed is 1000 characters.

Example request: Create a region

$ curl -X POST "https://api.mapbox.com/offline-data/v1/{username}/regions/seattle-1?access_token=
YOUR MAPBOX ACCESS TOKEN
"
\ -d @seattle.json \ --header "Content-Type:application/json"

Example request body: Create a region

The seattle.json file referenced in the request above may be defined as follows:

{
  "name": "Seattle",
  "description": "Seattle Chinatown International District",
  "configuration": {
      "geography":  {
        "type": "Polygon",
        "coordinates": [
          [
            [
              -122.3295021057129,
              47.60407971765813
            ],
            [
              -122.3295021057129,
              47.60326951283489
            ],
            [
              -122.33104705810547,
              47.58625231278527
            ],
            [
              -122.3089027404785,
              47.59065184726404
            ],
            [
              -122.30615615844727,
              47.606394519436975
            ],
            [
              -122.3295021057129,
              47.60407971765813
            ]
          ]
        ]
      },
     "maps": {
        "style_url": "mapbox://styles/mapbox/streets-v11",
        "min_zoom": 14,
        "max_zoom": 16,
        "include_ideographs": true
      },
     "navigation": true   
  }
}

Example response: Create a region

HTTP 204

Get pack creation status

Beta support for creating offline regions

To use the Mapbox Offline Data API, you must contact offline@mapbox.com to request access. The Mapbox Offline Data API endpoints for creating and interacting with offline regions are in private beta, and are subject to potential changes.

get
/offline-data/v1/{username}/regions/{region_id}/status
offline:read

Retrieves the status of a pack creation or refresh job. The valid statuses for a pack creation or refresh job are processing, succeeded and failed.

Required parametersDescription
usernameThe username of the account for which a region's status is being accessed.
region_idThe unique identifier for the region.

Example request: Get the status of a pack creation or refresh job

$ curl -X GET "https://api.mapbox.com/offline-data/v1/{username}/regions/seattle-1/status?access_token=
YOUR MAPBOX ACCESS TOKEN
"

Example response: Pack creation in progress

{
  "status": "processing",
  "started": "2020-06-04T22:11:20Z"   
}

Example response: Pack creation succeeded

{
  "status": "succeeded",
  "started": "2020-06-04T22:11:20Z",
  "completed": "2020-06-04T23:10:22Z"
}

Example response: Pack creation failed

{
  "status": "failed",
  "started": "2020-06-04T22:11:20Z",
  "completed": "2020-06-04T23:10:22Z",
  "message": "Region creation failed. {reason}"
}

Refresh a region

Beta support for creating offline regions

To use the Mapbox Offline Data API, you must contact offline@mapbox.com to request access. The Mapbox Offline Data API endpoints for creating and interacting with offline regions are in private beta, and are subject to potential changes.

post
/offline-data/v1/{username}/regions/{region_id}/refresh
offline:write, fonts:read, style:read

Updates the region using the latest versions of map and navigation data as specified in the configuration. Calling this endpoint will result in an asynchronous job to create new packs. A region's pack creation status can be queried using the status endpoint.

If a region already has an active create job for the latest revision, creating it again will have no effect. When a create job completes, the pack is available for download and the region's revision number is incremented.

Mapbox-provided map data (like the mapbox-streets-v8 tileset) is updated every day. If your maps packs rely on mapbox-streets tilesets, there's no need to refresh your packs more than once per day.

Mapbox navigation data is updated every one to seven days.

Required parametersDescription
usernameThe username of the account for which a region is being refreshed.
region_idThe unique identifier for the region to be refreshed.

Example request: Refresh a region

$ curl -X POST "https://api.mapbox.com/offline-data/v1/{username}/regions/seattle-1/refresh?access_token=
YOUR MAPBOX ACCESS TOKEN
"

Example response: Refresh a region

HTTP 204

Get a region

Beta support for creating offline regions

To use the Mapbox Offline Data API, you must contact offline@mapbox.com to request access. The Mapbox Offline Data API endpoints for creating and interacting with offline regions are in private beta, and are subject to potential changes.

get
/offline-data/v1/{username}/regions/{region_id}
offline:read

Gets the latest revision of a region. The revision is the version of data included in the maps and navigation packs for a region.

Required parametersDescription
usernameThe username of the account for which a region is being accessed.
region_idThe unique identifier for the region being accessed.

Example request: Get a region

$ curl -X GET 'https://api.mapbox.com/offline-data/v1/{username}/regions/seattle-1?access_token=
YOUR MAPBOX ACCESS TOKEN
' \ --header "Content-Type:application/json"

Example response: Get a region

{
  "name": "seattle-1",
  "revision": 7,
  "description": "Seattle Chinatown International District",
  "last_updated": "2020-05-11T19:17:32.856Z",
  "configuration": {
    "geography": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              -122.3295021057129,
              47.60407971765813
            ],
            [
              -122.3295021057129,
              47.60326951283489
            ],
            [
              -122.33104705810547,
              47.58625231278527
            ],
            [
              -122.3089027404785,
              47.59065184726404
            ],
            [
              -122.30615615844727,
              47.606394519436975
            ],
            [
              -122.3295021057129,
              47.60407971765813
            ]
          ]
        ]
    },
    "maps": {
      "style_url": "mapbox://styles/mapbox/streets-v11",
      "min_zoom": 14,
      "max_zoom": 16,
      "include_ideographs": true
    },
    "navigation": true
  },
  "packs": [
    {
      "domain": "maps",
      "format": 1,
      "url": "mapbox://offline-data/${username}/regions/seattle-1/7/maps/1",
      "md5_checksum": "ede5bea95f9472011c86caa173b993ba",
      "size": 1234123,
      "data_version": "2020-05-11T19:17:32.856Z"
    },
    {
      "domain": "navigation",
      "format": 1,
      "url": "mapbox://offline-data/${username}/regions/seattle-1/7/navigation/1",
      "md5_checksum": "7c8f873e9bd500daaf0fe42bcb3c6c4e",
      "size": 1234567,
      "data_version": "2020_05-03-00_00_00"
    }
  ]
}

List all regions

Beta support for creating offline regions

To use the Mapbox Offline Data API, you must contact offline@mapbox.com to request access. The Mapbox Offline Data API endpoints for creating and interacting with offline regions are in private beta, and are subject to potential changes.

get
/offline-data/v1/{username}/regions
offline:read

Lists the latest revision of all regions. The revision is the version of data included in the maps and navigation packs for a region.

Required parametersDescription
usernameThe Mapbox account for which regions are being listed.

Example request: List all regions

$ curl -X GET "https://api.mapbox.com/offline-data/v1/{username}/regions?access_token=
YOUR MAPBOX ACCESS TOKEN
"
\ --header "Content-Type:application/json"

Example response: List all regions

{
  "chicago-1": {
    "name": "Chicago : Warehouse 1",
    "description": "South Chicago including Oak Lawn",
    "last_updated": "2020-04-10T23:28:56.782Z",
    "revision": 7,
    "packs": [
      {
        "domain": "maps",
        "format": 1,
        "url": "mapbox://offline-data/{username}/regions/chicago-1/7/maps/1",
        "md5_checksum": "99fca024a38ce9806ddd1ca92fe324t9",
        "size": 300000000,
        "data_version": "2020-04-10T12:00:00.000Z"
      },
      {
        "domain": "navigation",
        "format": 1,
        "url": "mapbox://offline-data/{username}/regions/chicago-1/7/navigation/1",
        "md5_checksum": "99fca024a38ce9806ddd1ca92fe324t1",
        "size": 400000000,
        "data_version": "2020_04_10-03_00_00"
      }
    ],
    "configuration": {
      "geography": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              -87.79106140136719,
              41.869049503223515
            ],
            [
              -87.80616760253905,
              41.7615809118484
            ],
            [
              -87.70317077636719,
              41.78513707423634
            ],
            [
              -87.72239685058594,
              41.91147545749747
            ],
            [
              -87.79106140136719,
              41.869049503223515
            ]
          ]
        ]
      },
      "maps": {
        "style_url": "mapbox://styles/{username}/ck62ax4m90iwb1iqgwonb6151",
        "min_zoom": 8,
        "max_zoom": 12,
        "include_ideographs": true
      },
      "navigation": "true"
    }
  },
  "seattle-1": {
    "name": "Seattle",
    "description": "Lower Manhattan",
    "last_updated": "2020-02-02T23:28:56.782Z",
    "revision": 492,
    "packs": [
      {
        "domain": "maps",
        "format": 1,
        "url": "mapbox://offline-data/{username}/regions/seattle-1/492/maps/1",
        "md5_checksum": "1bfa485b14a9cfd27c05edb1a41c9a62",
        "size": 2654208,
        "data_version": "2020-02-02T23:00:00.000Z"
      },
      {
        "domain": "navigation",
        "format": 1,
        "url": "mapbox://offline-data/{username}/regions/seattle-1/492/navigation/1",
        "md5_checksum": "2bdc937954f2814e925df33261510f45",
        "size": 37580800,
        "data_version": "2020_02_02-03_00_00"
      }
    ],
    "configuration": {
      "geography": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              -122.3295021057129,
              47.60407971765813
            ],
            [
              -122.3295021057129,
              47.60326951283489
            ],
            [
              -122.33104705810547,
              47.58625231278527
            ],
            [
              -122.3089027404785,
              47.59065184726404
            ],
            [
              -122.30615615844727,
              47.606394519436975
            ],
            [
              -122.3295021057129,
              47.60407971765813
            ]
          ]
        ]
      },
      "maps": {
        "style_url": "mapbox://styles/mapbox/streets-v11",
        "min_zoom": 15,
        "max_zoom": 15,
        "include_ideographs": true
      },
      "navigation": "true"
    }
  }
}

Region configuration

Current version: 1

A region configuration is a JSON document composed of configuration options that tell the Offline Data API how to build offline packs for maps and navigation data.

The region configuration is used for creating and refreshing a region and it must be constructed according to the rules described below.

Configuration top-level fields

Required fieldsDescriptionData type
configurationA JSON Object that contains configuration.geography and one or both of configuration.maps and configuration.navigation.Object
configuration.geographyA GeoJSON Polygon that defines the area of interest for which offline packs must be created.Object
configuration.mapsA JSON Object that defines what the maps pack must contain.Object
configuration.navigationA key that defines if a navigation pack should be created.Boolean
Include at least one of maps or navigation in the region configuration

A region configuration must contain at least one of configuration.maps and configuration.navigation.

Optional fieldsDescriptionData type
nameThe region's name. The maximum allowed length is 100 characters.String
descriptionA description for the region. The maximum allowed length is 1000 characters.String

The geometry of a region (as specified in configuration.geography) is defined as a GeoJSON Polygon. For example:

 {
   "type":"Polygon",
   "coordinates":[
      [
         [
            -87.79106140136719,
            41.869049503223515
         ],
         [
            -87.80616760253905,
            41.7615809118484
         ],
         [
            -87.70317077636719,
            41.78513707423634
         ],
         [
            -87.72239685058594,
            41.91147545749747
         ],
         [
            -87.79106140136719,
            41.869049503223515
         ]
      ]
   ]
}

To build a maps pack, the region configuration must contain a maps object with the attributes described below.

Required maps attributesDescriptionData type
style_urlThe map style to be used for creating the offline maps pack. The format should follow the Mapbox Style URL format described in the Mapbox Styles API documentation.String
min_zoomThe minimum zoom level at which to tile map data. Must be less than or equal to max_zoom and between 0 to 16.Integer
max_zoomThe maximum zoom level at which to tile map data. Must be greater than or equal to min_zoom and between 1 to 16.Integer
include_ideographsWhether the offline pack should include font ranges containing Chinese/Japanese/Korean (CJK) ideographs and precomposed Hangul Syllables. Including ideographs can increase the offline pack size significantly so we recommend disabling this unless needed. See the Mapbox GL JS Local ideographs example for reference. Allowed values are true and false.Boolean

To build a navigation pack, the region configuration must contain a navigation object as described below.

Required navigation attributeDescriptionData type
navigationA boolean flag indicating whether the region must include navigation data. true or false values are allowed. The default is false.Boolean

Example configuration: A region that only contains a maps pack

{
  "name": "New York City",
  "description": "Central Park East",
  "configuration": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              -73.95996093749999,
              40.8027651305852
            ],
            [
              -73.9738655090332,
              40.78671542763972
            ],
            [
              -73.95566940307616,
              40.779891504181464
            ],
            [
              -73.9438247680664,
              40.79672258044242
            ],
            [
              -73.95996093749999,
              40.8027651305852
            ]
          ]
        ]
      },
    "maps": {
      "style_url": "mapbox://styles/mapbox/streets-v11",
      "min_zoom": 12,
      "max_zoom": 16,
      "include_ideographs": true
    },
    "navigation": false
}

Example configuration: A region that contains both maps and navigation packs

{
  "name": "Seattle",
  "description": "Seattle Chinatown International District",
  "configuration": {
    "geography": {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Polygon",
        "coordinates": [
            [
              -122.3295021057129,
              47.60407971765813
            ],
            [
              -122.3295021057129,
              47.60326951283489
            ],
            [
              -122.33104705810547,
              47.58625231278527
            ],
            [
              -122.3089027404785,
              47.59065184726404
            ],
            [
              -122.30615615844727,
              47.606394519436975
            ],
            [
              -122.3295021057129,
              47.60407971765813
            ]
          ]
      }
    },
    "maps": {
      "style_url": "mapbox://styles/mapbox/streets-v11",
      "min_zoom": 12,
      "max_zoom": 16,
      "include_ideographs": true
    },
    "navigation": true
  }
}

Example configuration: A region that only contains a navigation pack

{
  "name": "seattle-1",
  "description": "Seattle Chinatown International District",
  "configuration": {
    "geography": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              -122.3295021057129,
              47.60407971765813
            ],
            [
              -122.3295021057129,
              47.60326951283489
            ],
            [
              -122.33104705810547,
              47.58625231278527
            ],
            [
              -122.3089027404785,
              47.59065184726404
            ],
            [
              -122.30615615844727,
              47.606394519436975
            ],
            [
              -122.3295021057129,
              47.60407971765813
            ]
          ]
        ]
      },
    "navigation": true
  }
}

Offline Data API errors

Response body messageHTTP status codeDescription
POST body is misformatted: {reason}400The region configuration is incorrect.

When the response body message contains Region is partially within Japan. Offline data regions with navigation must be outside of, or entirely within, Japan it indicates that the requested configuration.geography must not partially overlap with Japan and a request with a new geography must be submitted.
Not Authorized - No Token401No access token was used in the request.
Not Authorized - Invalid Token401Check the access token that you used in the request.
Contact offline@mapbox.com for access403Your account does not have access to the Mapbox Offline Data API private beta. Contact offline@mapbox.com to request access.

Offline Data API restrictions and limits

  • You can create up to 1000 regions.
  • You can update each region once per hour. Depending on the size of your regions, it may take several minutes for your offline packs to become available for download.
  • A region's map pack can contain at the most 100,000 tiles. You can use a tool like the Offline Estimator to check whether your region contains fewer than 100,000 tiles.
  • The maximum zoom level (see max_zoom under region configuration examples) allowed is Z16.