chillgis / topojson

Convert GeoJSON to TopoJSON for smaller files and the power of topology! 🌐

TopoJSON

TopoJSON is an extension of GeoJSON that encodes topology. Rather than representing geometries discretely, geometries in TopoJSON files are stitched together from shared line segments called arcs. This technique is similar to Matt Bloch’s MapShaper and the Arc/Info Export format, .e00.

TopoJSON eliminates redundancy, allowing related geometries to be stored efficiently in the same file. For example, the shared boundary between California and Nevada is represented only once, rather than being duplicated for both states. A single TopoJSON file can contain multiple feature collections without duplication, such as states and counties. Or, a TopoJSON file can efficiently represent both polygons (for fill) and boundaries (for stroke) as two feature collections that share the same arc mesh. See How To Infer Topology for a visual explanation of how TopoJSON works.

To further reduce file size, TopoJSON can use quantized delta-encoding for integer coordinates. This is similar to rounding coordinate values (e.g., LilJSON), but with greater efficiency and control over loss of information. And like GeoJSON, TopoJSON files are easily modified in a text editor and amenable to gzip compression.

As a result, TopoJSON is substantially more compact than GeoJSON, frequently offering a reduction of 80% or more even without simplification. Yet encoding topology also has numerous useful applications for maps and visualization above! It allows topology-preserving shape simplification, which ensures that adjacent features remain connected after simplification; this applies even across feature collections, such as simultaneous consistent simplification of state and county boundaries. Topology can also be used for Dorling or hexagonal cartograms, as well as other techniques that need shared boundary information such as automatic map coloring.

See also:

• topojson-client
• topojson-simplify
• topojson-specification

Installing

If you use NPM, npm install topojson. Otherwise, download the latest release. You can also load directly from unpkg. AMD, CommonJS, and vanilla environments are supported. In vanilla, a topojson global is exported:

<script src="https://unpkg.com/topojson@2"></script>
<script>

var topology = topojson.topology({foo: geojson});

</script>

Try topojson in your browser.

API Reference

# topojson.topology(objects[, quantization])

Converts the specified GeoJSON objects to TopoJSON. The input objects are modified in-place and should not be referenced after calling this method; this is a destructive operation!

If a quantization parameter is specified, the input geometry is quantized prior to computing the topology, and the returned topology is quantized, and its arcs are delta-encoded. Quantization is recommended to improve the quality of the topology if the input geometry is messy (i.e., small floating point error means that adjacent boundaries do not have identical values); typical values are powers of ten, such as 1e4, 1e5 or 1e6. See also topojson.quantize to quantize a topology after it has been constructed, without altering the topological relationships.

Command-Line Reference

geo2topo

# geo2topo [options…] <name=file>… <>

Converts one or more GeoJSON objects to an output topology. For example, to convert the us-states.json GeoJSON FeatureCollection to a TopologyJSON topology with the “states” object in us.json:

geo2topo states=us-states.json > us.json

For convenience, you can omit the object name and specify only the file name; the object name will be the basename of the file, with the directory and extension removed. For example, to convert the states.json GeoJSON FeatureCollection to a TopologyJSON topology with the “states” object in us.json:

geo2topo states.json > us.json

See also topo2geo.

# geo2topo -h
# geo2topo --help

Output usage information.

# geo2topo -V
# geo2topo --version

Output the version number.

# geo2topo -n
# geo2topo --newline-delimited

Output newline-delimited JSON, with one feature per line.

# geo2topo -i file
# geo2topo --in file

Specify the input TopoJSON file name. Defaults to “-” for stdin.

# geo2topo -l
# geo2topo --list

List the names of the objects in the input topology, and then exit. For example, this:

geo2topo -l < us.json

Will output this:

counties
states
nation