address#

Address parsing, normalization, and harmonization utilities.

Parsing of one-line US address strings is delegated to pluggable backends via parse_address: the CRF-based usaddress library (default for US addresses, with a regex fallback for strings it cannot tag unambiguously) or a pass-through ‘none’ backend that preserves the raw string. Heavyweight backends (libpostal, deepparse) are documented placeholders only, so the base installation stays lightweight and cross-platform.

Component keys follow the conventions of dwelling-overture-2025 and the attribute registry: address_number, address_street, unit_number, city, state, postal_code. Normalization follows USPS Publication 28 abbreviations; display formatting produces title-cased street lines with uppercase state codes (e.g. ‘5006 Bogue Sound Dr, Emerald Isle, NC 28594’).

All abbreviation and equivalence tables live in address_equivalences.csv next to this module (case-insensitive, country-scoped via the admin1_id column; kind=match rows apply only when comparing streets, so notation variants like ‘HIGHWAY 94’ and ‘HWY 94’ match without changing display output). Per-country display syntax (segment order, postal-code rewrites) is declared in address_formats.csv — render-only, never used for parsing.

Classes#

ParsedAddress

Structured result of parse_address.

Functions#

clean_text(→ str)

Normalize casing, unicode accents, punctuation, and whitespace.

get_address_format(→ dict[str, str])

The country's display-syntax row from address_formats.csv.

get_admin2_codes(→ frozenset[str])

Within-country level-2 codes (e.g. 'NC', 'BY') from ISO 3166-2.

normalize_address_components(→ dict[str, str])

Standardize address components to USPS Publication 28 abbreviations.

parse_address(→ ParsedAddress)

Parse a one-line address into a structured ParsedAddress.

parse_address_string(→ dict[str, str | None])

Parse a one-line US address into components via parse_address.

get_address_similarity(→ float)

Fuzzy similarity between two normalized address strings (0-100).

canonicalize_for_match(→ str)

Collapse a street string to its comparison form.

match_streets(→ bool)

Decide whether two street strings refer to the same street.

harmonize_address_case(→ str)

Format address components into a single harmonized address line.

Module Contents#

openplaces.geo.address.clean_text(text: str) → str#

Normalize casing, unicode accents, punctuation, and whitespace.

openplaces.geo.address.get_address_format(admin1_id: str | None = None) → dict[str, str]#

The country’s display-syntax row from address_formats.csv.

Render-only declaration (never compiled into a parse regex): the format lists comma-separated segments of {component} fields, with ‘( … )?’ optional groups that drop unless every field inside is non-empty. Falls back to the ‘default’ row for countries without one.

openplaces.geo.address.get_admin2_codes(admin1_id: str) → frozenset[str]#

Within-country level-2 codes (e.g. ‘NC’, ‘BY’) from ISO 3166-2.

Backed by the admin-iso recipe table shipped with the package (the same data io.admin.get_admin2_iso reads), so state/region validation needs no hand-maintained lists and works for any country.

class openplaces.geo.address.ParsedAddress#

Structured result of parse_address.

components#

Parsed values keyed by ADDRESS_COMPONENTS (None if absent).

Type:

dict

address_raw#

The original input string, always preserved.

Type:

str

address_normalized#

Uppercase USPS Publication 28 canonical string.

Type:

str

address_formatted#

Title-cased display string (see harmonize_address_case).

Type:

str

metadata#

Parser provenance: {‘parser’, ‘version’, ‘status’} where status is ‘success’ or ‘fallback’.

Type:

dict

openplaces.geo.address.normalize_address_components(address_street: str, address_number: str | None = None, unit_number: str | None = None, postal_code: str | None = None, city: str | None = None, state: str | None = None, admin1_id: str | None = None) → dict[str, str]#

Standardize address components to USPS Publication 28 abbreviations.

Returns a dict keyed by ADDRESS_COMPONENTS with cleaned, uppercase values; missing components come back as empty strings. State codes are validated against the ISO 3166-2 level-2 codes of admin1_id (default DEFAULT_ADMIN1_ID); invalid codes are dropped.

openplaces.geo.address.parse_address(addr_str: str, backend: str = 'auto', admin1_id: str | None = None) → ParsedAddress#

Parse a one-line address into a structured ParsedAddress.

Parameters:

  • addr_str (str) – The raw address string; always preserved in address_raw.

  • backend (str) – ‘auto’ (default) resolves to ‘usaddress’ for US or unspecified addresses and degrades to ‘none’ otherwise; ‘usaddress’ forces the cached CRF parser; ‘none’ skips parsing and preserves the raw string. ‘libpostal’ and ‘deepparse’ are unbundled placeholders that warn and resolve like ‘auto’.

  • admin1_id (str, optional) – Level-1 admin (country) id providing routing context for ‘auto’ and state-code validation; None is treated as DEFAULT_ADMIN1_ID.

openplaces.geo.address.parse_address_string(addr_str: str) → dict[str, str | None]#

Parse a one-line US address into components via parse_address.

Thin convenience wrapper returning only the components dict, keyed by ADDRESS_COMPONENTS. Results are cached per unique input string.

openplaces.geo.address.get_address_similarity(addr1: str, addr2: str) → float#

Fuzzy similarity between two normalized address strings (0-100).

openplaces.geo.address.canonicalize_for_match(street: str, admin1_id: str | None = None) → str#

Collapse a street string to its comparison form.

Applies the country’s multi-word match phrases first (longest first), then maps every token through the union of its suffix, directional, and match tables — position-independent, unlike display normalization, so ‘HIGHWAY 94’ and ‘HWY 94’ compare equal. Tokens with an empty replacement are dropped.

openplaces.geo.address.match_streets(street1: str, street2: str, threshold: float = 80, admin1_id: str | None = None) → bool#

Decide whether two street strings refer to the same street.

Both sides are canonicalized via canonicalize_for_match (with the country’s tables) and compared with get_address_similarity. A dangling trailing directional on one side only (‘HWY 94 S’ vs ‘HWY 94’) is tolerated: the longer side is retried with it trimmed.

openplaces.geo.address.harmonize_address_case(address_street: str, address_number: str | None = None, unit_number: str | None = None, city: str | None = None, state: str | None = None, postal_code: str | None = None, admin1_id: str | None = None) → str#

Format address components into a single harmonized address line.

Applies title casing while preserving uppercase directionals (N, S, NE), state codes (NC, MA), Roman numerals, and unit alphanumerics (4B), and standardizing suffixes (St, Ave) and ordinals (1st, 2nd). The segment layout comes from the country’s address_formats.csv row, e.g. the default ‘5006 Bogue Sound Dr, Emerald Isle, NC 28594’ and DE’s ‘Hauptstrasse 12, 80331 Munich’. Units keep their designator (‘123 N Main St Apt 4B’); bare identifiers render as ‘#4B’.