Mapbox Tiling Service

Mapbox Tiling Service (MTS) is a tool for creating vector tilesets. With MTS, you use sets of configuration options (tileset recipes) to transform your geospatial data into vector tiles. The resulting tiles are hosted on Mapbox servers for use in your applications.

Vector tilesets are helpful if you want to visualize a large amount of data on a map quickly. When creating vector tiles, you can turn gigabytes of raw geospatial data into mere kilobytes, which can be critical for complex data visualizations since most modern browsers support loading about 100 MB of data at a time. And when you use MTS to create vector tiles, you have precise control over how your geospatial data is reduced into tiles.

Use cases

You can use MTS for many use cases. For example, you could use it to:

• Tile census boundaries to make interactive election visualizations.
• Add hiking paths, trails, or other roadways not included by default in Mapbox Streets to your map.
• Visualize activity data like runs or bike rides on a map.
• Add hotel or real estate properties and their attributes to a map.
• Create multi-layer tilesets (tilesets that contain up to 20 different data layers).

Because MTS is hosted by Mapbox and designed to scale, you can build full, end-to-end data pipelines with it. It's the same service Mapbox uses internally to create our global, daily-updating basemap Mapbox Streets.

How to use MTS

MTS requires two inputs to make tiles: a tileset source (your geospatial data) and a tileset recipe (a JSON document that specifies the configuration options for turning the tileset source into tiles). Learn more about tileset sources in the Tileset sources guide. Learn about how to format tileset recipes using the Recipe specification

You can interact with MTS in three ways:

• MTS Data Sync: Straightforward no-code MTS pipeline
• Tilesets CLI: Flexible, powerful tool for preparing and uploading data
• MTS API endpoints: Access the API endpoints directly

MTS Data Sync

MTS Data Sync is a command-line tool that allows you to publish data directly to MTS without writing any code. For many use-cases, MTS Data Sync provides the most straightforward way to use MTS. For example, it only takes one command to convert a standard GeoJSON file to line-delimited GeoJSON to use as a tileset source and to generate a tileset recipe. MTS Data Sync also provides a command that lets you estimate the cost of a tileset processing job.

For more information about the MTS Data Sync tool, including all available commands, see the MTS Data Sync documentation.

Tilesets CLI

The Tilesets CLI is a command-line Python tool that allows you to prepare and upload data for MTS. To create an example tileset using the Tilesets CLI, follow the Get started using Mapbox Tiling Service and the Tilesets CLI tutorial.

We recommend using the Tilesets CLI instead of MTS Data Sync if:

• You have a large dataset that needs multipart uploads
• Your use-case requires multiple tileset source files
• You prefer a less opinionated pipeline and want a more flexible tool

For more information about the Tilesets CLI, including all available commands, see the Tilesets CLI documentation.

MTS API endpoints

MTS has API endpoints for creating and interacting with tileset sources and tilesets. These endpoints are generally accessed using MTS Data Sync or the Tilesets CLI tool, but you can also access them directly instead (for example, if you want to integrate MTS into an application so that you can make vector tilesets programmatically).

To learn more about these API endpoints, see the MTS API documentation.

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:

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.

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.

Estimate tileset size in square kilometers

We have two tools to help you estimate the area of a tileset before you publish it:

• The Tilesets CLI estimate-area command
• The MTS Data Sync --estimate command

These commands will return the estimated area in km² for the tileset, which can be used with the pricing calculators to estimate the processing costs, hosting costs, or both associated with that tileset.

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.