Adjust the zoom extent of your tileset
When you upload data to your Mapbox account as a tileset, you may notice that your data has been simplified or that it is not rendered at all zoom levels. The Mapbox Streets source data is also limited to specific zoom levels. This guide provides an explanation for why this happens. It also describes some techniques for manually adjusting the zoom extent of your tilesets and for adding your own sources with custom zoom levels.
Why this happens
Data simplification and zoom level limiting make your map load faster and limit the file size of the resulting tileset.
Vector data simplification
Simplification at lower zoom levels reduces complexity on the map in places where the details would not even be noticed. This simplification makes the map load more efficiently.
The amount of data that can exist in a single vector tile has an upper size limit. By simplifying complex vector features during the upload process, we make sure each tile in your vector tileset falls below this upper limit and will display correctly on your maps.
Minimum and maximum zoom levels
Sometimes, it is not possible to display data legibly at a given zoom level. For example, a dense series of topographic lines would turn into a jumble of features when viewing the map at a low zoom level. Conversely, lower-resolution data would appear too coarse at high zoom levels. To prevent both of these potential issues, the Mapbox Uploads API analyzes your data and automatically determines the maximum and minimum zoom levels at which tiles should be rendered.
For raster tilesets, the uploaded image resolution sets the minzoom and maxzoom levels. Higher resolution images will result in the tileset rendering at more zoom levels.
Regardless of maximum zoom level, data can be overzoomed and visualized to zoom 22.
Adjust the zoom extent of your tileset
There are two techniques for adjusting the zoom extent of your tilesets:
- Use Mapbox Tiling Service (MTS) to create a tileset using a recipe that specifies the zoom extent.
- Use Tippecanoe to transform the data to MBTiles before uploading it to your Mapbox account.
It is not possible to adjust the zoom extent of tilesets created by uploading raw geospatial data to your Mapbox account using Mapbox Studio or the Uploads API. You will need to process the data into tiles before uploading to your Mapbox account using either Mapbox Tiling Service or Tippecanoe as described below.
Create a tileset using an MTS recipe
You can use Mapbox Tiling Service (MTS) to set or update a tileset's zoom extent in its tileset recipe. You can do this using the Tilesets CLI or by using MTS directly. For more information on zoom level configuration in tileset recipes, see the Tileset recipe reference and the Basic recipe using zoom levels example.
Transform data with Tippecanoe
Much of the data behind Mapbox Streets comes from OpenStreetMap. You can download this data using Overpass Turbo and adjust its zoom level options with Tippecanoe, a command-line utility for converting complex data into vector tiles. To download, prepare, and upload data from OpenStreetMap to your Mapbox account:
- Download the data you want to work with using Overpass Turbo.
- Install Tippecanoe using the command line. First, install Homebrew, then run
brew install tippecanoe. - Create your tileset using Tippecanoe's zoom level options. For example, to set the minimum zoom to 2 and maximum zoom to 7, the command would look something like this:
tippecanoe -o geography_regions.mbtiles -Z 2 -z 7 Documents/geography_regions.geojson
- Upload the MBTiles file you created in step 3 to your Mapbox account as a tileset.
For more details on installing and using Tippecanoe to transform your data, see the Tippecanoe documentation.