Geocoding & Address Normalization

Every coordinate in a retail location pipeline began life as a string somebody typed, and the quality of that translation sets a ceiling on everything downstream. This section covers the stage that turns addresses into points: parsing them into components, standardizing them against a reference, geocoding them at a known precision, and proving the result is good enough to route from.

It is the least glamorous stage in the stack and the one that quietly decides the most. A store geocoded to the centre of its postcode rather than to its door moves by a few hundred metres, which is invisible on a national map and enough to put its drive-time catchment on the wrong side of a dual carriageway. A customer address that failed to parse is silently dropped from a demographic join, and the market it came from looks weaker than it is. Neither failure raises an exception, and both survive review, which is why this stage needs gates rather than good intentions.

Concept and Theory: Geocoding Is Two Problems, Not One #

The word “geocoding” hides a parsing problem inside a matching problem, and they fail differently.

Parsing takes a single string and decomposes it into typed components: house number, street name, street type, unit designator, place, region, postal code. It is a language problem. The same physical address arrives as 1200 N Wells St Ste 4, 1200 North Wells Street, Suite 4 and Suite 4, 1200 N. Wells, and a parser has to recognise all three as the same components in different orders with different abbreviations. Parsers fail on ambiguity — Saint versus St versus a street named St James — and their failures are recoverable, because a partially parsed address can still be matched.

Matching takes those components and finds the corresponding record in a reference dataset: a parcel, a building, an address point, a street segment. It is a search problem with a scoring function, and its failures are quieter. A match against a street segment with linear interpolation always succeeds and always returns a point — a point that may sit fifty metres from the building or, on a long rural segment, several hundred. Nothing about that result announces itself as weaker than a rooftop match unless the geocoder reports its precision and the pipeline reads it.

Precision Tiers: The Field That Makes the Rest Possible #

Every serious geocoder returns some indication of how the point was derived. The names differ, the concept does not, and the tiers form a hierarchy of ground accuracy that a pipeline can act on.

The rule that makes this table operational is that the tier travels with the coordinate for the rest of its life. A point stored without its tier is a point whose reliability has to be guessed at, and the guess is always optimistic. Once the tier is a column, the validation rules for store coordinates can scale their tolerances to it — a rooftop point disagreeing with its address by 400 metres is a real error, while a postal-centroid point doing the same is behaving exactly as advertised.

Architecture: Where Geocoding Sits in the Pipeline #

Geocoding belongs at the boundary, immediately after ingestion and before anything spatial happens. Placing it later — inside the scoring run, say, or on demand when a map is drawn — produces two problems that are hard to undo: the same address gets geocoded repeatedly with results that may differ as the reference data updates, and the coordinate acquires no provenance, because nobody recorded which reference version produced it.

The shape that works is a normalization service with a persistent result store, keyed on the normalized address rather than on the raw string. Ingestion writes raw records; the normalizer parses and standardizes them; the geocoder resolves anything not already in the store; and downstream stages read coordinates that are already tiered, dated and attributable. This is the same decoupling principle applied throughout the architecture foundations, and it pays off in the same way: the expensive stage runs once, its output is versioned, and a change to a downstream consumer never triggers a re-geocode.

import hashlib
from dataclasses import dataclass

import usaddress


@dataclass(frozen=True)
class NormalizedAddress:
    number: str
    street: str
    unit: str
    city: str
    region: str
    postcode: str

    def key(self) -> str:
        """Stable key for the result store — normalization must be deterministic."""
        raw = "|".join([self.number, self.street, self.unit,
                        self.city, self.region, self.postcode]).upper()
        return hashlib.sha256(raw.encode()).hexdigest()[:20]


ABBREV = {"STREET": "ST", "AVENUE": "AVE", "ROAD": "RD", "NORTH": "N",
          "SOUTH": "S", "EAST": "E", "WEST": "W", "SUITE": "STE"}


def normalize(raw: str) -> NormalizedAddress:
    """Parse a free-text address into typed, standardized components."""
    parsed, _kind = usaddress.tag(raw)          # raises on genuinely ambiguous input
    def part(*keys: str) -> str:
        vals = [parsed.get(k, "") for k in keys]
        joined = " ".join(v for v in vals if v).upper().replace(".", "")
        return " ".join(ABBREV.get(tok, tok) for tok in joined.split())

    return NormalizedAddress(
        number=part("AddressNumber"),
        street=part("StreetNamePreDirectional", "StreetName", "StreetNamePostType"),
        unit=part("OccupancyType", "OccupancyIdentifier"),
        city=part("PlaceName"),
        region=part("StateName"),
        postcode=part("ZipCode")[:5],
    )

Two details in that function carry more weight than they look. The key is built from the normalized components rather than the raw string, so three spellings of one address share a cache entry and a coordinate — which is what makes the result store useful rather than merely large. And the abbreviation map is applied consistently in one direction; a pipeline that expands abbreviations in one place and contracts them in another will produce two keys for one address and never notice.

