UK Address Matcher¶

Fast, simple address matching (geocoding) in Python.

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.

Installation¶

pip install uk_address_matcher

What does it 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. The threshold guide explains how to interpret these scores.

Example:¶

Your data should be in the following format³:

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

The above is recommended if your canonical dataset is relatively small, say, under 1 million rows. If you're matching to larger canonical dataset, a preprocessing step is recommended. See choose whether to pre-process your canonical dataset for details.

Use Cases¶

Here is a list of some of our known users and their use cases:

Public Sector (UK)

The Greater London Authority's High Streets Data Service uses the uk_address_matcher to precisely geolocate London's businesses and assign each of them a commercial UPRN, in order to fully map the city's retail provision and commercial property use.
Homes England has tested the Splink-based address matcher to link the Land Registry Price Paid dataset with the Ordnance Survey National Geographic Database (NGD). In a Databricks environment, it links around 30 million records in under five hours with high accuracy, helping to identify and monitor new builds that contribute to the 1.5 million homes mandate.
The Welsh Government's DataMapWales team is using the uk_address_matcher to build a central, self-service address matching service in FME Flow. It matches free-text addresses, including Welsh language and bilingual addresses, against Ordnance Survey NGD, attaches UPRNs, and provides confidence ratings and review flags. By providing a simple user interface for the technical matching process, the service will make address matching capabilities accessible to teams without specialist coding or data engineering expertise.

Licence¶

This project is free and open source and is released under the MIT licence.

Next steps¶

Timings on a MacBook Pro M4 Max. ↩
Does not include the time taken to download Ordnance Survey data since this depends on the speed of your internet connection. ↩
The postcode column is optional. If you include it, the matcher will use it directly. If you do not, the matcher will attempt to detect and extract postcodes from address_concat. uk_address_matcher also supports matching addresses that lack a postcode. ↩