GeoJSON to TopoJSON Converter

TopoJSON to GeoJSON Converter (and Back)

This is a free, browser-based TopoJSON to GeoJSON converter — and a GeoJSON to TopoJSON converter — that lets you switch between the two formats in a single click while preserving topology. Drop in a .topojson or .json file, see the contained features rendered on a map, and export to either format. TopoJSON is the topology-preserving extension of GeoJSON popularised by Mike Bostock for D3.js maps; converting between the two is one of the most common tasks for anyone building data visualisations or trying to shrink a chunky GeoJSON file.

TopoJSON is dramatically more compact than GeoJSON for shared-boundary data because it stores each shared arc only once instead of duplicating coordinates in adjacent polygons. A US states GeoJSON might be 2 MB; the equivalent TopoJSON is often under 80 KB. That difference matters for web maps where every byte slows down page load.

How TopoJSON Encodes Topology

The key insight behind TopoJSON is that adjacent polygons share boundaries. In GeoJSON, the boundary between Pennsylvania and New York is stored twice — once in each state polygon — with identical coordinates. In TopoJSON, that boundary is stored once as an arc and both states reference it by index. Quantisation (snapping coordinates to a grid) and delta encoding shrink the file even further.

The converter walks the GeoJSON FeatureCollection, finds shared edges by hashing coordinate pairs, builds a deduplicated arc list, and rewrites every geometry as a sequence of arc indices. Going the other direction, it expands each arc reference back to full coordinates and emits a standard GeoJSON FeatureCollection.

Quantisation

Quantisation maps continuous coordinates onto an integer grid. A typical value of 1e4 snaps coordinates to roughly meter-scale precision; 1e6 keeps centimetre precision. Higher quantisation means smaller files but coarser geometry. The converter exposes this as a slider so you can balance fidelity against file size.

Topology-Preserving Simplification

One of TopoJSON's most useful tricks is that you can simplify the arcs (using a Visvalingam-Whyatt or Douglas-Peucker algorithm) and the simplified arcs remain shared between adjacent polygons. That means you can shrink a country boundary set without introducing slivers between provinces — a guarantee you don't get with naive GeoJSON simplification.

Practical Applications

D3.js Choropleth Maps

D3 was built around TopoJSON. Bostock's classic US choropleth examples use TopoJSON because the format makes it trivial to render state outlines, county outlines, and the merged national boundary from one small file.

Mobile and Embedded Web Maps

Mobile users on slow networks suffer when a page loads several megabytes of GeoJSON. Switching to TopoJSON often cuts payload size by 80% or more without sacrificing visual quality.

Choropleth Atlases

A static atlas of statistical maps — population, income, election results — typically needs the same boundary file rendered dozens of times. TopoJSON loaded once and reused across many SVGs is the standard pattern.

Election Reporting

News organisations publishing election results need state and county boundaries that load fast and remain crisp at multiple zoom levels. TopoJSON with topology-preserving simplification is the de facto choice.

Boundary Editing Workflows

When editing administrative boundaries (e.g., updating a school district) you want shared boundaries to update in lockstep. TopoJSON enforces that property by construction.

Static Site Cartography

Jekyll, Hugo, and other static site generators benefit from tiny embedded maps. A 60 KB TopoJSON loads almost instantly and renders cleanly on any device.

Step-by-Step Workflow in gis.tools

1. Open the GeoJSON to TopoJSON Converter page.
2. Drag your .json, .geojson, or .topojson file into the drop zone.
3. The converter detects the format and parses the file.
4. Set the quantisation level (start with 1e5 for typical web maps).
5. Optionally set a simplification threshold for topology-preserving generalisation.
6. Inspect the rendered preview to confirm geometry survived simplification.
7. Click Download TopoJSON (or Download GeoJSON if you started from TopoJSON).

Worked Example

A news developer is building an interactive map of US Congressional districts for an election dashboard. The source GeoJSON from the Census Bureau is 18 MB — far too large to bundle in a single web page. They drop it into the converter, set quantisation to 1e5, apply mild topology-preserving simplification, and download the result. The TopoJSON is 320 KB, a 56× reduction. State and district boundaries still align perfectly because shared arcs were simplified once and reused.

