GeoJSON vs TopoJSON Comparison

What is TopoJSON?

TopoJSON is an extension of GeoJSON that encodes topology. Rather than storing each geometry as independent coordinates, TopoJSON eliminates redundancy by representing shared boundaries (called arcs) only once. It was created by Mike Bostock (creator of D3.js).

A TopoJSON file contains a topology object with:

• objects — named geometry collections (analogous to GeoJSON FeatureCollections)
• arcs — an array of coordinate sequences that geometries reference by index
• transform (optional) — quantization parameters for integer-encoded coordinates

GeoJSON{
  "type": "Topology",
  "objects": {
    "states": {
      "type": "GeometryCollection",
      "geometries": [
        { "type": "Polygon", "arcs": [[0, 1]] },
        { "type": "Polygon", "arcs": [[2, -1]] }
      ]
    }
  },
  "arcs": [
    [[0, 0], [1, 0], [1, 1]],
    [[1, 1], [0, 1], [0, 0]],
    [[1, 0], [2, 0], [2, 1], [1, 1]]
  ]
}

Notice how arc 1 and -1 (reversed) are shared between the two polygons — this is the shared boundary stored once.

Side-by-Side Comparison

File Size: Where TopoJSON Shines

TopoJSON's biggest advantage is file size reduction when geometries share boundaries. Consider a map of US states:

• GeoJSON: Every state stores its complete boundary, including borders shared with neighbors. The Kansas-Nebraska border is stored twice — once for each state.
• TopoJSON: The shared border is stored as a single arc, referenced by both states. With quantization, coordinates are further compressed into integers.

Real-world size comparisons:

For point data or non-adjacent geometries, TopoJSON offers minimal size savings since there are no shared boundaries to deduplicate.

Topology Preservation

Beyond file size, TopoJSON preserves topological relationships that GeoJSON discards:

• Shared boundaries stay aligned — when two polygons share an edge in TopoJSON, they always share the exact same arc. In GeoJSON, adjacent polygons might have slightly different coordinates along their shared border, causing gaps or overlaps.
• Merge and mesh operations — TopoJSON supports merging adjacent polygons (dissolving boundaries) and extracting shared boundaries (mesh) directly from the topology, without complex geometric operations.
• Consistent simplification — when you simplify a TopoJSON topology, shared boundaries simplify together, preventing gaps between adjacent polygons. Simplifying GeoJSON polygons independently often creates slivers.

When to Use GeoJSON

Choose GeoJSON when:

• Interoperability is priority — you need data consumed by multiple tools, APIs, or services. GeoJSON is universally supported.
• Working with point data — points don't share boundaries, so TopoJSON offers no topological advantage.
• Server-side processing — most GIS backends (PostGIS, Turf.js, GDAL) work natively with GeoJSON.
• Data exchange — APIs almost exclusively use GeoJSON. TopoJSON is rarely accepted as input.
• Real-time or streaming data — line-delimited GeoJSON supports streaming; TopoJSON does not.
• Editing workflows — modifying coordinates directly is straightforward in GeoJSON.

When to Use TopoJSON

Choose TopoJSON when:

• Serving map data to browsers — smaller files mean faster downloads and rendering, especially on mobile.
• Visualizing adjacent polygons — countries, states, counties, census tracts, and other administrative boundaries benefit most from topology.
• Using D3.js — D3 has first-class TopoJSON support with topojson-client for rendering and topojson-simplify for client-side simplification.
• Boundary operations — you need to merge regions, extract shared borders, or identify neighbors.
• Consistent simplification — you want to simplify complex polygons without creating gaps between neighbors.

Converting Between Formats

GeoJSON → TopoJSON (command line)

Shellnpx topojson-server geo2topo states=states.geojson > states.topojson

# With quantization for smaller output
npx topojson-server geo2topo -q 1e5 states=states.geojson > states.topojson

TopoJSON → GeoJSON (command line)

Shellnpx topojson-client topo2geo states=- < states.topojson > states.geojson

In JavaScript (browser)

JavaScriptimport * as topojson from "topojson-client";

// TopoJSON → GeoJSON FeatureCollection
const geojson = topojson.feature(topology, topology.objects.states);

// Extract shared boundaries as a mesh
const borders = topojson.mesh(topology, topology.objects.states,
  (a, b) => a !== b  // only internal borders
);

In Python

JavaScriptimport topojson

# GeoJSON → TopoJSON
tj = topojson.Topology(geojson_data, quantization=1e5)
tj.to_json()

# TopoJSON → GeoJSON
tj.to_geojson()

Quantization Explained

TopoJSON can quantize coordinates — converting floating-point lon/lat values into integers within a grid. A quantization factor of 1e5 means a 100,000 × 100,000 grid.

Benefits:

• Integers compress better than floats (smaller JSON)
• Delta-encoding of arcs further reduces size
• Precision loss is negligible for visualization (< 1 meter at 1e5)

Tradeoff: quantization is lossy. For analytical work requiring precise coordinates, convert back to GeoJSON.

Tips

• Start with GeoJSON for data processing, then convert to TopoJSON as a final optimization step for delivery to browsers.
• Use quantization wisely — 1e4 is sufficient for world maps, 1e5 for country-level, 1e6 for detailed local data.
• Don't use TopoJSON for APIs — serve GeoJSON from your API and let the client convert if needed.
• Combine with simplification — use topojson-simplify to reduce complexity while preserving shared boundaries.

Further Reading

• What is GeoJSON? — introduction to the GeoJSON format
• GeoJSON Specification Guide — detailed RFC 7946 breakdown
• GeoJSON Best Practices — tips for working with GeoJSON effectively