search

mapbox / tippecanoe

Build vector tilesets from large collections of GeoJSON features.
BSD 2-Clause "Simplified" License
2.64k stars 426 forks source link
c-plus-plus geojson vector-tiles

readme

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.

Mapbox Tippecanoe

Build Status Coverage Status

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

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

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

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

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

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

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:

States and Provinces:

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

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

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

Tileset description and attribution

Input files and layer names

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

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

Zoom levels

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:

zoom level precision (ft) precision (m) map scale
-z0 32000 ft 10000 m 1:320,000,000
-z1 16000 ft 5000 m 1:160,000,000
-z2 8000 ft 2500 m 1:80,000,000
-z3 4000 ft 1250 m 1:40,000,000
-z4 2000 ft 600 m 1:20,000,000
-z5 1000 ft 300 m 1:10,000,000
-z6 500 ft 150 m 1:5,000,000
-z7 250 ft 80 m 1:2,500,000
-z8 125 ft 40 m 1:1,250,000
-z9 64 ft 20 m 1:640,000
-z10 32 ft 10 m 1:320,000
-z11 16 ft 5 m 1:160,000
-z12 8 ft 2 m 1:80,000
-z13 4 ft 1 m 1:40,000
-z14 2 ft 0.5 m 1:20,000
-z15 1 ft 0.25 m 1:10,000
-z16 6 in 15 cm 1:5000
-z17 3 in 8 cm 1:2500
-z18 1.5 in 4 cm 1:1250
-z19 0.8 in 2 cm 1:600
-z20 0.4 in 1 cm 1:300
-z21 0.2 in 0.5 cm 1:150
-z22 0.1 in 0.25 cm 1:75

Tile resolution

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

Modifying feature attributes

Filtering features by attributes

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 example, you can exclude the road names at low zoom levels by doing

tippecanoe -o roads.mbtiles -j '{ "*": [ "attribute-filter", "FULLNAME", [ ">=", "$zoom", 9 ] ] }' tl_2015_06001_roads.json

An attribute-filter expression itself is always considered to evaluate to true (in other words, to retain the feature instead of dropping it). If you want to use multiple attribute-filter expressions, or to use other expressions to remove features from the same layer, enclose them in an all expression so they will all be evaluated.

Dropping a fixed fraction of features by zoom level

Dropping a fraction of features to keep under tile size limits

Dropping tightly overlapping features

Line and polygon simplification

Attempts to improve shared polygon boundaries

Controlling clipping to tile boundaries

Reordering features within each tile

Adding calculated attributes

Trying to correct bad source geometry

Setting or disabling tile size limits

Temporary storage

Progress indicator

Filters

The pre- and post-filter commands allow you to do optional filtering or transformation on the features of each tile as it is created. They are shell commands, run with the zoom level, X, and Y as the $1, $2, and $3 arguments. Future versions of Tippecanoe may add additional arguments for more context.

The features are provided to the filter as a series of newline-delimited GeoJSON objects on the standard input, and tippecanoe expects to read another set of GeoJSON features from the filter's standard output.

The prefilter receives the features at the highest available resolution, before line simplification, polygon topology repair, gamma calculation, dynamic feature dropping, or other internal processing. The postfilter receives the features at tile resolution, after simplification, cleaning, and dropping.

The layer name is provided as part of the tippecanoe element of the feature and must be passed through to keep the feature in its correct layer. In the case of the prefilter, the tippecanoe element may also contain index, sequence, extent, and dropped, elements, which must be passed through for internal operations like --drop-densest-as-needed, --drop-smallest-as-needed, and --preserve-input-order to work.

Examples:

tippecanoe -o countries.mbtiles -z5 -C 'mkdir -p tiles/$1/$2; tee tiles/$1/$2/$3.geojson' ne_10m_admin_0_countries.json
tippecanoe -o countries.mbtiles -z5 -C './filters/limit-tiles-to-bbox 5.8662 47.2702 15.0421 55.0581 $*' ne_10m_admin_0_countries.json
tippecanoe -o roads.mbtiles -c 'if [ $1 -lt 11 ]; then grep "\"MTFCC\": \"S1[12]00\""; else cat; fi' tl_2016_18157_roads.json

Environment

Tippecanoe ordinarily uses as many parallel threads as the operating system claims that CPUs are available. You can override this number by setting the TIPPECANOE_MAX_THREADS environmental variable.

GeoJSON extension

Tippecanoe defines a GeoJSON extension that you can use to specify the minimum and/or maximum zoom level at which an individual feature will be included in the vector tileset being produced. If you have a feature like this:

