TopoJSON vs. GeoJSON: When and Why to Use TopoJSON

What Is TopoJSON?

TopoJSON is an extension of GeoJSON developed by Mike Bostock (creator of D3.js). While GeoJSON represents each geographic feature independently with its own geometry, TopoJSON encodes topology — the shared boundaries and relationships between adjacent features are stored only once, dramatically reducing file size and enabling new analytical possibilities.

The Core Difference: Topology vs. Geometry

In GeoJSON, if France and Germany share a border, that border segment is stored twice — once in France's polygon coordinates and once in Germany's. For a dataset of all world countries, every shared border is duplicated.

In TopoJSON, shared line segments (called arcs) are stored in a central arcs array. Each geometry then references those arcs by index rather than repeating coordinates. This means a shared border is stored exactly once, regardless of how many features use it.

How Much Smaller Is TopoJSON?

The size reduction depends on the dataset, but for political boundary data with many shared borders, TopoJSON files are typically 60–80% smaller than equivalent GeoJSON files. For example, a detailed world countries GeoJSON at 700 KB might compress to under 150 KB as TopoJSON.

Additionally, TopoJSON files compress extremely well with gzip because the arc structure is highly repetitive, so gzipped TopoJSON can be remarkably compact for browser delivery.

TopoJSON File Structure

A TopoJSON object looks quite different from GeoJSON:

{
  "type": "Topology",
  "objects": {
    "countries": {
      "type": "GeometryCollection",
      "geometries": [
        {
          "type": "Polygon",
          "arcs": [[0, 1, 2]],
          "properties": { "name": "France" }
        }
      ]
    }
  },
  "arcs": [
    [[100, 0], [50, 50], [0, 100]],
    [[0, 100], [100, 200]],
    [[100, 200], [100, 0]]
  ],
  "transform": {
    "scale": [0.001, 0.001],
    "translate": [-180, -90]
  }
}

Key structural elements:

• objects: Named layers of geometry collections (you can have multiple layers in one file).
• arcs: The shared coordinate sequences, stored as delta-encoded integers (relative to the previous point) after quantization.
• transform: A scale and translate used to convert quantized integer coordinates back to real-world values.

Quantization and Simplification

TopoJSON uses quantization — converting floating-point coordinates to integers on a fixed grid — which both reduces precision (in a controlled way) and enables delta encoding for further compression. The default quantization of 10,000 is fine for most web maps; increase it if you need sub-meter precision.

Because TopoJSON understands shared boundaries, it can also simplify geometries while preserving topological consistency — adjacent polygons continue to share clean borders even after simplification, without gaps or overlaps. This is something GeoJSON simplification tools cannot guarantee.

Working with TopoJSON

Converting GeoJSON to TopoJSON

The official command-line tool is topojson (via npm):

# Install
npm install -g topojson

# Convert
geo2topo countries.geojson > countries.topojson

# With quantization and simplification
geo2topo -q 10000 countries.geojson | toposimplify -p 0.001 > simplified.topojson

Using TopoJSON in the Browser

To render TopoJSON in Leaflet or Mapbox GL JS, you first convert it back to GeoJSON using the topojson-client library:

import * as topojson from 'topojson-client';

const response = await fetch('countries.topojson');
const topology = await response.json();

// Convert a named object back to a GeoJSON FeatureCollection
const geojson = topojson.feature(topology, topology.objects.countries);

// Use with Leaflet
L.geoJSON(geojson).addTo(map);

Merging and Meshing

TopoJSON's topological awareness enables two powerful operations:

• topojson.merge(topology, geometries) — dissolves shared borders between selected features, creating a union polygon. Great for building region aggregations.
• topojson.mesh(topology, object, filter) — extracts just the boundary lines (e.g., only interior borders between countries, not coastlines), useful for lightweight border overlays.

Comparison Summary

	GeoJSON	TopoJSON
File size	Larger	60–80% smaller
Human-readable	Easily	Harder to read raw
Browser support	Native	Requires topojson-client
Topology-aware simplification	No	Yes
Multiple layers in one file	No	Yes
Best for	APIs, general use	Data visualization, D3.js

When to Use TopoJSON

• You're building a D3.js data visualization with political boundaries or choropleth maps.
• File size is a concern — you're serving large boundary datasets over the web.
• You need to dissolve or merge adjacent features programmatically (e.g., aggregate counties into states).
• You want topologically consistent simplification without gaps between polygons.

For general-purpose APIs, mobile apps, and server-side data exchange, GeoJSON remains the better default. But for sophisticated cartographic web applications, TopoJSON is an invaluable tool.