tippecanoe

Note: there is an active fork of this project over at https://github.com/felt/tippecanoe

Builds vector tilesets from large (or small) collections of GeoJSON, Geobuf, or CSV features, like these.

:zap: Mapbox has a new service for creating vector tilesets! :zap:

Mapbox Tiling Service (MTS) is a hosted, data processing service that allows you to integrate custom datasets of any scale into your maps faster, cheaper, and with more flexibility and control than previously possible.

MTS is the same service we use internally to create our global, daily updating basemap product Mapbox Streets, which serves over 650 million monthly active users and customers such as Facebook, Snap, the Weather Channel, Tableau, and Shopify.

MTS creates and updates data using distributed and parallelized processing, meaning data is processed much more quickly than is possible with a standard, single server setup with comparable tools. For example, a global basemap at 30cm precision (max zoom of 16) can be processed in under 2 hours with MTS, whereas a comparable workload would take multiple days to process on a single server.

Customers like AllTrails, Plume Labs, and Ookla have noted that MTS helps them:

• build applications faster by focusing more on app development, not infrastructure
• build more compelling user experiences that drive better user engagement
• get updated data to their users faster—in some cases up to 90% faster than previous tools

Learn more about MTS.

Intent

The goal of Tippecanoe is to enable making a scale-independent view of your data, so that at any level from the entire world to a single building, you can see the density and texture of the data rather than a simplification from dropping supposedly unimportant features or clustering or aggregating them.

If you give it all of OpenStreetMap and zoom out, it should give you back something that looks like "All Streets" rather than something that looks like an Interstate road atlas.

If you give it all the building footprints in Los Angeles and zoom out far enough that most individual buildings are no longer discernable, you should still be able to see the extent and variety of development in every neighborhood, not just the largest downtown buildings.

If you give it a collection of years of tweet locations, you should be able to see the shape and relative popularity of every point of interest and every significant travel corridor.

Installation

The easiest way to install tippecanoe on OSX is with Homebrew:

$ brew install tippecanoe

On Ubuntu it will usually be easiest to build from the source repository:

$ git clone https://github.com/mapbox/tippecanoe.git
$ cd tippecanoe
$ make -j
$ make install

See Development below for how to upgrade your C++ compiler or install prerequisite packages if you get compiler errors.

Usage

$ tippecanoe -o file.mbtiles [options] [file.json file.json.gz file.geobuf ...]

If no files are specified, it reads GeoJSON from the standard input. If multiple files are specified, each is placed in its own layer.

The GeoJSON features need not be wrapped in a FeatureCollection. You can concatenate multiple GeoJSON features or files together, and it will parse out the features and ignore whatever other objects it encounters.

Try this first

If you aren't sure what options to use, try this:

$ tippecanoe -zg -o out.mbtiles --drop-densest-as-needed in.geojson

The -zg option will make Tippecanoe choose a maximum zoom level that should be high enough to reflect the precision of the original data. (If it turns out still not to be as detailed as you want, use -z manually with a higher number.)