{
    "type" : "Feature",
    "tippecanoe" : { "maxzoom" : 9, "minzoom" : 4 },
    "properties" : { "FULLNAME" : "N Vasco Rd" },
    "geometry" : {
        "type" : "LineString",
        "coordinates" : [ [ -121.733350, 37.767671 ], [ -121.733600, 37.767483 ], [ -121.733131, 37.766952 ] ]
    }
}

with a tippecanoe object specifiying a maxzoom of 9 and a minzoom of 4, the feature will only appear in the vector tiles for zoom levels 4 through 9. Note that the tippecanoe object belongs to the Feature, not to its properties. If you specify a minzoom for a feature, it will be preserved down to that zoom level even if dot-dropping with -r would otherwise have dropped it.

You can also specify a layer name in the tippecanoe object, which will take precedence over the filename or name specified using --layer, like this:

{
    "type" : "Feature",
    "tippecanoe" : { "layer" : "streets" },
    "properties" : { "FULLNAME" : "N Vasco Rd" },
    "geometry" : {
        "type" : "LineString",
        "coordinates" : [ [ -121.733350, 37.767671 ], [ -121.733600, 37.767483 ], [ -121.733131, 37.766952 ] ]
    }
}

If your source GeoJSON only has minzoom, maxzoom and/or layer within properties you can use ndjson-cli to move them into the required tippecanoe object by piping the GeoJSON like this:

ndjson-map 'd.tippecanoe = { minzoom: d.properties.minzoom, maxzoom: d.properties.maxzoom, layer: d.properties.layer }, delete d.properties.minzoom, delete d.properties.maxzoom, delete d.properties.layer, d'

Geometric simplifications

At every zoom level, line and polygon features are subjected to Douglas-Peucker simplification to the resolution of the tile.

For point features, it drops 1/2.5 of the dots for each zoom level above the point base zoom (which is normally the same as the -z max zoom, but can be a different zoom specified with -B if you have precise but sparse data). I don't know why 2.5 is the appropriate number, but the densities of many different data sets fall off at about this same rate. You can use -r to specify a different rate.

You can use the gamma option to thin out especially dense clusters of points. For any area where dots are closer than one pixel together (at whatever zoom level), a gamma of 3, for example, will reduce these clusters to the cube root of their original density.

For line features, it drops any features that are too small to draw at all. This still leaves the lower zooms too dark (and too dense for the 500K tile limit, in some places), so I need to figure out an equitable way to throw features away.

Unless you specify --no-tiny-polygon-reduction, any polygons that are smaller than a minimum area (currently 4 square subpixels) will have their probability diffused, so that some of them will be drawn as a square of this minimum size and others will not be drawn at all, preserving the total area that all of them should have had together.

Features in the same tile that share the same type and attributes are coalesced together into a single geometry if you use --coalesce. You are strongly encouraged to use -x to exclude any unnecessary attributes to reduce wasted file size.

If a tile is larger than 500K, it will try encoding that tile at progressively lower resolutions before failing if it still doesn't fit.

Development

Requires sqlite3 and zlib (should already be installed on MacOS). Rebuilding the manpage uses md2man (gem install md2man).

Linux:

sudo apt-get install build-essential libsqlite3-dev zlib1g-dev

Then build:

make

and perhaps

make install

Tippecanoe now requires features from the 2011 C++ standard. If your compiler is older than that, you will need to install a newer one. On MacOS, updating to the lastest XCode should get you a new enough version of clang++. On Linux, you should be able to upgrade g++ with

sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
sudo apt-get update -y
sudo apt-get install -y g++-5
export CXX=g++-5

Docker Image

A tippecanoe Docker image can be built from source and executed as a task to automatically install dependencies and allow tippecanoe to run on any system supported by Docker.

$ docker build -t tippecanoe:latest .
$ docker run -it --rm \
  -v /tiledata:/data \
  tippecanoe:latest \
  tippecanoe --output=/data/output.mbtiles /data/example.geojson

The commands above will build a Docker image from the source and compile the latest version. The image supports all tippecanoe flags and options.

Examples

Check out some examples of maps made with tippecanoe

Name

The name is a joking reference to a "tiler" for making map tiles.

tile-join

Tile-join is a tool for copying and merging vector mbtiles files and for joining new attributes from a CSV file to existing features in them.

It reads the tiles from an existing .mbtiles file or a directory of tiles, matches them against the records of the CSV (if one is specified), and writes out a new tileset.

If you specify multiple source mbtiles files or source directories of tiles, all the sources are read and their combined contents are written to the new mbtiles output. If they define the same layers or the same tiles, the layers or tiles are merged.

The options are:

Output tileset

Tileset description and attribution

Layer filtering and naming

Zoom levels

Merging attributes from a CSV file

Filtering features and feature attributes

Setting or disabling tile size limits

