Skip to main content

TopoJSON Format

Read TopoJSON topologies as GeoJSON-like features (when topojson is installed); write buffered geometries as a Topology on close.

Overview​

PropertyValue
Format idtopojson
ClassTopoJSONIterable
Extensions.topojson
ReadYes
WriteYes
Extratopojson (topojson)
Maturitystable

File Extensions​

  • .topojson — TopoJSON topology documents

Implementation Details​

Reading​

  • Small files: json.load, then (if topojson is installed) convert topology objects to GeoJSON features
  • Large files (> ~10MB) or non-seekable streams: optional ijson streaming over objects.item (raw topology objects; full Topology→GeoJSON conversion needs the whole file)
  • Without the topojson library, yields the raw topology structure

Writing​

  • Buffers geometry dicts in memory
  • On close(), writes a single Topology with a GeometryCollection under objects.collection
  • Nested write uses JSON text encoding

Key Features​

  • Read and write
  • Optional conversion: TopoJSON → GeoJSON features when the library is present
  • Streaming fallback: ijson for large files (raw objects)

Usage​

from iterable import open_iterable

with open_iterable("map.topojson") as source:
    for feature in source:
        print(feature.get("type"), feature.get("geometry"))

with open_iterable("out.topojson", mode="w") as dest:
    dest.write({"type": "Point", "coordinates": [0.0, 0.0]})
    dest.write({"type": "Point", "coordinates": [1.0, 1.0]})

Parameters​

ParameterTypeDefaultRequiredDescription
encodingstr'utf8'NoText encoding for the JSON document

Error Handling​

  • FormatParseError: Invalid JSON TopoJSON document
  • ImportError: Optional — full GeoJSON conversion needs topojson (pip install iterabledata[topojson]); reading raw topology still works without it for small files
  • FileNotFoundError: Path is wrong or the file is missing
  • Corrupt streaming input may fall back to non-streaming load or raise parse errors

See Troubleshooting for more help.

Installation​

pip install 'iterabledata[topojson]'

For large-file streaming reads, also install ijson (included in the json extra): pip install iterabledata[json].

Limitations​

  1. Write buffers until close — one Topology document per file
  2. Streaming reads skip full Topology→GeoJSON conversion
  3. Optional topojson library for feature conversion