Tilesets

Tilesets are the primary data format for Mapbox maps. Whether you start with your own custom data or you create a dataset first, converting your data into a tileset will allow you to add it to a Mapbox map and style it using the Mapbox Studio style editor.

Mapbox Studio topics covered in this section:

with the dataset editor

Upload

with the dataset editor

Dataset

by exporting your dataset

Tileset

on the styles page

Template style

in the style editor

Custom style

containing your tileset in the style editor

Add data to style

in the style editor

Style data

in the style editor

Publish

What is a tileset?

A tileset is a collection of raster or vector data broken up into a uniform grid of square tiles at up to 22 preset zoom levels. Tilesets are used in Mapbox libraries and SDKs as a core piece of making maps visible on mobile or in the browser; they are also the main mechanism we use for determining map views.

Tilesets are highly cacheable and load quickly. Mapbox relies heavily on both raster and vector tilesets to keep our maps fast and efficient.

Manage tilesets

The Tilesets page is where you can add and manage your uploaded tilesets.

The Tilesets page shows you a list of all your uploaded tilesets, plus the five Mapbox-provided tilesets:

Unlike the tilesets you upload, the Mapbox Streets and Mapbox Terrain tilesets have layers that group certain features together. Any tilesets you upload will appear below the tilesets Mapbox provides.

New tileset

Click the New tileset button to create a new tileset. You can either Upload a file or Create from dataset.

Note

When a vector data file is uploaded to Mapbox, it is converted to vector tile format. When a raster data file (like an image) is uploaded to Mapbox, it becomes a set of tiled PNGs.

Upload a file

When uploading a file, the uploads pane will appear in the lower right corner of the page. This pane shows the tileset ID and status of your upload — the circle will be blue while the file is processing and green once the file has been uploaded.

For more information about uploading data to your Mapbox account, see the Uploads page.

Create from dataset

Click the Create from dataset tab to create a tileset from a dataset. A modal will appear with a list of all datasets associated with your account. Choose a dataset from the list and click Export dataset. You will have the choice to either Export to a new tileset or, if that dataset is already connected to a tileset, the option to Update a connected tileset.

Tileset menu

For each tileset, you can either click on the name of the tileset to go to the Tileset explorer or click the button for more options:

Replace

Replace the current data in your tileset with new data. The tileset ID will stay the same and the new data will be reflected in all styles that reference this tileset.

Make public or private

Choose whether a tileset should be private or public. If a tileset is public, the tileset ID can be used by any Mapbox user with their access tokens. But, only the owner of a tileset can make changes or delete a tileset, even if it's public. If a tileset is private, the tileset ID can only be used with an access token from the owner's account. By default, new tilesets created in Mapbox Studio are private.

Delete

You can permanently delete a tileset from your account at any time. Deleted tilesets may not be recovered.

Tileset ID

From this menu, you can also copy the tileset ID to be used with Mapbox SDKs and APIs.

Tileset explorer

You can find additional information about your tilesets in the Tileset explorer.

Vector layers

For vector tilesets, you will see a list of Vector layers within the tileset. Every layer in the list contains information about its properties, including the property name, data type, and associated values.

You can use the to toggle layers on and off to focus on per-layer visual assessments.

Tile size

The Tile size graph displays information about the size of your map tiles at every supported zoom level. This allows you to see which areas of your map house the most data, allowing you to optimize your map's performance. If a tileset was created with Mapbox Studio or the Uploads API, the Tile size graph is not available.

X-ray view

The Tileset explorer x-ray view provides you with a preview of what your data looks like when it is rendered on a map. The x-ray view also lets you click on individual features to inspect the geometry and associated properties.

Bounding box viewport

The bounding box viewport displays the bounds of your data, in terms of your dataset’s extent and the current viewport. The dotted line shows the geographic extent of the dataset processed, while the small solid box shows the current viewport of the map. This allows you to understand your data viewed within the context of a world map.

You can also use the bounding box viewport to navigate around the map area. Click on the dotted line to zoom the map out to the extent of the data, or drag the viewport box to pan around the map.

Job history

For tilesets created with Mapbox Tiling Service, you can use the Job history menu to see an overview of all the tileset's associated publish jobs, as well as metadata including the job status, the tileset recipe, warnings and errors, and processing time. If a tileset was created with Mapbox Studio or the Uploads API, the Job history menu is not available.

Share & use

The Share & use menu includes additional information about the tileset, including:

  • A share link to the tileset
  • The tileset ID
  • A toggle to change the tileset's visibility from Private to Public

Pricing

Tilesets uploaded in Mapbox Studio are free, and do not incur processing or hosting charges. Free uploads via Mapbox Studio are limited to 20 uploads per month, and 300 MB per upload.

To understand the costs associated with uploading tilesets programmatically, see the pricing documentation for the Mapbox Tiling Service (MTS) or the Uploads API.