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 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.
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.
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.
If your file size exceeds these limits, see the Troubleshooting section below.
An extra note on dataset uploads: Multiple files can be uploaded to the same dataset without limit – they just 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.
Upload failures directly in Mapbox Studio typically occur for two reasons:
There’s an explicit issue with your data
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.
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.
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.
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.
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.
Note that population: 100 is duplicated. If you plan on styling based on attributes such as this, be wary of splitting into singleparts!
QGIS multipart to singlepart - Vector -> Geometry Tools -> Multipart to singleparts
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 tools typically take a tolerance parameter to specify how much to simplify. Some tools to use for simplifying data:
Large features that span the entire dataset can slow down processing.
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.
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.
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: