Upload data to Mapbox

If you want to upload your data to Mapbox, you’ve come to the right place! From GeoTIFFs to Shapefiles, whether you want to edit your data or style it on a map, this guide outlines the different types of data you can upload, techniques for uploading, and common pitfalls and how to troubleshoot them.

Datasets vs. tilesets

Datasets and tilesets are two different types of files that you can create when uploading data to your Mapbox account.

Datasets provide access to feature geometries (points, lines, and polygons) and properties (attributes), both of which can be edited in the Mapbox Studio dataset editor or through the Mapbox Datasets API.

Tilesets are lightweight collections of vector data that are optimized for rendering and are not editable but can be styled in the Mapbox Studio style editor.

Uploads

Techniques for uploading datasets and tilesets are listed below. The size of your data file will affect how much can be transferred at one time. See the section on transfer limits to know which method is best.

Datasets

To add your data to a dataset, you can create a new, blank dataset through Mapbox Studio or through the Mapbox Datasets API and then add data to it. Note that the Mapbox Datasets API does not date GeoJSON files as uploads, but rather as the body of a POST request. See the Mapbox Datasets API documentation for more information.

Tilesets

You can upload your data as a tileset through:

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, see the Troubleshooting section below.

Errors

Upload failures directly in Mapbox Studio typically occur for two reasons:

  1. There’s an explicit issue with your data.
  2. The data has failed to process within one hour.

If there is an explicit issue with your data, you will receive a descriptive error message when the upload fails. Each message includes an error code that is described in full below. If your upload times out, read through the troubleshooting recommendations below.

Message Description Solution
Failed to find a shapefile in your zip You tried to upload a zipfile that did not include one of the files that make up a shapefile: .shp, .shx, .dbf, .prj. Make sure your zipfile contains each of these files.
vector_layers must be an array of layer objects Your data source may not have any layers. Check your data source in QGIS or use ogr2ogr to make sure it is correct.
Metadata exceeds limit of 60kb The TileJSON file in your MBTiles upload contains too much information. Remove extra or unneeded content from the TileJSON file (inside the MBTiles file).
KML does not contain any layers. Your KML file is empty. Make sure you have some layers in your data that are readable. Here’s an example of a valid KML file.
X layers found. Maximum of X layers allowed. Your KML file has more than 15 layers. This can happen when combining a number of files into one. Make sure to split up your layers into different files before uploading to Mapbox Studio. If you must use KML and require all the layers, check out kml-split, which breaks a KML into multiple files with fewer layers. Otherwise you can merge your layers into one and upload as either GeoJSON or a Shapefile.
Tileset exceeds processing limit. Your MBTiles file has more items than the limit allows. Try adjusting & limiting your zoom levels.
Dataset not found. It may have been deleted during processing into a tileset. The uploaded dataset was deleted during processing into a tileset. Try uploading the dataset again, and do not delete the dataset until the tileset processing has successfully completed.
Tile exceeds maximum size of ... The size of a specific tile in the MBTiles file is too large. Reduce the detail of data at this zoom level or omit it by adjusting your minzoom.
Grid exceeds maximum size of ... The size of the grid tile in the MBTiles file is too large. Reduce the detail of data at this zoom level or omit it by adjusting your minzoom.
Failed to parse geojson feature Your GeoJSON file has invalid syntax. Make sure your GeoJSON is compliant with the GeoJSON specification. You can validate your GeoJSON with GeoJSON Hint.
Error creating Mapnik Datasource: Invalid geojson Mapnik is unable to process the GeoJSON file, likely due to invalid syntax. Make sure your GeoJSON is compliant with the GeoJSON specification. You can validate your GeoJSON with GeoJSON Hint.
Coordinates beyond web mercator range. Please check projection and lat/lon values. The coordinates in your file are beyond the extend of Web Mercator. Check to see that your coordinates are in the correct order ([longitude, latitude]). Try visualizing your GeoJSON in geojson.io to see if geometries appear where you expect. If they do, try reprojecting to Web Mercator prior to uploading.
Unknown filetype You have one of the following:
- Bad TIFF files that are missing necessary information.
- Invalid MBTiles where the MBTiles is not recognized as an SQLite database.
- tmz2 files have been double zipped meaning the .zip process has been applied twice on the same file.
- Try running gdalinfo to get more information.
- Make sure your mbtiles file conforms the mbtiles specification.
- Check that the file has only been zipped once.

