Skip to content
Common Operational Datasets

Topology Tools

Topology Tools cleans and reconciles administrative boundary polygons, and comes in two forms that share the same steps. The web app on this site runs each tool in the browser, with nothing to install. The CLI and Python library documented here run the same steps with DuckDB on your own machine, for scripting, batch runs, and files too large for the browser.

Installation

Section titled “Installation”

Install the topo-tools CLI and Python library with:

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

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

Using with agents

Section titled “Using with agents”

Run the whole boundary cleaning workflow with an AI agent. The agent installs the CLI itself, so it skips the Installation step above.

  • 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.

Boundary cleaning

Section titled “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.
  5. Names: check names with name-detect and fix the safe problems (spacing, invisible characters, encoding) with name-clean; review the rest.
  6. Packaging: build per-level polygons, label points, and the boundary line network for release.

Each step except Names has a how-to guide and a reference page per tool, listing its options with examples. Names is a manual review checklist.