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.

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.

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:

  1. Download the data you want to work with using Overpass Turbo.
  2. Install Tippecanoe using the command line. First, install Homebrew, then run brew install tippecanoe.
  3. 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
  1. 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, 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 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 step will create vector tiles for each zoom level and can be costly with large and 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 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.

Was this page helpful?