Troubleshooting: Adjust the zoom extent of your tileset

When you upload your data to Mapbox Studio, it is rendered into a tileset. After the upload, two changes can happen to your data: (1) it is simplified and (2) it is not rendered at all zoom levels. This doc explains why this happens and describes techniques for manually adjusting the zoom extent of your tilesets.

Why this happens

Data simplification and zoom extent make the map load faster and look good.

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.

Vector tilesets have limits on the amount of data that can exist in a single tile. To render the tileset at the maximum number of zoom levels possible, there needs to be less data per tile. Simplifying complex vector features is one way to lower the amount of data in each tile.

Minimum and maximum zoom levels

Another way we make sure the resulting tileset comes in under the size limit is to only render it at select zoom levels. Zoom extent prevents lower-resolution data showing at high zoom levels as well as prevent detailed data from cluttering the map at lower zoom levels. Tiles are only rendered at zoom levels where the data density allows for each tile to be under its size limit.

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:

1. Create tiles with Tippecanoe

Tippecanoe is a command-line utility for converting complex data into vector tiles that gives you a lot of control. 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 minimum zoom to be 2 and maximum zoom to be 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.

2. 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 Save as button to save the source.
  4. Click Settings and set the minzoom and maxzoom of your data. Use caution because this is creating 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. 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. Then re-open Mapbox Studio Classic, and upload again.

For more details on how to optimize massive data files and convert them to performant vector tiles, read the Convert thousands of points into vector tiles guide.

Additional questions? Ask our support team or learn more about How Mapbox Works.