UK Address Matcher Logo

High performance UK addresses matcher (geocoder)

Fast, simple address matching (geocoding) in Python.

For full documentation, see our main documentation site.

Why use this library

Simple. Setup in seconds, runs on a laptop. No separate infrastructure of services needed.
Fast. Match 100,000 addresses in ~30 seconds.
Proven accuracy. We use public, labelled datasets to measure and document accuracy.
[OPTIONAL] Support for Ordnance Survey data. We provide an automated build pipeline for users wishing to match to Ordnance Survey data. Matching to any other canonical dataset is also supported.

The end-to-end process of matching 100,000 addresses to Ordnance Survey data, including all software downloads and data processing takes:

Less than a minute if you are matching to a small area such as a local council region.
If matching to the whole UK, there's a one-time preprocessing step that takes around 10 minutes. Subsequent matching of 100k records takes less than a minute.

What does `uk_address_matcher` do?

uk_address_matcher finds the best known address for each address in your dataset.

Data flow diagram showing how uk_address_matcher cleans and matches addresses

[OPTIONAL]: Construct Ordnance Survey canonical data using ukam_os_builder. Skip this step if you already have a canonical dataset or are using another source.
Input: provide a messy dataset, such as addresses typed by users, and a canonical dataset of known addresses. See the input data requirements.
Preparation: addresses are cleaned, standardised, and enriched with useful features such as postcodes. See the canonical dataset preprocessing guidance.
Matching: configurable matching stages compare each messy address with candidate canonical addresses, from exact matches through to probabilistic matching with Splink. See choosing a matching threshold.
Output: the best match, together with the match reason, match weight, and distinguishability score. See choosing a matching threshold for how to interpret these scores.

Installation

pip install uk_address_matcher

Inputs

You provide two datasets:

a "messy" dataset of addresses that you want to match
a "canonical" dataset of known addresses, often an Ordnance Survey dataset such as AddressBase or NGD.

The package will find the best matching canonical address for each messy address.

Example:

Your address files need, at minimum, two columns: unique_id and address_concat.

postcode is optional by recommended. If not provided an attempt is made to parse them out of address_concat

Given the following data:

Messy data

unique_id	address_concat	postcode
m_1	Flat A Example Court, 10 Demo Road, Townton	AB1 2BC
...more rows

Canonical data

unique_id	address_concat	postcode
c_1	Flat A, 10 Demo Road, Townton	AB1 2BC
c_2	Flat B, 10 Demo Road, Townton	AB1 2BC
c_3	Basement Flat, 10 Demo Road, Townton	AB1 2BC
...more rows

You can match it as follows:

import duckdb
from uk_address_matcher import AddressMatcher

con = duckdb.connect()
messy = con.read_csv("example_data/messy_example.csv")
canonical = con.read_csv("example_data/canonical_example.csv")

matcher = AddressMatcher(
    canonical_addresses=canonical,
    addresses_to_match=messy,
    con=con,
)
result = matcher.match()
result.matches().show(max_width=10000)

Example output:

unique_id	resolved_canonical_id	original_address_concat	original_address_concat_canonical	match_reason	match_weight	distinguishability
m_1	c_2	Flat A Example Court, 10 Demo Road, Townton	Flat A, 10 Demo Road, Townton	splink: probabilistic match	13.5885	11.5033

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"
    ]
}

Metadata

Release files for uk_address_matcher 1.5.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for uk_address_matcher 1.5.1
File	Size	Uploaded
uk_address_matcher-1.5.1.tar.gz	10.3 MB	Oct 14, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for uk_address_matcher 1.5.1
File	Interpreter	ABI	Platform	Reset
uk_address_matcher-1.5.1-py3-none-any.whl 10.3 MB Oct 14, 2026	Python 3	none	any	Details

Total release size: 20.7 MB

Release files / uk_address_matcher-1.5.1.tar.gz

Download URL	uk_address_matcher-1.5.1.tar.gz
Size	10.3 MB
Tags	Source
SHA-256 checksum How to use checksums	`fa4d573fdfef501f5c62cd374e625295b445a4538acab61cc1c36bafd428aa84`
BLAKE2b-256 checksum How to use checksums	`0cf5701be02f67cc4cda69cfb1ed11b3279c4d9a58a34a770c5206094b329638`
Upload date	Oct 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.11.3 {"installer":{"name":"uv","version":"0.11.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / uk_address_matcher-1.5.1-py3-none-any.whl

Download URL	uk_address_matcher-1.5.1-py3-none-any.whl
Size	10.3 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`23a45c3fd90c206658316e81ddfdb158e87ef2c998b73c62033a3f12589a23e0`
BLAKE2b-256 checksum How to use checksums	`8989d5a33bbecf26b668eaaaef71521a217610073205d87f65cc819228e00b7a`
Upload date	Oct 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.11.3 {"installer":{"name":"uv","version":"0.11.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`