Manage large data files for Mapbox Studio with Tippecanoe

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.

Mac OS

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.

Install Tippecanoe:

brew install tippecanoe

Install GDAL:

brew install gdal --enable-unsupported --with-libkml --with-mysql

Linux

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: ogr2ogr --formats

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 new-york_new-york_osm_buildings files:

  • new-york_new-york_osm_buildings.shx
  • new-york_new-york_osm_buildings.shp
  • new-york_new-york_osm_buildings.prj
  • new-york_new-york_osm_buildings.dbf

These files combined are over 362 MB. Zip or compress these four files.

Upload data

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):

cd ~/path/to/new-york_new-york.imposm-shapefiles

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 \

The option -progress is added here to watch as the file converts and see when it’s 100% converted.

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 (new-york-city_buildings.mbtiles).

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.

Next steps

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:

Additional questions? Ask our support team or learn more about How Mapbox Works.