Offline Data

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

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.

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

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
This endpoint requires a token with offline:write, fonts:read, and style:read scope.
" \
  -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-v12",
        "min_zoom": 14,
        "max_zoom": 16,
        "include_ideographs": true
      },
     "navigation": true   
  }
}

Example response: Create a region

HTTP 204 No Content

Get pack creation status

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.

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
This endpoint requires a token with offline:read scope.
"

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

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.

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
This endpoint requires a token with offline:write, fonts:read, and style:read scope.
"

Example response: Refresh a region

HTTP 204 No Content

Get a region

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

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
This endpoint requires a token with offline:read scope.' \
--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-v12",
      "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

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

Example request: List all regions

$ curl -X GET "https://api.mapbox.com/offline-data/v1/{username}/regions?access_token=
YOUR_MAPBOX_ACCESS_TOKEN
This endpoint requires a token with offline:read scope.
" \
  --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-v12",
        "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

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.

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

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-v12",
      "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-v12",
      "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

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.

Changelog

June 25, 2020

• Added the Offline Data API in private beta.