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 offer first-party support and an automated data preparation pipeline through
ukam_os_builder. You can also match against any other canonical dataset.
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
Before proposing changes, read the contribution guidelines, including scope agreement, documentation and AI-use expectations.
Security checks and maintainer setup are documented in developer security administration. Contributors should run the checks but leave security baselines and exceptions to maintainers. Report vulnerabilities privately using the security policy.
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.5.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| uk_address_matcher-1.5.2.tar.gz | 11.0 MB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| uk_address_matcher-1.5.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 22.1 MB
Release files / uk_address_matcher-1.5.2.tar.gz
| Download URL | uk_address_matcher-1.5.2.tar.gz |
|---|---|
| Size | 11.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d129f25989266f38be6bb1c221b8ce75df639fa888fe3f762f3e5bd887aa30e5
|
|
BLAKE2b-256 checksum How to use checksums |
b8ab68ae27737f3d224a27dabe28d8dd2c93d5c335076c7e9ff8a1ad4ea63ce2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| 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.2-py3-none-any.whl
| Download URL | uk_address_matcher-1.5.2-py3-none-any.whl |
|---|---|
| Size | 11.1 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
eff0479dc9c20512ba415c187fb56914191f1e2bcea19b6b2853483467cb0f61
|
|
BLAKE2b-256 checksum How to use checksums |
7e8a66780bd958db854b8cdfab50e9329288c9a0e8ac084fbddfdb5192931e79
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| 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}
|
Security for uk_address_matcher 1.5.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