Configuration Parameters #

The parameter that causes the most argument is accepted_tiers, and the argument is usually a symptom of the wrong question. The tiers are not a quality bar to be raised until enough records pass — they are a description of what each point can support. Street-interpolated points are entirely adequate for a market-level demand estimate and inadequate for measuring the distance from a candidate site to its nearest competitor, so the right answer is per use, recorded per record, rather than a single threshold applied everywhere.

Deduplication: The Problem Normalization Exposes #

Normalizing addresses makes duplicates visible that were previously hidden behind spelling differences, and duplicates matter more in a retail pipeline than in most: a store counted twice inflates a market’s coverage, doubles a competitor’s apparent presence, and creates a phantom cannibalization signal against itself.

The usual duplicates are not exact matches. They are the same location expressed as a suite and a unit, as two names for one plaza, or as a delivery entrance and a customer entrance thirty metres apart. Catching those requires combining a normalized-string comparison with a spatial one, which is why deduplication belongs after geocoding rather than before it.

Scaling and Cost: Geocoding Is a Budget Line #

At a few thousand store records, geocoding is free in every sense — a single batch, a few seconds, no meaningful cost. At a few million customer addresses it becomes a line item, and the shape of the spend is worth understanding before it arrives.

Three factors dominate. Volume of distinct addresses, not raw records, is what a well-designed pipeline pays for, because the result store answers everything it has seen before; a customer file of two million rows routinely contains fewer than a million distinct normalized addresses, and a delivery file far fewer still. Refresh policy decides how often that number is paid again: tying re-geocoding to reference-data releases rather than to a schedule turns an annual cost into an occasional one. And precision requirements decide which provider is needed at all — a market-level aggregate can be served by a free postal-code lookup, while a walk-catchment analysis needs rooftop matches that only a real geocoder provides.

The architecture that keeps the bill proportionate is the one already described: normalize first so the cache key is stable, store every result with its reference version, and let the pipeline request only what is genuinely new. Teams that skip the store typically discover the problem when a routine backfill re-geocodes the entire history, and the discovery arrives as an invoice rather than as an alert.

Throughput matters as much as cost. A provider that accepts batches of five hundred addresses per call will complete a million-address backfill in a couple of thousand calls; the same work issued one address at a time is a million round trips and, at any sensible client-side rate limit, a job measured in days. Batching is therefore not an optimisation but the difference between a backfill that fits in a maintenance window and one that does not — and the same applies to a self-hosted service, where the per-request overhead is smaller but the concurrency ceiling is real.

Validation and QA Gates #

The gates that matter here are cheap and specific, and they run on every ingest:

• Parse rate — the share of records that produced a full component set, tracked per source. A drop is a source-format change, not a data problem.
• Tier distribution — the share of results in each precision tier, compared against the previous run. A sudden shift toward postal centroids means the reference data or the matcher changed.
• Jurisdiction agreement — the geocoded point falls inside the administrative area its address claims. This single check catches transposed coordinates, wrong-state matches and a surprising number of genuine data-entry errors.
• Displacement on re-geocode — when a record is geocoded again under a new reference version, the distance it moved. Most should move less than a metre; the tail is where the reference improved or regressed.
• Duplicate rate — new duplicates found per import, by type. A rising unit-variant rate usually means a source system started emitting a field it previously omitted.

None of these needs a model, and all of them are the kind of measurement that turns an invisible degradation into a number on a dashboard. Feeding them into the same drift monitoring that watches the demographic layers keeps the whole ingestion boundary under one set of eyes.

Integration Notes: What the Next Stage Expects #

Downstream, the spatial database stores the coordinate with its tier, its reference version and the normalized key that produced it. The isochrone stage snaps that coordinate to the road network and will happily snap a postal-centroid point to a motorway; passing the tier through lets the routing stage refuse, or at least flag, contours built from points that were never precise enough to route from. And the competitor proximity index measures distances between points whose own uncertainty may exceed the differences being measured — which is only knowable if the tier travelled with them.

Frequently Asked Questions #

Conclusion #

Geocoding is where a text problem becomes a spatial one, and everything after it inherits whatever error was introduced here. Treat it as a distinct pipeline stage with its own store, keep the precision tier attached to every coordinate, deduplicate after geocoding rather than before, and gate each import on parse rate, tier distribution and jurisdiction agreement. Do that and the coordinates that reach the routing and scoring stages come with the one thing they most need: a documented claim about how much they can be trusted.

Related #

• Parsing and Standardizing US Store Addresses — the component-level parsing this section depends on.
• Batch Geocoding with a Self-Hosted Service — pinned reference versions and reproducible coordinates.
• Measuring Geocoder Accuracy Against Parcel Centroids — quantifying what each precision tier is worth.
• Data Validation Rules for Store Coordinates — the checks that run once a coordinate exists.

← Back to Location Intelligence Architecture & Data Foundations