Vector MTS
What is Vector MTS?
Mapbox Tiling Service (MTS) is a tool for creating vector tilesets. MTS allows the processing of massive sets of data into custom vector tilesets, continuously updating the maps as the data changes. It creates and updates data using distributed and parallelized processing, meaning data is processed much more quickly than is possible with a standard, single server setup with comparable tools. Map styles are more performant if they reference fewer tilesets. MTS has the flexibility of organizing data into multiple vector layers that are still ultimately part of the same tileset. This allows more data on the map, without sacrificing the same data organization of having multiple tilesets.
Create a new tileset with MTS
The core workflow for creating a new tileset with MTS is:
Style an MTS-created tileset
Once you have created a new tileset with MTS, you can view and style it in Mapbox Studio:
If you want to style your data using a Mapbox SDK like Mapbox GL JS or one of our mobile SDKs, the MTS documentation has detailed examples that you can use to get started. The basic recipe example is a good one to start with.
Update a tileset with MTS
You can update an existing tileset's tiles using MTS. These update steps can be repeated indefinitely for the same tileset:
--replace flag in the upload-source command, which automatically deletes the original tileset source and creates a new tileset source with your updated geographic source data. You can also use the Replace a tileset source endpoint to replace the original data. If you use the Add to an existing tileset source endpoint without deleting the original tileset source, it will append a new tileset source file to your existing tileset source instead of overwriting the original tileset source.You can also update a tileset's recipe and metadata using MTS:
- Update a tileset’s recipe using the Update a tileset’s recipe MTS endpoint. You can update the recipe to use a new tileset source if you wish.
- Update a tileset's metadata using the Update tileset information MTS endpoint.
Precision levels and square kilometers
Web maps distribute their spatial data as "tiles", which are small squares of geographic data meant to load only when required by the visual parts of the map. Every single tile displays a particular place in the world, and is intended to always represent that part of the world.
Map tiles are organized into zoom levels (abbreviated "Z"), which are loaded as you zoom in and out of the map. The greater the extent of the view, the lower the zoom level. Think of zoom levels as a pyramid of tiles, as you zoom in (increase the zoom level) the earth requires more and more tiles. At zoom 0 (world view), all your data exists in a single tile. As you zoom into country, state, county, and street level views, your data disperses across more and more tiles. The image below shows how the number of tiles increases quadratically with each zoom level.
Realistically, few maps need to zoom beyond 16, or 22 if they feature detail work at centimeter precision. Each zoom level is useful for presenting some data from the world, but not all data. For example, you would want to show continental boundaries at zoom zero, but you probably don’t need roads or city labels. At zoom 10 you may want to show county or city labels, but not alleyways. At zoom 16 you want to show the location of candy stores, but not country boundaries. As you increase the zoom level, the granularity of data presented is much more fine.
| zoom 1 | zoom 5 | zoom 11 | zoom 16 | zoom 18 |
|---|---|---|---|---|
| continents, country borders, state + province labels | lakes, landuse, major roads, city labels | landuse, parks, all roads, major points of interest labels | block level, restaurant locations, building outlines | bench locations, entrances and exits |
| ~127,408,003 sq km per tile | ~497,688 sq km per tile | ~122 sq km per tile | .12 sq km per tile | .01 sq km per tile |
| 4 tiles | 1,024 tiles | 4,194,304 tiles | 4,294,967,296 tiles | 68,719,476,736 tiles |
Each tile has a limit of 1250 kilobytes. At zoom 0, there is a single tile, meaning that all data rendered at this zoom level must fit within the 1250 KB limit. This also means that at zoom 0, a single tile contains the square kilometers of the entire world, approximately 509,632,010 square kilometers. At zoom level 11, there are 4,194,304 tiles, meaning that each tile contains approximately 122 square kilometers. Thus at higher zoom levels, the square kilometers occupied by each tile changes dramatically and the type of data you need to display as those varying perspectives changes as well.
Source data and varying maxzooms
In the examples below, you can toggle each layer of a tileset to see the effects of tiling the same data at varying maxzooms. The recipe used to generate each map is provided below as well.
Points
Multilayer tilesets
Below is a map of state capital point data with various maxzooms. If you uncheck layer 14, and then zoom in past zoom 10, you'll see the layer with a maxzoom of 10 disappear. This is because each layer only displays data up to its maxzoom value. Once you reach the highest maxzoom of the tileset (zoom 14), the data in that layer will be overzoomed, so it can be viewed at zooms 14+. Overzooming scales your data from the tiles at your maxzoom, so there is precision loss that happens with this functionality. The multiple tileset section below provides a visual of this precision loss depending on your maxzoom.
Recipe Used
{
"version": 1,
"layers": {
"layer10": {
"source": "mapbox://tileset-source/{username}/capitals",
"minzoom": 0,
"maxzoom": 10
},
"layer14": {
"source": "mapbox://tileset-source/{username}/capitals",
"minzoom": 0,
"maxzoom": 14
}
}
}
Multiple tilesets
The map below displays the same data source tiled with the recipe above, except each layer is an individual tileset instead of a multilayer tileset. Each individual tileset is overzoomed beyond its maxzoom so data is visible on the map. Yet, since the tileset with a maxzoom of zoom 10 only contains data at a country level perspective, as you zoom in to the state, city, or street level views, that data becomes increasingly imprecise. The tileset with a maxzoom of zoom 14 is more precise as you zoom in because tiles are available at this higher, city level perspective. It's important to note that data is still visible to users at all zoom levels.
Lines
Multilayer tilesets
Below is a map of major highways with various maxzooms. If you uncheck layer 14, and then zoom in past zoom 10, you'll see the layer with a maxzoom of 10 disappear. This is because each layer only displays data up to its maxzoom value. Once you reach the highest maxzoom of the tileset (zoom 14, the data in that layer will be overzoomed, so it can be viewed at zooms 14+. Overzooming scales your data from the tiles at your maxzoom, so there is precision loss that happens with this functionality. The multiple tileset section below provides a visual of this precision loss depending on your maxzoom.
This example also highlights randomized feature dropping at zoom levels 0 and 1. The data density per tile is high at those zoom levels, causing the data to be dropped unpredictably on each layer to adhere to the 1250 KB limit. To make sure data is dropped in a consistent manner, you would need to add the order filter to the feature ID attribute, or remove unneeded properties per feature using allowed_output to reduce the metadata per feature.
Recipe Used
{
"version": 1,
"layers": {
"layer10": {
"source": "mapbox://tileset-source/examples/natural-earth-roads",
"minzoom": 0,
"maxzoom": 10,
"features": {
"attributes": {
"set": {
"quality": [
"match",
[ "get", "type" ],
"Ferry Route", 0,
"Major Highway", 1,
"Secondary Highway", 2,
3
]
}
},
"filter": [ "<=", [ "get", "quality" ], 2 ],
"bbox": [ -125.0011, 24.9493, -66.9326, 49.5904 ]
}
},
"layer14": {
"source": "mapbox://tileset-source/examples/natural-earth-roads",
"minzoom": 0,
"maxzoom": 14,
"features": {
"attributes": {
"set": {
"quality": [
"match",
[ "get", "type" ],
"Ferry Route", 0,
"Major Highway", 1,
"Secondary Highway", 2,
3
]
}
},
"filter": [ "<=", [ "get", "quality" ], 2 ],
"bbox": [ -125.0011, 24.9493, -66.9326, 49.5904 ]
}
}
}
}
Multiple tilesets
The map below displays the same data source tiled with the recipe above, except each layer is an individual tileset instead of a multilayer tileset. Each individual tileset is overzoomed beyond its maxzoom so data is visible on the map. Yet, since the tileset with a maxzoom of zoom 10 only contains data at a country level perspective, as you zoom in to the state, city, or street level views, that data becomes increasingly imprecise. The tileset with a maxzoom of zoom 14 is more precise as you zoom in because tiles are available at this higher, city level perspective. It's important to note that data is still visible to users at all zoom levels.
Polygons
Multilayer tilesets
Below is a map of country boundaries with various maxzooms. If you uncheck layer 14, and then zoom in past zoom 10, you'll see the layer with a maxzoom of 10 disappear. This is because each layer only displays data up to its maxzoom value. Once you reach the highest maxzoom of the tileset (zoom 14), the data in that layer will be overzoomed, so it can be viewed at zooms 14+. Overzooming scales your data from the tiles at your maxzoom, so there is precision loss that happens with this functionality. The multiple tileset section below provides a visual of this precision loss depending on your maxzoom.
This dataset also uses the bbox option to clip features so only country boundaries within most of North America are visible.
Recipe Used
{
"version": 1,
"layers": {
"layer10": {
"source": "mapbox://tileset-source/examples/country-polygons",
"minzoom": 0,
"maxzoom": 10,
"features": {
"bbox": [ -141.328125, 4.915832801313164, -57.30468749999999, 52.05249047600099 ]
}
},
"layer14": {
"source": "mapbox://tileset-source/examples/country-polygons",
"minzoom": 0,
"maxzoom": 14,
"features": {
"bbox": [ -141.328125, 4.915832801313164, -57.30468749999999, 52.05249047600099 ]
}
}
}
}
Multiple tilesets
The map below displays the same data source tiled with the recipe above, except each layer is an individual tileset instead of a multilayer tileset. Each individual tileset is overzoomed beyond its maxzoom so data is visible on the map. Yet, since the tileset with a maxzoom of zoom 10 only contains data at a country level perspective, as you zoom in to the state, city, or street level views, that data becomes increasingly imprecise. The tileset with a maxzoom of zoom 14 is more precise as you zoom in because tiles are available at this higher, city level perspective. It's important to note that data is still visible to users at all zoom levels.