Skip to content

Topology Tools

DuckDB-powered geospatial topology utilities for cleaning and reconciling administrative boundary polygons, as a Python/CLI package and library.

Boundary cleaning

  1. Schema

    Map source columns to admin code and name columns, then apply the crosswalk.

  2. Topology

    Find gaps and overlaps between units, then clean them.

  3. Edge matching

    Fit units to a reference boundary so the outer edge follows the agreed outline.

  4. Codes

    Keep the previous release's codes for units that carry over, or cold-start codes when there is no previous release.

    old new

  5. Names

    Review names by hand: duplicates under the same parent, near-duplicate typos, blanks and placeholders, and encoding artifacts.

  6. Packaging

    Build per-level polygons, label points, and the boundary line network for release.

Each phase has a step-by-step guide, a tutorial, reference pages (what each tool does) and explanation pages (why it works that way).

Using with agents

  • Claude Code: install the plugin in VS Code or a terminal, then run it from Claude Code.

  • Other agents: paste one prompt into any agent that can read a URL. Nothing to install.

Installation

The boundary cleaning steps run the topo-tools CLI. Install it with:

uv tool install topo-tools   # CLI
uv add topo-tools            # Python library

pip install topo-tools       # CLI or library
pipx install topo-tools      # CLI

conda install -c conda-forge topo-tools   # CLI or library

Recommended on Windows. mamba and pixi install it from the same channel.

brew install OCHA-DAP/topo-tools/topo-tools

macOS/Linux, with no Python tooling required.

Inputs and outputs: GeoParquet, GeoPackage, Shapefile and GeoJSON. The output format matches the input format.

The tools are also available as a web app, which runs DuckDB in the browser: nothing to install, and files are processed locally.