ap3rture/tippecanoe repository overview

⁠tippecanoe

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

⁠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_MAX (population) attribute in features that are clustered together. Other attributes will be arbitrarily taken from the first feature in the cluster.

⁠Show countries at low zoom levels but states at higher zoom levels

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

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 -z3 -o countries-z3.mbtiles --coalesce-densest-as-needed ne_10m_admin_0_countries.geojson
tippecanoe -zg -Z4 -o states-Z4.mbtiles --coalesce-densest-as-needed --extend-zooms-if-still-dropping ne_10m_admin_1_states_provinces.geojson
tile-join -o states-countries.mbtiles countries-z3.mbtiles states-Z4.mbtiles

Countries:

• -z3: Only generate zoom levels 0 through 3
• --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

States and Provinces:

• -Z4: Only generate zoom levels 4 and beyond
• -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

⁠Represent multiple sources (Illinois and Indiana counties) as separate layers

curl -L -O https://www2.census.gov/geo/tiger/TIGER2010/COUNTY/2010/tl_2010_17_county10.zip
unzip tl_2010_17_county10.zip
ogr2ogr -f GeoJSON tl_2010_17_county10.geojson tl_2010_17_county10.shp

curl -L -O https://www2.census.gov/geo/tiger/TIGER2010/COUNTY/2010/tl_2010_18_county10.zip
unzip tl_2010_18_county10.zip
ogr2ogr -f GeoJSON tl_2010_18_county10.geojson tl_2010_18_county10.shp

tippecanoe -zg -o counties-separate.mbtiles --coalesce-densest-as-needed --extend-zooms-if-still-dropping tl_2010_17_county10.geojson tl_2010_18_county10.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

⁠Merge multiple sources (Illinois and Indiana counties) into the same layer

curl -L -O https://www2.census.gov/geo/tiger/TIGER2010/COUNTY/2010/tl_2010_17_county10.zip
unzip tl_2010_17_county10.zip
ogr2ogr -f GeoJSON tl_2010_17_county10.geojson tl_2010_17_county10.shp

curl -L -O https://www2.census.gov/geo/tiger/TIGER2010/COUNTY/2010/tl_2010_18_county10.zip
unzip tl_2010_18_county10.zip
ogr2ogr -f GeoJSON tl_2010_18_county10.geojson tl_2010_18_county10.shp

tippecanoe -zg -o counties-merged.mbtiles -l counties --coalesce-densest-as-needed --extend-zooms-if-still-dropping tl_2010_17_county10.geojson tl_2010_18_county10.geojson

As above, but

• -l counties: Specify the layer name instead of letting it be derived from the source file names

⁠Selectively remove and replace features (Census tracts) to update a tileset

# Retrieve and tile California 2000 Census tracts
curl -L -O https://www2.census.gov/geo/tiger/TIGER2010/TRACT/2000/tl_2010_06_tract00.zip
unzip tl_2010_06_tract00.zip
ogr2ogr -f GeoJSON tl_2010_06_tract00.shp.json tl_2010_06_tract00.shp
tippecanoe -z11 -o tracts.mbtiles -l tracts tl_2010_06_tract00.shp.json

# Create a copy of the tileset, minus Alameda County (FIPS code 001)
tile-join -j '{"*":["none",["==","COUNTYFP00","001"]]}' -f -o tracts-filtered.mbtiles tracts.mbtiles

# Retrieve and tile Alameda County Census tracts for 2010
curl -L -O https://www2.census.gov/geo/tiger/TIGER2010/TRACT/2010/tl_2010_06001_tract10.zip
unzip tl_2010_06001_tract10.zip
ogr2ogr -f GeoJSON tl_2010_06001_tract10.shp.json tl_2010_06001_tract10.shp
tippecanoe -z11 -o tracts-added.mbtiles -l tracts tl_2010_06001_tract10.shp.json

# Merge the filtered tileset and the tileset of new tracts into a final tileset
tile-join -o tracts-final.mbtiles tracts-filtered.mbtiles tracts-added.mbtiles

The -z11 option explicitly specifies the maxzoom, to make sure both the old and new tilesets have the same zoom range.

The -j option to tile-join specifies a filter, so that only the desired features will be copied to the new tileset. This filter excludes (using none) any features whose FIPS code (COUNTYFP00) is the code for Alameda County (001).