They load the TopoJSON in their D3 page, use topojson.feature to extract the districts as GeoJSON for D3 path generation, and topojson.merge to compute state outlines on the fly. The dashboard loads in under a second on mobile networks.

Common Pitfalls and Gotchas

• Over-quantisation — Setting quantisation too low (like 1e3) collapses fine geometry into chunky steps.
• Mixed CRS — TopoJSON, like GeoJSON, expects WGS84. Reproject before converting if your data is in another CRS.
• Self-intersecting polygons — Topology inference assumes valid input. Invalid polygons can produce malformed arcs.
• Floating-point precision — Two adjacent boundaries that look identical may differ in the 14th decimal place, defeating arc deduplication. Snap coordinates first.
• Large file size — Even TopoJSON has limits. A continental dataset at high precision can still be megabytes.
• GeoJSON-only consumers — Most web map libraries (Leaflet, MapLibre) prefer GeoJSON; you'll need to expand TopoJSON back at runtime with topojson-client.
• Property loss — Property data is preserved per object, but arc-level metadata (e.g., which is a coastline vs an internal boundary) is not native to the format.

Tips for Best Results

• Snap or round your coordinates before conversion to maximise arc deduplication.
• Use topology-preserving simplification rather than naive Douglas-Peucker.
• Start with quantisation 1e5 and tune from there.
• Verify shared boundaries between adjacent features stayed coincident after simplification.
• Use the GeoJSON Validator & Fixer on the GeoJSON before conversion to avoid topology surprises.
• Combine with the GeoJSON Simplifier for non-shared geometry.
• Keep a backup of your original GeoJSON in case you need higher precision later.

Comparison with Other GIS Approaches

Mike Bostock's topojson-server (Node CLI) is the canonical conversion tool, with topojson-client for the reverse. Mapshaper offers a friendly web UI for the same task. QGIS doesn't natively read or write TopoJSON. Online services exist but most upload your data to a server. The browser-based gis.tools converter sits in the same family as Mapshaper but focuses specifically on round-tripping with privacy and zero installation.

Performance Considerations

Topology inference is O(n log n) on the number of vertices because it uses hashing to find shared edges. A continent-scale dataset with millions of vertices takes a few seconds on a desktop browser. Memory usage during conversion can spike to several times the input size, so leave headroom.

Data Privacy and Browser-Based Processing

Every byte of your input stays on your device. Boundary files for sensitive territories — disputed regions, indigenous land, infrastructure assets — never leave your tab.

Related GIS Concepts

Arc — A shared linear feature in TopoJSON that may belong to multiple polygons. The fundamental unit of topology preservation.

Quantisation — Snapping continuous coordinates to a fixed grid to enable delta encoding and shrink file size.

Topology-Preserving Simplification — Generalisation that operates on arcs so adjacent features stay connected after vertex reduction.

Visvalingam-Whyatt — A simplification algorithm based on triangle areas, often preferred over Douglas-Peucker for cartographic generalisation.

Frequently Asked Questions

Will my GeoJSON properties survive the round trip?

Yes — properties are preserved per object in TopoJSON's objects field.

Why is my TopoJSON not much smaller than the original GeoJSON?

If your features don't share boundaries (e.g., a layer of unrelated points), TopoJSON offers little benefit. The savings come from shared edges.

Can I edit TopoJSON directly?

Not easily — the indexed arc format is awkward to hand-edit. Convert to GeoJSON, edit, then convert back.

What quantisation should I use?

For city-scale data, 1e6. For country-scale, 1e5. For continent-scale, 1e4.

Related Tools on gis.tools

• GeoJSON, KML, Shapefile & GIS File Viewer
• GeoJSON Validator & Fixer
• GeoJSON Simplifier
• Coordinate Precision Reducer
• Simplify Preserving Topology
• GIS Dissolve Tool (Merge by Field)
• Online Map Viewer (Multi-Layer)
• Metadata Generator