Skip to main content

Geospatial data

With Mapbox Studio, you can upload and manage custom data to be added to a map.

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

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.

book
NOTE
If you are uploading raster data, you must 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 to add it to a style.

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu

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.

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu

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 Mapbox Tiling Service

lightning
Beta support for uploading data with Mapbox Tiling Service

Mapbox Tiling Service is in beta and is subject to potential changes.

You can also use Mapbox Tiling Service (MTS) to upload vector geographic data, transform the data according to the configuration options described in a tileset recipe, and turn it into a vector tileset. MTS can be accessed using the Tilesets CLI or programmatically using the MTS API endpoints. For more information on how to upload custom data as a tileset using MTS, see the MTS documentation.

You should use MTS for tileset creation unless you need to create raster tilesets, in which case you can use the Uploads API (see below).

Uploading using the Uploads API

You can use the Mapbox Uploads API to upload data to be 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. The Uploads API does not allow you to choose configuration options, making MTS the better choice for uploading data unless you need to upload raster data.

Uploading using Mapbox Studio

Uploads created in Mapbox Studio via the Mapbox Studio style editor, your tilesets page, or exported from a dataset using the dataset editor are subject to additional limits. These uploads cannot exceed 300 MB, and are limited to 20 uploads per month. Some file types have limits below 300 MB. See the chart below for limits by file type.

Accepted file types and transfer limits

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

File typeDatasetsTilesetsTransfer limits
CSVcheckcheck5 MB for datasets, 1 GB for tilesets
GeoJSONcheckcheck5 MB for datasets, 1 GB for tilesets
MBTilescheck25 GB
KMLcheck260 MB with 15 layers or fewer
GPXcheck260 MB
Shapefilecheck260 MB (combined uncompressed size of .shp and .dbf files) You must upload shapefiles as a compressed .zip file.
GeoTIFFcheck10 GB

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

book
NOTE

Multiple files can be uploaded to the same dataset without limit — they need to be loaded 5 MB at a time. The size of a dataset is unlimited, but the Mapbox Studio dataset editor can only display datasets of 20 MB or smaller. These datasets can still be downloaded from Mapbox Studio and accessed through the Datasets API.

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 make sure that each tile is below a certain size. Mapbox Studio does this 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.

book
NOTE

Zoom extents for vector tiles affect the zoom levels at which tiles are generated. This is different from the zoom levels at which the data is visible: Vector tilesets can be styled up to zoom level 22, and zoom levels higher than the zoom extent will be styled using the highest zoom tiles available.

More about tilesets

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

Read about tilesetschevron-right

More about datasets

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

Read about datasetschevron-right

Troubleshooting common upload errors

Having trouble with uploads? Try our troubleshooting guides.

View troubleshooting guideschevron-right
Was this page helpful?