Troubleshooting

If you receive a Processing timed out message after a lengthy “processing” status, it is likely because your file has taken more than one hour to process and has timed out. To keep our upload queue fresh, we limit the time it takes for particularly large uploads. The following techniques can be used to update your data to improve processing time.

Note: the troubleshooting advice here mostly relates to tilesets, although some may be applicable to datasets as well. If you are having trouble uploading datasets and your issue is not listed here, please contact support.

Reproject to Web Mercator

During upload processing, we reproject all geometries to Web Mercator (EPSG:3857) before encoding into vector tiles. During the vector tile encoding process, if your data isn’t Web Mercator, each vertex must be reprojected during encoding, which can take a long time.

We suggest reprojecting your data before uploading to skip this process and speed up your upload. Here’s how you can reproject your data with open source tools:

  • GDAL’s ogr2ogr command line utility. The following example is how to convert a Shapefile to Web Mercator.

      ogr2ogr output.shp -t_srs "EPSG:3857" input.shp
    
  • QGIS allows for reprojection - Right click your layer -> Save As -> Select "Web Mercator EPSG:3857" as the output projection.

Multipart to singlepart

Multipart geometries can be complex – a single feature can be comprised of hundreds of thousands of polygons. These complex multipart geometries increase processing time and lead to timeouts.

To improve processing speeds, you can break each polygon into its own unique feature (singlepart) using QGIS. This will reduce the complexity per feature and allow the data to process faster. Note that each individual singlepart feature will share the attributes of the original feature.

multipart to singlepart

Note that population: 100 is duplicated. If you plan on styling based on attributes such as this, be wary of splitting into singleparts!

To change multipart to singlepart in QGIS use Vector -> Geometry Tools -> Multipart to singleparts.

Simplification

Simplifying your data means removing complexity in the vertices of your geometry. Each vertex must be translated to vector tile coordinates. The fewer vertices to translate, the faster processing becomes. Often you can simplify your data without any visual change. It’s important to watch out for oversimplification, though! Oversimplifying could remove important granularity in your data as well as potentially create invalid geometries if lines begin overlapping.

simplification image

Simplification tools typically take a tolerance parameter to specify how much to simplify. Some tools to use for simplifying data:

Limit large features

Large features that span the entire dataset can slow down processing.

illustration of a possible dataset

For example, consider this dataset of Hawaii. It contains a handful of smaller polygons that represent the islands. It also contains a large polygon that represents the surrounding water. Since the bounding box of the water polygon will intersect with nearly all the tile boundaries (grey lines), the water polygon will need to be processed for nearly every tile within this tileset.

There is no exact solution for this, since it largely depends on the dataset and how you plan to style and use the data.

Some possible solutions include:

  • Remove the large polygon if it’s not necessary for your use case.

  • Split the large polygon into smaller polygons: After creating a digitized layer of smaller polygons, use that digitized layer to intersect with the large polygon and split it into pieces. Then add the newly split feature into your original dataset.

    QGIS geometry intersection - Vector -> Geoprocessing Tools -> Intersection

    Caution: This could create unwanted polygon borders, depending on how you plan to style the dataset.

Slice large contour datasets

Large contour datasets can be particularly complex. Often they will have long, single feature linestrings wrapping across the entire dataset. Like the large polygons above, these can take a long time to process.

We recommend using GRASS’s v.split function via QGIS to break lines into shorter, equal segments. Smaller geometries will improve processing speed. If the contour data is highly detailed (as in, requires zoom 22) we recommend breaking lines every 5 kilometers.

TIFF uploads

  • Only 8-bit GeoTIFFs are supported. Run gdalinfo to find your GeoTIFF’s resolution.
  • Mapbox only accepts TIFFs with georeferencing information (GeoTIFFs). Make sure your TIFF is georeferenced before trying to upload.

If you are attempting to upload large TIFFs (multi GBs), here are some ways you can optimize your TIFF before uploading:

  • Reproject to Web Mercator EPSG:3857.
  • Set blocksize to 256x256.
  • If compression is needed, use LZW.
  • Remove Alpha band, if applicable.