If you have worked with geographic data on the web, you have almost certainly used GeoJSON. It is the de-facto standard for exchanging vector features between web maps, APIs, and GIS tools. TopoJSON is less well-known, but for certain use cases — especially D3-based data visualizations — it is dramatically more efficient. This guide explains how the two formats differ, when each shines, and how to move between them.

Quick Answer

If you need a fast comparison before diving into details, here it is:

Feature	GeoJSON	TopoJSON
Base format	JSON	JSON
Coordinate storage	Explicit per feature	Shared arcs (topology)
File size	Baseline	Typically 60–80% smaller
Topology awareness	None	Yes — shared borders encoded once
Browser support	Universal	Requires topojson-client library
Best mapping library	Leaflet, Mapbox, OpenLayers, QGIS, everything	Primarily D3.js
Created by	IETF (RFC 7946)	Mike Bostock (D3.js author)
Use case	General-purpose, APIs, data exchange	Compact static maps, D3 visualizations

In short: GeoJSON is simple and universally supported; TopoJSON is compact, topology-aware, and purpose-built for efficient web mapping where file size matters.

What Is GeoJSON?

GeoJSON is an open standard for encoding geographic data structures using JSON. It was formalized as RFC 7946 by the IETF in 2016, though the format had been in wide use for years before that. A GeoJSON document is built around three core concepts:

Geometry — the spatial shape: Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, or GeometryCollection.
Feature — a geometry paired with an arbitrary set of properties (name, population, category, etc.).
FeatureCollection — a list of Feature objects, which is the most common top-level structure you will encounter.

Coordinates are always in WGS 84 longitude/latitude (EPSG:4326) per the spec. Every polygon, every line, every point stores its own full coordinate list. That simplicity is exactly what makes GeoJSON so easy to work with: you can open it in a text editor, paste it into the GeoDataTools viewer, or hand it directly to Leaflet or Mapbox GL JS with zero transformation.

Universal support is the defining strength of GeoJSON. PostGIS, QGIS, Mapbox, Leaflet, OpenLayers, Esri products, Python's shapely and geopandas, and virtually every modern GIS tool can read and write GeoJSON without plugins or conversion steps. If you are exchanging geodata between systems, GeoJSON is almost always the right choice.

What Is TopoJSON?

TopoJSON is an extension of GeoJSON created by Mike Bostock — the author of D3.js — and first released in 2012. The key insight behind TopoJSON is that many geographic datasets contain shared borders. In a map of US counties, every county boundary that separates two adjacent counties is stored twice in GeoJSON: once for each feature. TopoJSON eliminates this duplication by encoding geometry as a topology of shared arcs rather than as independent coordinate lists.

Instead of each polygon owning its vertices outright, a TopoJSON file contains a flat array of arcs (sequences of delta-encoded coordinates), and each geometry references the arc indices it is composed of. Arcs can be shared between multiple geometries, and the direction of traversal (forward or reverse, indicated by a negative index) determines which side of the border belongs to which polygon.

This architecture delivers two major benefits:

Smaller files — shared borders are stored only once, and delta encoding (storing the difference between successive coordinates rather than absolute values) compresses well under gzip.
Topology preservation — because adjacent polygons share the exact same arc, simplification operations (reducing vertex count) never create gaps or overlaps along shared borders. This is a significant advantage for cartographic simplification compared to simplifying GeoJSON geometries independently.

The trade-off is complexity: a TopoJSON file cannot be rendered directly by most mapping libraries. You must first decode it back into GeoJSON using the topojson-client JavaScript library, adding a dependency and a decode step to your pipeline.

File Size Comparison

The size difference between GeoJSON and TopoJSON is not marginal — it is substantial and consistent across different datasets. A classic benchmark is the US counties dataset:

Dataset	GeoJSON (gzipped)	TopoJSON (gzipped)	Reduction
US counties (3,000+ polygons)	~100 KB	~25 KB	75%
World countries (medium resolution)	~180 KB	~40 KB	78%
US states	~30 KB	~8 KB	73%

Why is TopoJSON so much smaller? Three reasons compound each other:

Shared arcs — in the counties dataset, the vast majority of border segments are shared between two counties. Storing each arc once instead of twice immediately halves the coordinate data for those shared edges.
Delta encoding — TopoJSON stores coordinate differences from the previous point rather than absolute longitude/latitude values. Small integer deltas compress far better than full floating-point coordinates.
Quantization — the geo2topo tool quantizes coordinates to a fixed integer grid (e.g., 1e4 or 1e6 units), trading sub-pixel precision for smaller numbers that compress better without any visible quality loss at normal map zoom levels.

For bandwidth-sensitive applications — mobile web maps, slow connections, or pages that load many map layers — this reduction translates directly to faster load times and a better user experience.

Browser and Tool Support

GeoJSON enjoys essentially universal support across the entire geospatial ecosystem:

Web mapping: Mapbox GL JS, Leaflet, OpenLayers, Deck.gl, Cesium — all accept GeoJSON natively.
Desktop GIS: QGIS, ArcGIS Pro, GRASS GIS — all read and write GeoJSON out of the box.
Databases: PostGIS (ST_GeomFromGeoJSON), SQLite/SpatiaLite, MongoDB.
Server-side: GDAL/OGR, Turf.js, Shapely, GeoPandas — full support everywhere.
APIs: GitHub renders GeoJSON files as interactive maps; most public geodata APIs return GeoJSON.

TopoJSON support is much narrower:

D3.js — this is TopoJSON's primary home. The topojson-client package (the official decoder by Mike Bostock) integrates tightly with D3 and is the standard approach for D3 choropleth maps and cartographic projections.
Direct browser rendering — not possible without decoding first. You must call topojson.feature() or topojson.mesh() to convert arcs back to GeoJSON geometries before passing them to a rendering library.
QGIS / GDAL — GDAL 2.3+ includes a TopoJSON driver, so desktop GIS tools can open TopoJSON files, but this is less commonly used.
Node.js tooling — the topojson-server and topojson-client npm packages provide full encode/decode support.

The bottom line: if you are not using D3.js, TopoJSON offers little benefit and adds friction. If you are building D3 visualizations, it is the standard choice. You can explore and inspect both formats using the all tools available on GeoDataTools.

When to Use TopoJSON

TopoJSON is the right choice in these specific scenarios:

D3.js choropleth maps — the canonical D3 mapping tutorial uses TopoJSON, and the entire D3 mapping ecosystem is built around it. If you are following D3 patterns for choropleth maps, statistical maps, or cartograms, TopoJSON is standard practice.
Bandwidth-constrained environments — mobile-first applications, maps served in regions with slow internet, or pages that must load quickly benefit significantly from 70–80% smaller payloads. The decode cost of topojson-client is negligible compared to the network savings.
Adjacent polygon maps requiring clean borders — when you need to simplify a polygon dataset (reduce vertex count to decrease file size further), TopoJSON-aware simplification tools like topojson-simplify guarantee that shared borders remain topologically consistent. Simplifying GeoJSON without topology can introduce gaps and overlaps between neighboring polygons — a common problem when you simplify GeoJSON without topology awareness.
Static reference datasets — country boundaries, administrative divisions, census geographies, and other datasets that are prepared once and served many times are ideal candidates for TopoJSON encoding. The one-time encode cost is easily justified.
Server-side tile pre-processing — when pre-computing map tiles or building a static site generator pipeline, encoding to TopoJSON reduces CDN storage and egress costs.

Conversely, avoid TopoJSON when building REST APIs that need to interoperate with many different clients, when your mapping library is not D3, or when your team needs to inspect or debug the raw geodata easily — GeoJSON is far more readable in its raw form.

Converting Between Formats

Converting GeoJSON to TopoJSON and back is straightforward with the official command-line tooling from the topojson npm package suite.

GeoJSON to TopoJSON using geo2topo:

npx geo2topo counties=counties.geojson -o counties.topojson

The counties= prefix assigns the object name inside the TopoJSON file, which you reference when decoding. You can pass multiple input files to merge them into a single topology, which is useful for combining states and counties into one file.

TopoJSON back to GeoJSON using topo2geo:

npx topo2geo counties=counties.geojson < counties.topojson

Simplifying during conversion:

npx geo2topo counties=counties.geojson | npx toposimplify -p 0.0001 -f | npx topo2geo counties=simplified.geojson

The -p flag sets the planar area threshold for the Visvalingam simplification algorithm, and -f removes small rings. This pipeline produces a GeoJSON that is simplified without gaps at shared borders — something you cannot reliably achieve by simplifying GeoJSON directly.

In JavaScript, decoding TopoJSON at runtime with topojson-client:

import * as topojson from 'topojson-client';

fetch('counties.topojson')
  .then(r => r.json())
  .then(topology => {
    const geojson = topojson.feature(topology, topology.objects.counties);
    // geojson is now a standard GeoJSON FeatureCollection
  });

The GeoDataTools team is actively evaluating TopoJSON support for the GeoDataTools viewer, which would allow drag-and-drop TopoJSON import, automatic decoding, and export back to GeoJSON or other formats directly in the browser — no command-line tools required.

Whether you are working with GeoJSON today or exploring TopoJSON for your next D3 visualization, understanding both formats gives you the flexibility to choose the right tool for each job in your geospatial workflow.

TopoJSON vs GeoJSON: What's the Difference and When to Use Each