⁠Options

There are a lot of options. A lot of the time you won't want to use any of them other than -o output.mbtiles to name the output file, and probably -f to delete the file that already exists with that name.

If you aren't sure what the right maxzoom is for your data, -zg will guess one for you based on the density of features.

Tippecanoe will normally drop a fraction of point features at zooms below the maxzoom, to keep the low-zoom tiles from getting too big. If you have a smaller data set where all the points would fit without dropping any of them, use -r1 to keep them all. If you do want point dropping, but you still want the tiles to be denser than -zg thinks they should be, use -B to set a basezoom lower than the maxzoom.

If some of your tiles are coming out too big in spite of the settings above, you will often want to use --drop-densest-as-needed to drop whatever fraction of the features is necessary at each zoom level to make that zoom level's tiles work.

If your features have a lot of attributes, use -y to keep only the ones you really need.

If your input is formatted as newline-delimited GeoJSON, use -P to make input parsing a lot faster.

⁠Output tileset

• -o file.mbtiles or --output=file.mbtiles: Name the output file.
• -e directory or --output-to-directory=directory: Write tiles to the specified directory instead of to an mbtiles file.
• -f or --force: Delete the mbtiles file if it already exists instead of giving an error
• -F or --allow-existing: Proceed (without deleting existing data) if the metadata or tiles table already exists or if metadata fields can't be set. You probably don't want to use this.

⁠Tileset description and attribution

• -n name or --name=name: Human-readable name for the tileset (default file.json)
• -A text or --attribution=text: Attribution (HTML) to be shown with maps that use data from this tileset.
• -N description or --description=description: Description for the tileset (default file.mbtiles)

⁠Input files and layer names

