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.
- Support for Ordnance Survey data. We provide a 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?
Given the following data:
- 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.
this 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
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file uk_address_matcher-1.3.0.tar.gz.
File metadata
- Download URL: uk_address_matcher-1.3.0.tar.gz
- Upload date:
- Size: 1.9 MB
- Tags: Source
- Uploaded using 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}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a1ef944261c555ea6e391b4a0253b95976492523a76b5f270b1c2cdf66c7f62e
|
|
| MD5 |
f21e3c79cbcf803aac814032c5ed0dcc
|
|
| BLAKE2b-256 |
f0786cfbd40b2595dba1bf45e00427a75344cf0332772e90ff8f216f06ac1f64
|
File details
Details for the file uk_address_matcher-1.3.0-py3-none-any.whl.
File metadata
- Download URL: uk_address_matcher-1.3.0-py3-none-any.whl
- Upload date:
- Size: 1.9 MB
- Tags: Python 3
- Uploaded using 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}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
21e9b96a6329bfd2d97641625e8bedf0bcebb35c98207f45b6220888d2eaa30a
|
|
| MD5 |
608e229376163392b42014cb342475c6
|
|
| BLAKE2b-256 |
17da5bfe4cc4a9ed986a2b97f6e2ca4843e4d85ade4ba39f9b91966dbeb65c0c
|
