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.
- [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"
]
}
2 maintainers
Metadata
2 maintainers
Release files for uk_address_matcher 1.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| uk_address_matcher-1.4.0.tar.gz | 10.3 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| uk_address_matcher-1.4.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 20.6 MB
Release files / uk_address_matcher-1.4.0.tar.gz
| Download URL | uk_address_matcher-1.4.0.tar.gz |
|---|---|
| Size | 10.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e17db5d23f04b3a2f67af3fee386c5015a3c2dec35289a19afb578ade3e1040c
|
|
BLAKE2b-256 checksum How to use checksums |
c1113ae40abed648fdcaa4f8de5d96b02cc2b751aca31a16daa491b5659a8d1e
|
| Upload date | |
|
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.4.0-py3-none-any.whl
| Download URL | uk_address_matcher-1.4.0-py3-none-any.whl |
|---|---|
| Size | 10.3 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3b3a5983e2dc2fb51b8f39a32c5df298d735efc7778caa1f0f8b5e37c36cb60a
|
|
BLAKE2b-256 checksum How to use checksums |
54fd286c43c843280455925008023068e80c4720769836309a0446eaee315bb1
|
| Upload date | |
|
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}
|
