Gazetteer

class Gazetteer(gazetteer_name: str)

Bases: object

A gazetteer interface for querying geographic features.

This class provides access to gazetteer data stored in the local database, allowing retrieval of candidate features for name matching using different search strategies: exact, partial, and fuzzy matching.

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

class GazetteerInstaller

Bases: object

Orchestrates the complete gazetteer installation process.

This class coordinates a pipeline of stages that download, process, and load gazetteer data into the database. The pipeline follows a clear, linear flow:

  1. Acquisition: Download and extract source files

  2. Schema: Create database tables and views

  3. Ingestion: Load data into tables

  4. Transformation: Apply derivations and build geometries

  5. Indexing: Create database indices

  6. Registration: Register features and names

Each stage is independent and testable, with well-defined responsibilities and interfaces.

install(config_path: str | Path, chunksize: int = 20000, keep_downloads: bool = False) → None

Install a gazetteer from a YAML configuration file.

Parameters:

  • config_path – Path to the YAML configuration file

  • chunksize – Number of records to process at once for chunked operations

  • keep_downloads – Whether to keep downloaded files after installation

Raises:

Exception – If installation fails at any stage