TopoJSON
GeoJSON's topology-aware cousin — smaller files for adjacent polygons.
- Specification
- TopoJSON Specification 1.0
- Released
- 2012 (Mike Bostock)
- When to use
- Use TopoJSON when you have many adjacent polygons that share long boundaries — country and state outlines, electoral districts, watershed basins — and the duplicated coordinates in equivalent GeoJSON inflate the file. The format is also a natural fit when used together with D3.js, which has first-class support. For non-adjacent features or simple point datasets, the savings vanish and plain GeoJSON is simpler.
What is TopoJSON?
TopoJSON, designed by Mike Bostock in 2012, is an extension of GeoJSON that encodes topology: shared boundaries between adjacent polygons are stored exactly once as 'arcs', and each geometry references arcs by integer index rather than repeating coordinates. The root object has a fixed type of 'Topology' and contains an arcs array (the shared coordinate streams), an objects map (each entry a named GeometryCollection referencing arcs), and an optional transform (a scale and translate pair that quantises coordinates to integers for further compression). The format typically achieves 60–80% size reduction compared to equivalent GeoJSON for political-boundary datasets, and quantisation can push the savings further at the cost of small geometric simplification. The trade-off is that consumers must reconstruct geometries by following arc references — the topojson-client library does this in the browser, returning standard GeoJSON FeatureCollections suitable for any mapping library. TopoJSON is not an OGC standard; it is a community specification, and its support outside the D3/web-mapping world is limited.
Supported by
- D3.js (first-class via d3-geo + topojson-client)
- QGIS (read/write since 3.x)
- GDAL/OGR (driver: TopoJSON, read-only in older versions)
- Mapshaper (excellent topology-aware editor)
- ogr2ogr (export, conversion)
- topojson-server / topojson-client npm packages
- Observable notebooks
Strengths
- 60–80% smaller than equivalent GeoJSON for adjacent polygons
- Topology preserved — shared boundaries are guaranteed to match exactly
- Quantisation offers additional lossy compression with control
- First-class D3.js support
- Plain JSON, no binary parsing required
Weaknesses
- Not an OGC standard; ecosystem smaller than GeoJSON
- Desktop GIS support is uneven (good in QGIS, weak elsewhere)
- Must reconstruct geometries before rendering — extra client-side step
- Quantisation introduces controlled geometric error
- Savings disappear for point-only datasets
- Limited writer tooling outside the JavaScript ecosystem
Converters for TopoJSON
Convert FROM TopoJSON
Convert TO TopoJSON
Validator
TopoJSON Validator
Validate a TopoJSON file for topology structure, arc definitions, and object geometry references.
Frequently Asked Questions
How does TopoJSON achieve smaller file sizes?
Two mechanisms: arc sharing and coordinate quantisation. Arc sharing means a boundary between two polygons (say, the border between Germany and Poland) is stored once and referenced twice, instead of being duplicated as in GeoJSON. Quantisation maps floating-point coordinates onto an integer grid with a single transform scale/translate, replacing 8-byte doubles with 2- or 4-byte ints.
Will my TopoJSON file render in Leaflet directly?
Not as-is. Leaflet expects GeoJSON. You need topojson-client to convert TopoJSON back to GeoJSON in the browser first, then pass the result to L.geoJSON(). The conversion is fast and the file you download from the server is still small.
Is quantisation lossy?
Yes, but controllably. A quantisation factor of 1e5 maps coordinates onto a 100,000-step grid per axis, which is roughly 1 metre precision at the equator. For visualisation that's invisible; for survey-grade work it's too coarse, so use higher factors or skip quantisation.
Can I edit TopoJSON in QGIS?
QGIS will open TopoJSON and let you edit it like any other vector layer. However, edits are usually saved back as GeoJSON or another format because QGIS treats the topology as a one-way decoding. For round-tripping topology-aware edits, use Mapshaper.
When should I prefer GeoJSON over TopoJSON?
For point datasets (no shared boundaries to encode), for small files where the GeoJSON overhead is negligible, for tools that don't speak TopoJSON, and for situations where you want plain features without an extra client-side decoding step.