If the tiles come out too big, the --drop-densest-as-needed option will make Tippecanoe try dropping what should be the least visible features at each zoom level. (If it drops too many features, use -x to leave out some feature attributes that you didn't really need.)

Examples

Create a tileset of TIGER roads for Alameda County, to zoom level 13, with a custom layer name and description:

$ tippecanoe -o alameda.mbtiles -l alameda -n "Alameda County from TIGER" -z13 tl_2014_06001_roads.json

Create a tileset of all TIGER roads, at only zoom level 12, but with higher detail than normal, with a custom layer name and description, and leaving out the LINEARID and RTTYP attributes:

$ cat tiger/tl_2014_*_roads.json | tippecanoe -o tiger.mbtiles -l roads -n "All TIGER roads, one zoom" -z12 -Z12 -d14 -x LINEARID -x RTTYP

Cookbook

Linear features (world railroads), visible at all zoom levels

curl -L -O https://www.naturalearthdata.com/http//www.naturalearthdata.com/download/10m/cultural/ne_10m_railroads.zip
unzip ne_10m_railroads.zip
ogr2ogr -f GeoJSON ne_10m_railroads.geojson ne_10m_railroads.shp

tippecanoe -zg -o ne_10m_railroads.mbtiles --drop-densest-as-needed --extend-zooms-if-still-dropping ne_10m_railroads.geojson

• -zg: Automatically choose a maxzoom that should be sufficient to clearly distinguish the features and the detail within each feature
• --drop-densest-as-needed: If the tiles are too big at low zoom levels, drop the least-visible features to allow tiles to be created with those features that remain
• --extend-zooms-if-still-dropping: If even the tiles at high zoom levels are too big, keep adding zoom levels until one is reached that can represent all the features

Discontinuous polygon features (buildings of Rhode Island), visible at all zoom levels

curl -L -O https://usbuildingdata.blob.core.windows.net/usbuildings-v1-1/RhodeIsland.zip
unzip RhodeIsland.zip

tippecanoe -zg -o RhodeIsland.mbtiles --drop-densest-as-needed --extend-zooms-if-still-dropping RhodeIsland.geojson

• -zg: Automatically choose a maxzoom that should be sufficient to clearly distinguish the features and the detail within each feature
• --drop-densest-as-needed: If the tiles are too big at low or medium zoom levels, drop the least-visible features to allow tiles to be created with those features that remain
• --extend-zooms-if-still-dropping: If even the tiles at high zoom levels are too big, keep adding zoom levels until one is reached that can represent all the features

Continuous polygon features (states and provinces), visible at all zoom levels

curl -L -O https://www.naturalearthdata.com/http//www.naturalearthdata.com/download/10m/cultural/ne_10m_admin_1_states_provinces.zip
unzip -o ne_10m_admin_1_states_provinces.zip
ogr2ogr -f GeoJSON ne_10m_admin_1_states_provinces.geojson ne_10m_admin_1_states_provinces.shp

tippecanoe -zg -o ne_10m_admin_1_states_provinces.mbtiles --coalesce-densest-as-needed --extend-zooms-if-still-dropping ne_10m_admin_1_states_provinces.geojson

• -zg: Automatically choose a maxzoom that should be sufficient to clearly distinguish the features and the detail within each feature
• --coalesce-densest-as-needed: If the tiles are too big at low or medium zoom levels, merge as many features together as are necessary to allow tiles to be created with those features that are still distinguished
• --extend-zooms-if-still-dropping: If even the tiles at high zoom levels are too big, keep adding zoom levels until one is reached that can represent all the features

Large point dataset (GPS bus locations), for visualization at all zoom levels

curl -L -O ftp://avl-data.sfmta.com/avl_data/avl_raw/sfmtaAVLRawData01012013.csv
sed 's/PREDICTABLE.*/PREDICTABLE/' sfmtaAVLRawData01012013.csv > sfmta.csv
tippecanoe -zg -o sfmta.mbtiles --drop-densest-as-needed --extend-zooms-if-still-dropping sfmta.csv

(The sed line is to clean the corrupt CSV header, which contains the wrong number of fields.)

• -zg: Automatically choose a maxzoom that should be sufficient to clearly distinguish the features and the detail within each feature
• --drop-densest-as-needed: If the tiles are too big at low or medium zoom levels, drop the least-visible features to allow tiles to be created with those features that remain
• --extend-zooms-if-still-dropping: If even the tiles at high zoom levels are too big, keep adding zoom levels until one is reached that can represent all the features

Clustered points (world cities), summing the clustered population, visible at all zoom levels

curl -L -O https://www.naturalearthdata.com/http//www.naturalearthdata.com/download/10m/cultural/ne_10m_populated_places.zip
unzip -o ne_10m_populated_places.zip
ogr2ogr -f GeoJSON ne_10m_populated_places.geojson ne_10m_populated_places.shp

tippecanoe -zg -o ne_10m_populated_places.mbtiles -r1 --cluster-distance=10 --accumulate-attribute=POP_MAX:sum ne_10m_populated_places.geojson

• -zg: Automatically choose a maxzoom that should be sufficient to clearly distinguish the features and the detail within each feature
• -r1: Do not automatically drop a fraction of points at low zoom levels, since clustering will be used instead
• --cluster-distance=10: Cluster together features that are closer than about 10 pixels from each other
• --accumulate-attribute=POP_MAX:sum: Sum the `POP