Because tile-join just copies the geometries to the new .mbtiles without processing them (except to rescale the extents if necessary), it doesn't have any of tippecanoe's recourses if the new tiles are bigger than the 500K tile limit. If a tile is too big and you haven't specified -pk, it is just left out of the new tileset.

Example

Imagine you have a tileset of census blocks:

curl -L -O http://www2.census.gov/geo/tiger/TIGER2010/TABBLOCK/2010/tl_2010_06001_tabblock10.zip
unzip tl_2010_06001_tabblock10.zip
ogr2ogr -f GeoJSON tl_2010_06001_tabblock10.json tl_2010_06001_tabblock10.shp
./tippecanoe -o tl_2010_06001_tabblock10.mbtiles tl_2010_06001_tabblock10.json

and a CSV of their populations:

curl -L -O http://www2.census.gov/census_2010/01-Redistricting_File--PL_94-171/California/ca2010.pl.zip
unzip -p ca2010.pl.zip cageo2010.pl |
awk 'BEGIN {
    print "GEOID10,population"
}
(substr($0, 9, 3) == "750") {
    print "\"" substr($0, 28, 2) substr($0, 30, 3) substr($0, 55, 6) substr($0, 62, 4) "\"," (0 + substr($0, 328, 9))
}' > population.csv

which looks like this:

GEOID10,population
"060014277003018",0
"060014283014046",0
"060014284001020",0
...
"060014507501001",202
"060014507501002",119
"060014507501003",193
"060014507501004",85
...

Then you can join those populations to the geometries and discard the no-longer-needed ID field:

./tile-join -o population.mbtiles -x GEOID10 -c population.csv tl_2010_06001_tabblock10.mbtiles

tippecanoe-enumerate

The tippecanoe-enumerate utility lists the tiles that an mbtiles file defines. Each line of the output lists the name of the mbtiles file and the zoom, x, and y coordinates of one of the tiles. It does basically the same thing as

select zoom_level, tile_column, (1 << zoom_level) - 1 - tile_row from tiles;

on the file in sqlite3.

tippecanoe-decode

The tippecanoe-decode utility turns vector mbtiles back to GeoJSON. You can use it either on an entire file:

tippecanoe-decode file.mbtiles

or on an individual tile:

tippecanoe-decode file.mbtiles zoom x y
tippecanoe-decode file.vector.pbf zoom x y

Unless you use -c, the output is a set of nested FeatureCollections identifying each tile and layer separately. Note that the same features generally appear at all zooms, so the output for the file will have many copies of the same features at different resolutions.

Options

tippecanoe-json-tool

Extracts GeoJSON features or standalone geometries as line-delimited JSON objects from a larger JSON file, following the same extraction rules that Tippecanoe uses when parsing JSON.

tippecanoe-json-tool file.json [... file.json]

Optionally also wraps them in a FeatureCollection or GeometryCollection as appropriate.

Optionally extracts an attribute from the GeoJSON properties for sorting.

Optionally joins a sorted CSV of new attributes to a sorted GeoJSON file.

The reason for requiring sorting is so that it is possible to work on CSV and GeoJSON files that are larger than can comfortably fit in memory by streaming through them in parallel, in the same way that the Unix join command does. The Unix sort command can be used to sort large files to prepare them for joining.

The sorting interface is weird, and future version of tippecanoe-json-tool will replace it with something better.

Options

Example

Join Census LEHD (Longitudinal Employer-Household Dynamics) employment data to a file of Census block geography for Tippecanoe County, Indiana.

Download Census block geometry, and convert to GeoJSON:

$ curl -L -O https://www2.census.gov/geo/tiger/TIGER2010/TABBLOCK/2010/tl_2010_18157_tabblock10.zip
$ unzip tl_2010_18157_tabblock10.zip
$ ogr2ogr -f GeoJSON tl_2010_18157_tabblock10.json tl_2010_18157_tabblock10.shp

Download Indiana employment data, and fix name of join key in header

$ curl -L -O https://lehd.ces.census.gov/data/lodes/LODES7/in/wac/in_wac_S000_JT00_2015.csv.gz
$ gzip -dc in_wac_S000_JT00_2015.csv.gz | sed '1s/w_geocode/GEOID10/' > in_wac_S000_JT00_2015.csv

Sort GeoJSON block geometry so it is ordered by block ID. If you don't do this, you will get a "GeoJSON file is out of sort" error.

$ tippecanoe-json-tool -e GEOID10 tl_2010_18157_tabblock10.json | LC_ALL=C sort > tl_2010_18157_tabblock10.sort.json

Join block geometries to employment attributes:

$ tippecanoe-json-tool -c in_wac_S000_JT00_2015.csv tl_2010_18157_tabblock10.sort.json > blocks-wac.json