Mapbox Studio Classic source manual

With Mapbox Studio Classic, you can import custom sources. This manual will take a deep dive into important features and recommendations for preparing your sources.

Source project

A Mapbox Studio Classic source project is stored in a single directory with a .tm2source file extension. A typical source project directory looks like this:



  • data.yml is the main project file in YAML format. This file contains the core metadata to the project.
  • data.xml is a compiled mapnik XML file for the project. It can be used directly with tilelive-bridge to render the project to vector tiles.
  • .thumb.png is a thumbnail image that serves as a quick preview of the project.
  • data files used by a project should be kept in the project directory so that it’s portable.

Size limits

To ensure vector tiles rendering is fast, the following limits on source uploads are in place:

  • Individual vector tiles can not exceed 500kb at any zoom level
  • An entire .mbtiles export can not exceed 5gb

Optimizing uploads

If your upload is rejected then the next step is to optimize your source to ensure the vector tiles are smaller. There are many ways to do this. Below are several workflows for how to do this with specific considerations for geometry type - point, line, or polygon:

Supported import formats

Mapbox Studio Classic supports several different types of data sources:

  • Shapefiles
  • GeoJSON
  • geographic SQLite databases
  • PostGIS databases
  • GeoTIFFs
  • VRTs
  • KML
  • GPX (GPS Exchange Format)
  • CSV (Comma-Separated Value) files containing latitude and longitude fields.


In the Settings panel, you can change the minzoom and maxzoom for the source. These values define which zoom levels will be included in your source.

  • minzoom defines how far out users will be able to zoom and still see data.
  • maxzoom defines the maximum zoom level your source will store data for, but it’s possible to display this data at even higher zoom levels.

The ability to display data at higher zoom levels is referred to as overzooming. Overzooming allows for great efficiency in creating and storing vector tiles by reducing the number of tiles required by several orders of magnitude.

As a general rule, vector tiles are useful for about 4-6 levels of overzooming. For example, the data in a zoom level 14 tile can be stretched out and look great up to zoom level 18 or 20.


When you import a data source using Add layer, you can set the buffer for the source. A buffer on a layer allows you to include extra data around the outside of each tile. Depending on the data and desired styles this can be necessary to ensure seamless rendering across tile boundaries. Tile buffers are set individually for each layer; different layers have different requirements and it’s important to make boundaries no larger than necessary in order to keep the size of your vector tiles to a minimum.

The value for the buffer setting is in pixels (assuming that the vector tile is rendered at 256×256 pixels).

General guidelines when setting the buffer size:

  • Buffers for label layers should be quite large - often 128 pixels.
  • Buffers for line and polygon layers should be at least half the width of the widest stroke you think you’ll want to draw.
  • If you think styles such as blurs or geometry-transforms will be useful for a layer, you’ll want to take this into account. A buffer of 8 pixels will allow blurring by up to 8 pixels without artifacts.

Also note that tile buffers get stretched along with the rest of the tile when overzooming. A z14 layer with an 8 pixel buffer will actually have a 16 pixel buffer if shown overzoomed at z15, 32 pixels at z16, and so on.

Labeling polygons

Placing text labels on polygons doesn’t work quite like in TileMill. With vector tiles, a polygon might be split across many vector tiles, so if you use text-placement: point, you will end up with lots of duplicate labels. As a workaround, you will need to create a layer containing the centroid of each polygon, and use that for polygon labeling.

You can use QGIS or PostGIS to create a centroid layer.

Shapefile, GeoJSON

If your polygons are saved as Shapefile or GeoJSON then you can use QGIS, an open source desktop GIS tool, to generate an additional layer.

  1. In QGIS, browse to the file and double-click it to view.
  2. From the menu, select Vector > Geometry Tools > Polygon centroids
  3. Browse to where you want the output file to go, click OK.
  4. Import the new layer to your Mapbox Studio Classic source project.


Using PostGIS you can perform the centroid computation on the fly using ST_PointOnSurface(). Create a new layer, with an SQL query such as:

( SELECT ST_PointOnSurface(geom) AS geom, name
  FROM ne_10m_lakes
) AS data

Layer ordering

In Mapbox Studio Classic’s source editor, you can drag and drop layers in the layer list to reorder them. This is helpful when you’ve added multiple layers to single source project. The order they’re listed here will be the order they’re stored in the vector tiles and the default order styles will use to draw. Layers at the top of the list will be drawn on top of layers further down.

For most map designs, you will want an order that looks some thing like this:

  • Least important labels at the top.
  • Most important labels below less important labels, but above everything else.
  • Roads and/or data layers in the middle.
  • Landuse and landcover areas on the bottom.

Advanced PostgreSQL layers

Check out our PostGIS Manual for more details on how to use PostGIS + SQL with Mapbox Studio Classic to create fast, performant vector tiles.

The Natural Earth Mapbox Studio Classic project is a great example of a full Mapbox Studio Classic source and includes advanced PostgreSQL tricks like having multiple tables in one layer and scale-aware queries.

Next article:

Mapbox Studio Classic style manual

Learn the ins and outs of styling maps with vector tile data sources in Mapbox Studio Classic. We'll cover the directory structure of a style project, referencing and compositing data sources, and how to control data layer order and priority.

Additional questions? Ask our support team or learn more about How Mapbox Works.