Developer Interface

Matcher Class

class whereabouts.Matcher.Matcher(db_name: str, how: str = 'standard', threshold: float = 0.5)

A class for geocoding and reverse geocoding addresses.

con

A DuckDB database connection.

Type:

duckdb.DuckDBPyConnection

how

The geocoding algorithm to use, either ‘standard’, ‘trigram’, or ‘skipphrase’. Defaults to ‘standard’.

Type:

str

threshold

The threshold for considering a match valid. Defaults to 0.5.

Type:

float

close() → None

Close the underlying DuckDB connection.

geocode(addresses: list[str] | str | ndarray | Series, top_n: int = 1, address_ids: list[int] | None = None, how: str | None = None, verbose: bool = False) → list[dict]

Geocode a list of addresses.

Parameters:

  • addresses (list of str or str) – A list of strings representing addresses or a single address string.

  • top_n (int, optional) – Max number of matches to return for each input address. Defaults to 1.

  • address_ids (list of int, optional) – A list of integers representing the IDs of the addresses. Defaults to None.

  • how (str, optional) – The geocoding algorithm to use. If not provided, the default ‘how’ attribute is used.

  • verbose (bool, optional) – If True, print step-by-step details of the query pipeline. Defaults to False.

Returns:

results – A list of dictionaries representing geocoded addresses.

Return type:

list of dict

load_tree(tree_path: str) → None

Load a pre-built KDTree and its reference data for reverse geocoding.

Parameters:

  • tree_path (str) – Path to the pickled KDTree file created by AddressLoader.create_kdtree().

  • warning:: (..) – This uses pickle.load internally. Only load tree files from trusted sources, as deserializing untrusted pickle data can execute arbitrary code.

query(query: str) → DataFrame

Execute a read-only SQL query using the matcher’s database.

Only SELECT statements are allowed. Mutations (INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, ATTACH, DETACH, COPY, EXPORT) are rejected to prevent accidental or malicious data modification.

Parameters:

query (str) – The SQL query to execute (must be a SELECT statement).

Returns:

results – The results of the query as a DataFrame.

Return type:

pd.DataFrame

reverse_geocode(points: list[tuple[float, float]]) → list[dict]

Find the nearest addresses for given latitude and longitude coordinates.

Parameters:

points (list of tuple) – A list of (latitude, longitude) tuples representing coordinates.

Returns:

results – A list of dictionaries representing the nearest addresses.

Return type:

list of dict

MatcherPipeline Class

class whereabouts.MatcherPipeline.MatcherPipeline(matchers: list[Matcher], query_types: list[str])

MatcherPipeline class for concatenating Matcher objects to improve the recall of addresses.

matchers

A list of Matcher objects used for geocoding addresses.

Type:

list of Matcher

query_types

Specify for each matcher which query type to use, e.g., ‘standard’, ‘trigram’, or ‘skipphrase’

Type:

list of str

geocode(addresses, address_ids=None) :

Geocode a list of addresses using the Matcher objects in sequence.

geocode(addresses: list[str], address_ids: list[int] | None = None) → list[dict]

Geocode a list of addresses by passing them through each Matcher object in the pipeline.

Parameters:

  • addresses (list of str) – A list of strings representing addresses or place names.

  • address_ids (list of int, optional) – A list of integers representing the IDs of the addresses or place names (default is None).

Returns:

results – A list of dictionaries containing the best match for each input address.

Return type:

list of dict

set_matches(matchers: list[Matcher]) → None

Set the list of Matcher objects for the pipeline.

Parameters:

matchers (list of Matcher) – A list of Matcher objects to replace the current matchers.