With Mapbox Studio, you can upload custom data to your account to be added to a map. If you want to style a map without custom data, that’s also great! Head to the Styles section of this manual.

Mapbox Studio topics covered in this section:

Types of uploads

Datasets and tilesets are two different formats you can create when uploading custom data to your Mapbox account. If you want to upload data and edit it before adding to a map, upload as a dataset. If you want to upload data to add directly to a map, upload as a tileset.

Uploading data you can edit (datasets)

When you upload your data as a dataset, feature geometries (points, lines, and polygons) and properties (attributes) can be edited, added, or removed in the Mapbox Studio dataset editor. Once you have finished editing your dataset, you will need to save it and export it as a tileset in order to add it to a style.

Uploading data to add to a map (tilesets)

Tilesets are lightweight collections of vector or raster data that are optimized for rendering and are not editable but can be styled in the Mapbox Studio style editor. When you upload vector data as a tileset, it is simplified and cut up into vector tiles that can be used directly in your style. Once data is converted to a tileset, it is no longer editable.

Preparing your data for upload

Mapbox Studio allows you to upload your own custom data to use in your map styles. You can upload your files on the Tilesets page.

For a smooth upload process, it helps to make sure that:

  • Geospatial data has been projected to Web Mercator (EPSG:3857).
  • GeoJSON files have been validated for proper syntax.
  • Unnecessary properties have been removed.

Uploading using the Uploads API

Alternatively, you can use the Mapbox Uploads API to upload an accepted file that is transformed into a tileset. With the Uploads API, Mapbox provides you with a temporary S3 bucket to stage uploads that can be started and monitored.

Accepted file types and transfer limits

The accepted file types and transfer limits for dataset and tileset uploads include:

File type Datasets Tilesets Transfer limits
CSV 5 Mb for datasets, 1 GB for tilesets
GeoJSON 5 Mb for datasets, 1 GB for tilesets
MBTiles   25 GB
KML   260 Mb with 15 layers or fewer
GPX   260 Mb
Shapefile   260 Mb (combined uncompressed size of .shp and .dbf files) You must upload shapefiles as a compressed (.zip) file.
GeoTIFF   10 GB

If your file size exceeds these limits or if you run into errors, see our troubleshooting guide.

Zoom levels and simplification

When an upload is completed in Mapbox Studio, it is rendered into a tileset. After the tileset is created, your data is sometimes simplified at lower zoom levels to reduce the complexity of the data and ensure that each tile is below a certain size. This is done to make your map load faster in areas where details wouldn’t be normally noticed.

Uploaded tilesets are also given a zoom extent. This zoom extent is the total zoom range in which features are visible, which is listed on the tileset information page. If you need your tileset to be visible at a different zoom extent, you can adjust this manually.

More about tilesets

See the Tilesets section for more information on how to upload and manage tilesets in Mapbox Studio.

Read about tilesets

More about datasets

See the Datasets section for more information on how to upload, manage, and edit datasets in Mapbox Studio.

Read about datasets

Troubleshooting common upload errors

Having trouble with uploads? Check out our troubleshooting page.

Visit troubleshooting page

Next section:
Learn how to create and manage styles in Mapbox Studio.