If you have a large data file, you may have trouble uploading it into Mapbox Studio. This guide will show you how to use Tippecanoe, a command-line utility, to convert your data into smaller files suitable for uploading to Mapbox Studio.
Install Tippecanoe and GDAL
Unfortunately, Tippecanoe is currently not supported on Windows.
Before you get started, you’ll need to install Tippecanoe and GDAL. We recommend installing Tippecanoe and GDAL with Homebrew. Open your
terminal window and run the following commands.
brew install gdal --enable-unsupported --with-libkml --with-mysql
For Ubuntu-based distributions run:
sudo apt-get install gdal-bin
Then follow the instructions to build Tippecanoe from source.
Now run this command to verify your formats are available:
Work with a large data file
For this example, you’ll be working with Mapzen’s Metro Extracts for New York City. Download the IMPOSM SHP collection for New York, New York to work along with this guide.
When you unzip the downloaded file, it should contain 13 Shapefiles representing different features in New York City.
Next, you will upload the
new-york_new-york_osm_buildings Shapefile. This will be all of the
These files combined are over
362 MB. Zip or compress these four files.
Now let’s try to upload our zipped Shapefile.
Log into Mapbox Studio and open the Tilesets tab on the left. Click New tileset and upload the zipped Shapefile.
Too big to process
Mapbox Studio tries to process this data into a vector tile but instead errors with:
Error: File is larger than 272.63 MB. Too big to process.
Even though the zipped Shapefile is only about
90 MB, the datafiles are actually much larger.
Convert to vector tiles with Tippecanoe
Since the data file is too large for Mapbox Studio to process, you can use Tippecanoe to convert your custom data to vector tiles within the size limits. You must start with a data format readable by Tippecanoe: in this case, GeoJSON.
Let’s convert this Shapefile into GeoJSON. We’re going to use
ogr2gor which we downloaded and installed earlier to do the conversion.
Convert Shapefiles to GeoJSON
Open your terminal window and navigate to the folder where you saved the Shapefiles earlier (not the zipped folder you created before):
Next, we’ll take
new-york_new-york_osm_buildings.shp and convert it to GeoJSON (
.json). Run the
ogr2ogr conversion command:
ogr2ogr -f GeoJSON new-york_new-york_osm_buildings.json \
new-york_new-york_osm_buildings.shp -progress \
-progress is added here to watch as the file converts and see when it’s
Once it’s done you should see
new-york_new-york_osm_buildings.json in the folder with the rest of the data.
Convert GeoJSON to vector tiles
Now it’s time to convert
new-york_new-york_osm_buildings.json into vector tiles (
.mbtiles) with Tippecanoe. Run the Tippecanoe command:
tippecanoe -o new-york-city_buildings.mbtiles new-york_new-york_osm_buildings.json
With the command above, Tippecanoe reads and sorts the features, converts them, and voila! A shiny, new vector tileset!
You should see a
new-york-city_buildings.mbtiles file in your data folder.
Upload to Mapbox Studio
Now let’s try to upload the data file to Mapbox Studio again, but instead of the zipped Shapefile, we’ll upload the vector tileset (
After the file uploads, click on the data file from the Tilesets tab and then click Add to style. Check out our Add custom data in Mapbox article to learn more about adding your data to a map style.
After you’re done uploading, you’ll need to style your data. Our series on Styling data types in Mapbox Studio has lots of tips for that: