How does TopoJSON make files smaller?

TopoJSON stores boundaries shared between two shapes — like a border between adjacent countries — as a single arc referenced by both. GeoJSON repeats those coordinates in every feature, so eliminating the duplication plus delta encoding can dramatically shrink the file.

What does quantization do?

Quantization snaps every coordinate onto an integer grid of the chosen size, replacing floating-point longitudes and latitudes with small integers. Combined with delta encoding, where each point stores only its offset from the previous one, this produces short repetitive numbers that compress well.

Which geometry types are supported?

Point, MultiPoint, LineString, MultiLineString, Polygon, and MultiPolygon are supported. Points are stored directly in the topology; line and polygon rings are converted into the shared arc array.

Will the output match the d3 topojson library?

It follows the TopoJSON 1.0 specification — a topology object with arcs, transform, and named objects — so it round-trips through standard TopoJSON clients. Exact arc ordering may differ from topojson-server, but the decoded geometry is equivalent.

No. The entire topology build, including arc extraction and quantization, happens in your browser. Nothing is sent to any server.

What is the GeoJSON to TopoJSON Converter?

Encode a GeoJSON FeatureCollection as a TopoJSON topology, extracting line segments into a shared arc array and applying delta-encoded quantization to cut redundancy. Shows the compression ratio and gives downloadable TopoJSON. Runs entirely in your browser. It runs free in your browser on Gera Tools, with nothing uploaded.

GeoJSON to TopoJSON Converter

Name: GeoJSON to TopoJSON Converter
Creator: Gera Tools
License: https://creativecommons.org/licenses/by/4.0/

GeoJSON to TopoJSON Converter turns a GeoJSON file into the more compact TopoJSON format. TopoJSON encodes geometry as topology — shared boundaries are stored once as arcs and referenced by every shape that touches them — which removes the coordinate duplication that bloats GeoJSON. Paste your data, pick a quantization level, and get back a valid TopoJSON object with a reported size reduction, all without leaving your browser.

How it works

The converter runs three stages that mirror the TopoJSON specification:

Quantization. Every coordinate is mapped from its geographic range onto an integer grid of quantization × quantization cells. The mapping is stored in a transform object with scale and translate so the original values can be reconstructed.
Arc extraction. Each ring and line is broken into arcs. The tool deduplicates identical arc coordinate sequences so a border shared by two polygons becomes one entry in the arcs array, referenced by index from both features.
Delta encoding. Within each arc, only the first point is absolute; every following point stores the difference from the previous one. After quantization these deltas are small integers, which is what makes TopoJSON compress so well.

When TopoJSON compresses far better than GeoJSON

The savings depend heavily on how much shared geometry your data has:

High savings: administrative boundary datasets — country borders, state/province maps, county maps. Every shared border between two adjacent polygons appears once in the arc array instead of twice in the GeoJSON. A world countries file, for example, commonly shrinks by 80% or more.

Moderate savings: datasets with few shared borders, such as a set of non-adjacent points or disconnected polygons. Quantization and delta encoding still help, but without shared arcs the saving is smaller.

Minimal savings: datasets already stored as Points or single LineStrings, where there is no topology to exploit. A GeoJSON minifier with coordinate rounding is a better tool in this case.

Choosing a quantization level

Quantization controls how finely the coordinate grid is divided. The commonly used value 1e4 (10,000 cells per axis) is a practical default: it preserves enough detail for web-scale maps while keeping the integer deltas small. Use 1e5 if your map zooms to street level and detail matters. Use 1e3 when you are producing a small overview map where boundary accuracy at the pixel level is not important.

Using the output with D3 and Mapbox

The output follows the TopoJSON 1.0 specification. In D3, pass it to topojson.feature(topology, topology.objects.yourLayer) to recover GeoJSON for rendering. In Mapbox GL JS, convert it back to GeoJSON with the same library and add it as a source. The companion TopoJSON to GeoJSON tool on this site does that conversion without writing any code.

Tips and notes

Higher quantization (for example 1e5) preserves fine detail at the cost of larger numbers; lower values (like 1e3) compress harder but visibly coarsen boundaries. For maps that share long borders — administrative regions, country outlines — the savings are largest because those boundaries collapse to single arcs. The output is a standard TopoJSON topology, so you can decode it later with the companion TopoJSON to GeoJSON tool.