Gazetteer#

Public gazetteer query interface.

A Gazetteer wraps an installed artifact (a self-contained, read-only SQLite file) and exposes name search and identifier lookup over its features.

class Gazetteer(gazetteer_name: str)#

Bases: object

A gazetteer interface for querying geographic features.

This class provides access to an installed gazetteer artifact, allowing retrieval of candidate features for name matching using different search strategies: exact, phrase, partial, and fuzzy matching.

property crs: str#

Coordinate reference system of the gazetteer’s geometries.

find(identifier: str) → Feature | None#

Find a feature by its identifier.

Parameters:

identifier – The identifier value of the feature to find

Returns:

Feature object if found, None otherwise

search(name: str, method: str = 'exact', limit: int = 10000, tiers: int = 1) → List[Feature]#

Search for features using the specified search method.

Parameters:

  • name – Name string to search for

  • method – Search method to use (“exact”, “phrase”, “partial”, “fuzzy”)

  • limit – Maximum number of results to return (default: 10000)

  • tiers – Number of rank tiers to include in results (default: 1, ignored for exact method)

Returns:

List of Feature objects matching the search criteria

Raises:

ValueError – If an unknown search method is specified

Gazetteer builder: compiles a declarative config into a SQLite artifact.

The build pipeline has three stages, each its own progress group:

  1. Preparing sources: resolve (download/extract, cached across builds) and load each source’s file into a transient DuckDB table

  2. Compiling features: compile and run one projection per feature block, producing canonical (identifier, source, data, geometry) and (identifier, name) rows, then merge rows that share an identifier

  3. Building artifact: copy the compiled rows into a temporary SQLite file, build its search structures and metadata, then atomically move it into place

The staging database and all intermediate tables are discarded after the build; the artifact is the only output.

class GazetteerBuilder#

Bases: object

Builds gazetteer artifacts from declarative configuration files.

build(config_path: str | Path, keep_downloads: bool = False) → Path#

Build and install a gazetteer from a configuration file.

Parameters:

  • config_path – Path to the YAML configuration file

  • keep_downloads – Whether to keep downloaded files after the build

Returns:

Path of the installed artifact

uninstall(gazetteer_name: str) → bool#

Remove an installed gazetteer artifact.

Parameters:

gazetteer_name – Name of the gazetteer to remove

Returns:

True if an artifact was removed, False if none was installed