uk_address_matcher 1.0.0.dev28

A package for matching UK addresses using a pretrained Splink model

High performance UK addresses matcher (geocoder)

Fast, simple address matching (geocoding) in Python.

The key features are:

• Simple: Python only, set up in seconds on any laptop, no infrastructure needed
• Fast: Match 100,000 addresses in around 30 seconds*
• Reproducible benchmarks: High accuracy, demonstrated with reproducible examples

* Timings based on a Macbook M4 Max.

Installation

pip install --pre uk_address_matcher

Usage

uk_address_matcher assumes you have two tables in the following format:

unique_id	address_concat
1	123 Fake Street, Faketown, FA1 2KE
2	456 Other Road, Otherville, NO1 3WY
...	...

Generally one dataset will be a dataset of 'messy addresses' which need matching, and the second will be a 'canonical dataset' of addresses to match to, such as Ordnance Survey Addressbase or NGD.

Basic Matching

[!NOTE] Two runnable examples with live sample data are included for experimentation:

• examples/example_matching.py: End-to-end matching example, including loading data, running the matcher, and previewing results.
• examples/example_prepare_canonical.py: Example of preparing a canonical dataset for repeated use, demonstrating how to persist prepared data to disk and load it for matching.

The package also provides downloadable demo datasets via ukam_datasets.

import duckdb

from uk_address_matcher import AddressMatcher, ukam_datasets

con = duckdb.connect()

# Download + load fictional London dummy datasets (cached locally)
df_messy, df_canonical = ukam_datasets.fictional_london

matcher = AddressMatcher(
    canonical_addresses=df_canonical,
    addresses_to_match=df_messy,
    con=con,
)

result = matcher.match()
result.matches().show(max_width=500)

The default stages are ExactMatchStage followed by SplinkStage. You can customise them by passing your own stages list:

from uk_address_matcher import (
    AddressMatcher,
    ExactMatchStage,
    SplinkStage,
    UniqueTrigramStage,
)

matcher = AddressMatcher(
    canonical_addresses=df_canonical,
    addresses_to_match=df_messy,
    con=con,
    stages=[
        ExactMatchStage(),
        UniqueTrigramStage(),
        SplinkStage(),
    ],
)

result = matcher.match()
result.matches().show(max_width=500)

Additional columns

You may also provide a separate column called postcode, which, if provided will take precidence over any postcode information provided in address_concat.

If you have labelled data (you know the ground truth), you may provide a column called ukam_label, if provided, this will propagate through your results for accuracy analysis.

Pre-preparing canonical data

Cleaning a large canonical dataset (e.g. AddressBase) is expensive. Use prepare_canonical_folder to do it once and write the artefacts to disk. Subsequent runs load the prepared folder directly, skipping cleaning entirely.

from uk_address_matcher import AddressMatcher, prepare_canonical_folder

# One-time preparation
prepare_canonical_folder(
    df_canonical,
    output_folder="./ukam_prepared_canonical",
    con=con,
    overwrite=True,
)

print("Prepared canonical data written to ./ukam_prepared_canonical/")

# Fast matching — pass the folder path instead of a relation
matcher = AddressMatcher(
    canonical_addresses="./ukam_prepared_canonical",
    addresses_to_match=df_messy,
    con=con,
)

result = matcher.match()
result.matches().show(max_width=500)

Matching one or more AddressRecord entries

If you want to match a small number of addresses, or you have them in-memory as Python dictionaries, you can pass them directly as addresses_to_match without needing to create a DuckDB relation first.

You can pass a list of AddressRecord entries directly as addresses_to_match. The matcher also accepts a list of dicts with address_concat, postcode, and unique_id, or a DuckDB relation.

import duckdb

from uk_address_matcher import AddressMatcher, AddressRecord, ukam_datasets

con = duckdb.connect()

df_canonical = ukam_datasets.as_relation("fictional_london_canonical", con=con)

records = [
    AddressRecord(
        unique_id="m_1",
        address_concat="96 Marlowhill Street, Kingsford, London",
        postcode="NW24 2CW",
    ),
    AddressRecord(
        unique_id="m_2",
        address_concat="46 Vespergate Road, Maple Green",
        postcode="NW26 6MU",
    ),
]

matcher = AddressMatcher(
    canonical_addresses=df_canonical,
    addresses_to_match=records,
    con=con,
)

result = matcher.match()
result.matches().show(max_width=500)

Methodology

The Splink phase uses a two-pass approach to achieve high accuracy matching:

1. First Pass: A standard probabilistic linkage model using Splink generates candidate matches for each input address.

2. Second Pass: Within each candidate group, the model analyzes distinguishing tokens to refine matches:

   • Identifies tokens that uniquely distinguish addresses within a candidate group
   • Detects "punishment tokens" (tokens in the messy address that don't match the current candidate but do match other candidates)
   • Uses this contextual information to improve match scores

This approach is particularly effective when matching to a canonical (deduplicated) address list, as it can identify subtle differences between very similar addresses.

Development

The scripts and tests will run better if you create .vscode/settings.json with the following:

{
    "jupyter.notebookFileRoot": "${workspaceFolder}",
    "python.analysis.extraPaths": [
        "${workspaceFolder}"
    ],
    "python.testing.pytestEnabled": true,
    "python.testing.unittestEnabled": false,
    "python.testing.pytestArgs": [
        "-v",
        "--capture=tee-sys"
    ]
}