Skip to main content

Mapbox Tiling Service

  • check
    Create highly customized vector tilesets
  • check
    Specify IDs for each feature in a tileset
  • check
    Reuse uploaded data across multiple tilesets
  • check
    Generate tilesets with multiple layers to optimize for performance
lightning
Public beta
Mapbox Tiling Service is in public beta. All features and workflows are subject to potential changes.

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

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:

Your raw geographic source data must be formatted as line-delimited GeoJSON (uncompressed line-delimited sequences of GeoJSON features). For information on how to format your geographic source data correctly, see the Tileset sources guide.
arrow-down
You need a tileset source before you can create a new tileset. For information on how to create a new tileset source, see the Create a tileset source MTS endpoint documentation.
arrow-down
Tileset recipes describe transformation options for converting your tileset sources into vector tiles. For information on how to write your tileset recipe, see the Recipe specification.
arrow-down
You will create an empty tileset before you publish your data to it in the next step. For information on how to use a tileset recipe to create a new tileset, see the Create a tileset MTS endpoint documentation.
arrow-down
After you create a new empty tileset, you can publish it. This starts an asynchronous publish job that retrieves your data and processes it to your tileset according to your tileset recipe. For information on how to create a publish job, see the Publish a tileset MTS endpoint documentation.

Style an MTS-created tileset

Once you have created a new tileset with MTS, you can view and style it in Mapbox Studio:

Open a new or existing map style in Mapbox Studio, and click on the Layers tab. Click the + button to add a new layer. For detailed information on how to add a new layer in Mapbox Studio, see the Studio Manual.
arrow-down
Choose the tileset you created in MTS from the list of tilesets. You can filter this list by name. You can also click + Add tileset by ID. You need the full tileset ID to select your tileset with this method. For detailed information on how to add a tileset in Mapbox Studio, see the Studio Manual
arrow-down
Click on the Style tab to start styling your data. For more information on how to style a layer in Mapbox Studio, see the Studio Manual.

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:

To update a tileset's tiles, you need to first delete your original tileset source. For information on how to delete a tileset source, see the Delete a tileset source MTS endpoint documentation.
arrow-down
Next, create a new tileset source with your updated geographic source data. This new tileset source must have the same tileset source ID as the original tileset source did so you don't need to also update your tileset recipe when you publish your updates later. For information on how to create a tileset source, see the Create a tileset source MTS endpoint documentation.
arrow-down
After you have created your new tileset source, you can begin a new publish job for the tileset you are updating. This job processes your new tileset source according to your tileset recipe, and the tiles will be updated accordingly. For information on how to create a publish job, see the Publish a tileset MTS endpoint documentation.
alert
WARNING
To update your tileset's tiles without changing the tileset ID or the tileset recipe, use the --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:

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 1zoom 5zoom 11zoom 16zoom 18
continents, country borders, state + province labelslakes, landuse, major roads, city labelslanduse, parks, all roads, major points of interest labelsblock level, restaurant locations, building outlinesbench 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 tiles1,024 tiles4,194,304 tiles4,294,967,296 tiles68,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.

Estimate tileset size in square kilometers

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

These commands will return the estimated area in km2 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.

Was this page helpful?