TopoJSON · format guide

TopoJSON viewer

TopoJSON stores geometry as shared arcs rather than as independent polygons, which makes it roughly a fifth the size of the equivalent GeoJSON. MapCrafter converts topology on the client and renders the result, so a file whose borders would double-stroke in GeoJSON draws cleanly here.

What a TopoJSON file is

TopoJSON was designed by Mike Bostock to fix a specific waste in GeoJSON: when two countries share a border, GeoJSON stores that border twice, once in each country. At world scale that is a large fraction of the file. TopoJSON stores each arc once and has features reference them.

The saving is real. Natural Earth country boundaries at 1:110m are about 108 kB as TopoJSON and several times that as GeoJSON. For a web map that difference is the difference between a fast first paint and a slow one.

The trade is that TopoJSON is not directly renderable. It has to be converted back to GeoJSON before a map library will draw it, which is what MapCrafter does on the client. Practically, that means you can treat a TopoJSON file exactly like a GeoJSON file here.

What MapCrafter reads from it

A topology with one or more objects
Every drawable object is imported automatically as a layer
Quantised coordinates
The transform block is applied on conversion
Shared arcs
Converted so that adjacent polygons share an edge exactly, with no sliver between them
Properties on geometries
Carried through and usable for colour, labels and popups

Mapping a TopoJSON file, step by step

  1. 1

    Drop the .topojson or .json file in

    Every object in the topology is listed by name.

  2. 2

    Review the layers

    All drawable objects are imported. Hide overlapping land or boundary layers that you do not need.

  3. 3

    Style it

    As a fill for a choropleth, or as lines if the subject is the borders themselves.

  4. 4

    Export as GeoJSON

    The converted geometry exports cleanly if you need it in a tool that cannot read topology.

Things that go wrong with TopoJSON

Every one of these is a property of the format rather than a bug in a particular tool, which is why they keep happening.

  • A border appears twice as thick as the others.

    Adjacent polygons may both draw their common edge after conversion, and overlapping objects can add another outline. Hide duplicate layers or reduce outline width; shared arcs in the source do not guarantee a single rendered stroke.

  • Coordinates are enormous integers.

    Quantisation. The transform block holds scale and translate values that map integers back to degrees, and it has to be applied. MapCrafter applies it during conversion; a naive parser that skips it produces coordinates in the millions.

  • The geometry is in the wrong place after conversion.

    Check the topology-wide transform and source coordinate system. TopoJSON conversion applies scale and translation, but does not infer an unknown projected CRS.

  • Only one country rendered.

    Inspect the imported layer list and any warnings. All drawable objects are imported, but an object containing a single feature will still contain only that feature.

TopoJSON maps in the gallery

267 live maps built from TopoJSON data, each showing its source columns and the geometry that was detected.

TopoJSON questions

Can I view a TopoJSON file without converting it first?
Yes. The topology is converted in the browser and rendered directly. You do not need to run it through topojson-client or mapshaper beforehand.
Why is TopoJSON smaller than GeoJSON?
Because shared boundaries are stored once as arcs rather than once per polygon, and coordinates are stored as quantised integers rather than long decimals. For world boundaries the difference is typically a factor of four or five.
Does MapCrafter export TopoJSON?
No, it exports GeoJSON. TopoJSON is worth generating when you are publishing tiles or shipping a boundary file to a browser, and mapshaper or the topojson command line tools are the right instruments for that.

Other formats MapCrafter reads

Start with your own file

Last updated 2026-10-22.