topojson

What it is and what it does

topojson is a Python library that converts spatial objects (geometries from shapely, GeoJSON, or GeoDataFrames) into TopoJSON format, a topology-aware encoding that dramatically reduces file size. It works by computing shared topology between features, encoding coordinates as fixed-precision integers, and optionally simplifying arcs using either Ramer–Douglas–Peucker or Visvalingam-Whyatt algorithms. The library depends on numpy for numerical operations, shapely for geometry handling, and packaging for version management.

You would use topojson when you need to compress geographic data for transmission, storage, or web visualization—particularly when serving maps or spatial datasets over the network where bandwidth matters. It maintains topological relationships during simplification, so adjacent polygons remain properly aligned after reduction. The library is designed for developers working with geographic information systems, web mapping, or data visualization pipelines.

Use it for:

• Reduce GeoJSON file sizes for web map applications before serving to browsers
• Compress spatial datasets for storage or archival while preserving topology
• Simplify polygon boundaries in geographic data while keeping adjacent regions aligned
• Convert shapely geometries to a compact format for data interchange or APIs
• Prepare geographic data for interactive visualization with tools like Altair

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

topojson encodes spatial data into TopoJSON format, a compressed topology representation that reduces file size by eliminating coordinate redundancy and applying fixed-precision integer encoding and arc simplification.

Yes, if you work with geographic data and need file compression. The library is stable (BSD licensed, no known vulnerabilities), has low install friction, and solves a real problem in geospatial workflows. The aging maintenance status (388 days since last release) is a minor concern for new features but not a blocker for core functionality. Install if you're already using shapely and need TopoJSON output; skip if you don't work with spatial data.

Install

topojson on PyPI

pip install topojson

uv add topojson

poetry add topojson

Installing topojson

Before you install

Low friction: pure Python wheel with three straightforward runtime dependencies (numpy, shapely, packaging). Last commit 2025-07-22 with 198 repository stars; maintenance status is aging (388 days since last release), so expect slower response to new issues.

License in practice

BSD permissive license allows commercial and private use with minimal restrictions, making it safe for most projects.

Quickstart

pip install topojson
import topojson
from shapely.geometry import Polygon

polygon = Polygon([(0, 0), (1, 0), (1, 1), (0, 1)])
topo = topojson.Topology(polygon)

Requires Python 3.8 or later; numpy and shapely must be installed and functional.

Verify before relying

• Actual compression ratios and typical file size reductions for real-world datasets
• Performance characteristics and scalability limits for large spatial datasets
• Compatibility with specific GeoJSON or shapely versions beyond the stated dependencies

Package facts

Evidence: topojson-1.10-py3-none-any.whl

Keywords: topojson, python, github, topology, geojson

Tags

More Scientific/Engineering packages