• name.json or name.geojson: Read the named GeoJSON input file into a layer called name.
• name.json.gz or name.geojson.gz: Read the named gzipped GeoJSON input file into a layer called name.
• name.geobuf: Read the named Geobuf input file into a layer called name.
• name.csv: Read the named CSV input file into a layer called name.
• -l name or --layer=name: Use the specified layer name instead of deriving a name from the input filename or output tileset. If there are multiple input files specified, the files are all merged into the single named layer, even if they try to specify individual names with -L.
• -L name:file.json or --named-layer=name:file.json: Specify layer names for individual files. If your shell supports it, you can use a subshell redirect like -L name:<(cat dir/*.json) to specify a layer name for the output of streamed input.
• -L{layer-json} or --named-layer={layer-json}: Specify an input file and layer options by a JSON object. The JSON object must contain a "file" key to specify the filename to read from. (If the "file" key is an empty string, it means to read from the standard input stream.) It may also contain a "layer" field to specify the name of the layer, and/or a "description" field to specify the layer's description in the tileset metadata, and/or a "format" field to specify csv or geobuf file format if it is not obvious from the name. Example:

tippecanoe -z5 -o world.mbtiles -L'{"file":"ne_10m_admin_0_countries.json", "layer":"countries", "description":"Natural Earth countries"}'

CSV input files currently support only Point geometries, from columns named latitude, longitude, lat, lon, long, lng, x, or y.

⁠Parallel processing of input

• -P or --read-parallel: Use multiple threads to read different parts of each GeoJSON input file at once. This will only work if the input is line-delimited JSON with each Feature on its own line, because it knows nothing of the top-level structure around the Features. Spurious "EOF" error messages may result otherwise. Performance will be better if the input is a named file that can be mapped into memory rather than a stream that can only be read sequentially.

If the input file begins with the RFC 8142⁠ record separator, parallel processing of input will be invoked automatically, splitting at record separators rather than at all newlines.

Parallel processing will also be automatic if the input file is in Geobuf format.

⁠Projection of input

• -s projection or --projection=projection: Specify the projection of the input data. Currently supported are EPSG:4326 (WGS84, the default) and EPSG:3857 (Web Mercator). In general you should use WGS84 for your input files if at all possible.

⁠Zoom levels

• -z zoom or --maximum-zoom=zoom: Maxzoom: the highest zoom level for which tiles are generated (default 14)
• -zg or --maximum-zoom=g: Guess what is probably a reasonable maxzoom based on the spacing of features.
• -Z zoom or --minimum-zoom=zoom: Minzoom: the lowest zoom level for which tiles are generated (default 0)
• -ae or --extend-zooms-if-still-dropping: Increase the maxzoom if features are still being dropped at that zoom level. The detail and simplification options that ordinarily apply only to the maximum zoom level will apply both to the originally specified maximum zoom and to any levels added beyond that.
• -R zoom/x/y or --one-tile=zoom/x/y: Set the minzoom and maxzoom to zoom and produce only the single specified tile at that zoom level.

If you know the precision to which you want your data to be represented, or the map scale of a corresponding printed map, this table shows the approximate precision and scale corresponding to various -z options if you use the default -d detail of 12:

⁠Tile resolution

• -d detail or --full-detail=detail: Detail at max zoom level (default 12, for tile resolution of 2^12=4096)
• -D detail or --low-detail=detail: Detail at lower zoom levels (default 12, for tile resolution of 2^12=4096)
• -m detail or --minimum-detail=detail: Minimum detail that it will try if tiles are too big at regular detail (default 7)

All internal math is done in terms of a 32-bit tile coordinate system, so 1/(2^32) of the size of Earth, or about 1cm, is the smallest distinguishable distance. If maxzoom + detail > 32, no additional resolution is obtained than by using a smaller maxzoom or detail.

⁠Filtering feature attributes

• -x name or --exclude=name: Exclude the named attributes from all features. You can specify multiple -x options to exclude several attributes. (Don't comma-separate names within a single -x.)
• -y name or --include=name: Include the named attributes in all features, excluding all those not explicitly named. You can specify multiple -y options to explicitly include several attributes. (Don't comma-separate names within a single -y.)
• -X or --exclude-all: Exclude all attributes and encode only geometries

⁠Modifying feature attributes

• -Tattribute:type or --attribute-type=attribute:type: Coerce the named feature attribute to be of the specified type. The type may be string, float, int, or bool. If the type is bool, then original attributes of 0 (or, if numeric, 0.0, etc.), false, null, or the empty string become false, and otherwise become true. If the type is float or int and the original attribute was non-numeric, it becomes 0. If the type is int and the original attribute was floating-point, it is rounded to the nearest integer.
• -Yattribute:description or --attribute-description=attribute:description: Set the description for the specified attribute in the tileset metadata to description instead of the usual String, Number, or Boolean.
• -Eattribute:operation or --accumulate-attribute=attribute:operation: Preserve the named attribute from features that are dropped, coalesced-as-needed, or clustered. The operation may be sum, product, mean, max, min, concat, or comma to specify how the named attribute is accumulated onto the attribute of the same name in a feature that does survive.
• -pe or --empty-csv-columns-are-null: Treat empty CSV columns as nulls rather than as empty strings.
• -aI or --convert-stringified-ids-to-numbers: If a feature ID is the string representation of a number, convert it to a plain number to use as the feature ID.
• --use-attribute-for-id=name: Use the attribute with the specified name as if it were specified as the feature ID. (If this attribute is a stringified number, you must also use -aI to convert it to a number.)

⁠Filtering features by attributes

• -j filter or --feature-filter=filter: Check features against a per-layer filter (as defined in the Mapbox GL Style Specification⁠) and only include those that match. Any features in layers that have no filter specified will be passed through. Filters for the layer "*" apply to all layers. The special variable $zoom refers to the current zoom level.
• -J filter-file or --feature-filter-file=filter-file: Like -j, but read the filter from a file.

Example: to find the Natural Earth countries with low scalerank but high LABELRANK:

tippecanoe -z5 -o filtered.mbtiles -j '{ "ne_10m_admin_0_countries": [ "all", [ "<", "scalerank", 3 ], [ ">", "LABELRANK", 5 ] ] }' ne_10m_admin_0_countries.geojson

Example: to retain only major TIGER roads at low zoom levels:

tippecanoe -o roads.mbtiles -j '{ "*": [ "any", [ ">=", "$zoom", 11 ], [ "in", "MTFCC", "S1100", "S1200" ] ] }' tl_2015_06001_roads.json

Tippecanoe also accepts expressions of the form [ "attribute-filter", name, expression ], to filter individual feature attributes instead of entire features. For exampl