Skip to content
allanninal.dev/build
Collaborate

Part 1 of 7 · Address verifier series ~6 min read

An address verifier on AWS for a few dollars a month

A failed delivery costs the carrier charge, the re-send, the customer service exchange and a decent chance of the order being cancelled, and almost all of them trace back to an address that was wrong when it was typed. The obvious fix is to validate at checkout and refuse bad ones, and that turns a delivery problem into an abandoned basket. This post walks through a small system that suggests rather than refuses.

An aerial view of a parking lot with cars
Photo by Bernd Dittrich on Unsplash

Key takeaways

  • The reference file is authoritative and incomplete. Both halves matter.
  • Suggest a correction; never block. A refused address is a lost order.
  • Only formatting is corrected silently. Anything that changes meaning is offered.
  • Most failed deliveries come from addresses already stored, so those get swept too.
  • Designed on AWS for about $4 a month plus reference lookups.

The whole system on one page

Before any code, here is the shape of what we are designing.

System: an address checked against a reference file, a correction suggestedThree boxes across the top sit outside the AWS account. On the left, The checkout: an address being typed. In the middle, Reference file: postal data accessed by lookup. On the right, The customer: who accepts a suggestion or insists on what they typed. Each connects by an arrow to the AWS account container below. An address flows down into the account. The reference file answers whether it exists. A suggestion, not a block, goes back out. Inside the AWS account are three components in a row. On the left, the Checker, which normalises and then looks up. In the middle, the Suggester, which offers one correction rather than a list of ten. On the right, the Recorder, which stores what was offered and what was chosen. A note at the bottom says nothing here can prevent an order, and the worst outcome is a suggestion declined.AWS ACCOUNTThe checkoutan address being typedReference filepostal data, by lookupThe customeraccepts, or insistsCheckernormalise, then look upSuggesterone correction,never a list of tenRecorderwhat was offered,what was chosenan addressdoes it exist?a suggestion, nota blockNothing here can prevent an order. The worst outcome is a suggestion declined.
Fig 1. Three things outside the account, three pieces inside it. The note at the bottom is the commercial constraint that shapes every other decision.
  • Management
  • Analytics
  • Front-end & mobile
  • People

Authoritative and incomplete

A postal reference file is the best available description of which addresses exist, and it is not a complete one. New developments take months to appear. A house divided into two flats may exist as one entry. Farms, rural properties and anything with a name rather than a number are routinely represented differently from how the occupant writes them.

So a lookup that returns nothing means one of two things: the address is wrong, or the address is fine and the file does not have it. The system genuinely cannot tell which, and every design decision here follows from taking that seriously rather than treating a miss as a rejection.

What runs (the inside)

  • The checker. Normalises what was typed, looks it up, and classifies the result into one of four outcomes rather than a yes or a no. Part 2 covers the four and why a boolean is not enough.
  • The suggester. Where the file has an obvious near-match, offers it as one suggestion with the difference highlighted. Part 3 is about offering one rather than a list and about what counts as obvious.
  • The recorder. Stores what was typed, what was offered and what was chosen. That third field is what makes the whole thing improvable, and it is the one most implementations omit.

One address, end to end

One address from typing to recorded choice, in five stagesA horizontal row of five boxes joined by arrows. Typed: at checkout. Normalised: for case, spacing and field order. Looked up: producing one of four outcomes. Suggested: or accepted as typed. Recorded: both what was offered and what was chosen. A note says about two hundred milliseconds, and the customer never waits for it.ONE ADDRESS, END TO ENDTypedat checkoutNormalisedcase, spacing, orderLooked upone of four outcomesSuggestedor accepted as typedRecordedoffered, and chosenAbout 200 milliseconds, and the customer never waits for it.
Fig 2. The same system as one line. It runs while somebody is still filling in the next field, which is what makes suggesting viable at all.
  • Machine learning
  • Management
  • Analytics
  • Front-end & mobile

In plain words

Somebody types “14 chestnut rd, ashford, kent, tn24 8ql”. The checker normalises the case and the postcode spacing and looks it up. The reference file has 14 Chestnut Road at that postcode, so the address exists and the only differences are formatting. It is silently tidied and nothing is shown.

The next customer types the same street with postcode TN24 8QC. That postcode is a different street entirely, and the reference file has no number 14 on it. But the address they typed matches Chestnut Road exactly, and Chestnut Road has one postcode. So the suggester offers: “Did you mean TN24 8QL?” with the change highlighted. They tap yes and the delivery arrives.

The third customer types an address in a development finished six weeks ago. The reference file has never heard of it, and there is no near-match to suggest. The system shows nothing at all, the order proceeds exactly as it would have, and the address is recorded as unverified — which is a fact the warehouse can see if it wants to, and not an obstacle.

Design rules that shaped every decision

  • Never block. A refused address is a lost order and the reference file is not complete enough to justify it.
  • Correct formatting silently; suggest anything that changes meaning.
  • One suggestion, not a list. A picker with ten options is a worse experience than typing it again.
  • Record what was offered and what was chosen. Declined suggestions are the tuning signal.
  • Sweep the stored addresses too. Most failed deliveries come from data that predates any validation.
  • An unverified address is a flag, not an error. Plenty of real addresses are unverifiable.

Why this shape

Address validation products mostly optimise for the checkout moment and treat the result as binary, which produces two bad outcomes: real customers at real addresses being refused, and the far larger pool of already-stored bad addresses going untouched because the product only runs at entry.

So this design does the entry check gently and spends equal effort on the background sweep, because a business that has been trading five years has vastly more bad addresses in its database than it will collect at checkout this month. Fixing those is where the failed deliveries actually go away.

The next four posts walk through each piece: how an address is checked, how a suggestion is made, what happens to an address that cannot be verified, and how the stored ones get swept. One diagram per post, a cost breakdown, and an engineering reference at the end.

All posts