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. This guide provides an explanation for why this happens and describes some techniques for manually adjusting the zoom extent of your tilesets.

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 where the details would not even be noticed, making it load faster.

There’s an upper limit on the amount of data that can exist in a single vector tile. 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 or 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 maximum and minimum zoom levels at which tiles should be rendered.

For raster tilesets, the minzoom and maxzoom levels are set based on the resolution of the uploaded image. Higher resolution images will result in the tileset rendering at more zoom levels.

Note: 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.

Create tiles with Tippecanoe

Tippecanoe is a command-line utility for converting complex data into vector tiles. Tippecanoe is powerful, but requires some familiarity with the command line. To set minimum and maximum zoom levels using Tippecanoe:

  1. On Mac OS, install Homebrew, then run brew install tippecanoe.
  2. If you want 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

For more details on installing and using Tippecanoe to transform your data, read the Manage large data files for Mapbox Studio with Tippecanoe guide.

Upload with Mapbox Studio Classic

You can manually set minzoom and maxzoom levels with Mapbox Studio Classic, our legacy desktop design tool:

  1. Download the latest version of Mapbox Studio Classic.
  2. In Mapbox Studio Classic, click Styles & Sources > New style or source > Create custom vector tiles to create a new source.
  3. Click New layer, browse to find and the file you want to upload, then click the Save as button to save the source.
  4. Click Settings and set the minzoom and maxzoom of your data. Use caution because this this step will create vector tiles for each zoom level and can be costly with large complex data files. See troubleshooting uploads for more information.
  5. Save your changes, then click Upload to Mapbox. Your source will appear on the Tileset list page of Mapbox Studio.

You cannot set maxzoom beyond 16 in Mapbox Studio Classic. If you do want your maxzoom to be more than 16:

  1. Exit out of Mapbox Studio Classic.
  2. In a text editor, open the data.yml file found in your source’s .tm2source folder. Save and close the file.
  3. Re-open Mapbox Studio Classic and upload your tileset.

For more details on how to optimize massive data files and convert them to performant vector tiles, read the Uploads guide.