Skip to main content

Human-in-the-loop geocoding

This approach skips parsingaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates., resolving, and guessing. It shows the user what it thinks they meant and lets them confirm. The parser is a suggestion engine; the user's confirmation is the ground truthground truthThe correct answer for an example, used as the standard a prediction is graded against. Mailwoman's ground truth is the hand-labeled golden set; its quality caps achievable accuracy..

The approach​

  1. Accept free-text input. A single text field. No separate boxes for streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels., citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy., stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality., and ZIP. The user types whatever they have: 350 5th Ave, NYC, Empire State Building, 90210, my house.
  2. Run a fuzzy geocoder on the input. PostcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. extraction, gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. lookup, normalizenormalizeStage 1 of the runtime pipeline: deterministic input preprocessing (Unicode NFC, punctuation normalization, whitespace collapse). Returns a NormalizedInput with an offsetMap that maps normalized positions back to the raw input.-to-match against a known database — whatever combination of simple approaches works for your address universe. The geocoder returns candidates, not a single answer.
  3. Show the user the candidates. A dropdown or map with the top 3-5 matches. "Did you mean: 350 5th Ave, New York, NY 10118 (Empire State Building)?" The user picks.
  4. The user's selection is canonical. The selected address is stored as the canonical form for that user. Future inputs from the same user can match against their saved addresses without re-guessing.

This is how Google Maps, Apple Maps, and every ride-sharing app work. The user types a few characters, the system suggests completions, the user taps one. The system never has to parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. a free-text address with high confidence — it only has to suggest plausible completions from a known universe.

When it works​

  • Interactive applications. A checkout form, a delivery address entry, a search box. The user is present and can confirm. The cost of a wrong guess is a bad suggestion, not a misdelivered package.
  • You have an autocomplete index. A database of known addresses (Google's Places API, your own customer database, a gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture.). The system suggests from the index, not from free-text parsingaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates..
  • Your user base is typing their own addresses. They know where they live. They will recognize the correct suggestion when they see it. The system doesn't need to be right — it needs to be close enough that the right answer is in the top 5.
  • You serve ambiguous addresses. Springfield — the system suggests the top 3 Springfields by proximity to the user's IP or previous addresses. The user picks the right one. No AI needed.
  • You are building a product, not infrastructure. The geocodinggeocodingThe process of converting an address into geographic coordinates (latitude and longitude). Mailwoman geocodes in a multi-tier cascade: exact address-point match → street interpolation → locality centroid. Each tier is progressively coarser but more widely available. is a UX featurefeatureAn input signal a model conditions on. Beyond the raw tokens, Mailwoman feeds soft features — gazetteer-membership channels and the postcode anchor — that inform predictions without overriding them., not a backend pipelinestaged pipelineMailwoman's runtime architecture: a sequence of pure-function stages (normalize → query-shape → locale-gate → kind-classifier → phrase-grouper → classifier → decoder) connected by typed handoffs. Each stage is published as its own npm package.. The user's selection is the output. The system doesn't need to geocode in batchbatch sizeHow many examples the model processes before each parameter update. Larger batches give smoother gradients but cost more memory; gradient accumulation simulates a big batch on a small GPU. without human oversight.

What you lose​

  • Batch processing. You cannot show suggestions to a million addresses in a CSV file. Human-in-the-loop requires a human. Batchbatch sizeHow many examples the model processes before each parameter update. Larger batches give smoother gradients but cost more memory; gradient accumulation simulates a big batch on a small GPU. geocodinggeocodingThe process of converting an address into geographic coordinates (latitude and longitude). Mailwoman geocodes in a multi-tier cascade: exact address-point match → street interpolation → locality centroid. Each tier is progressively coarser but more widely available. requires a parser that works without one.
  • Automation. Every address that needs human confirmation is a step in a workflow that could have been automatic. If 95% of addresses are unambiguous and 5% need confirmation, the 5% drives your support costs.
  • The user's patience. Springfield, IL has one obvious candidate. Showing a dropdown of 34 Springfields is noise. The system should recognize when there's a single high-confidence match and skip the confirmation. Knowing when to skip requires a confidence signal — which requires a parser.
  • The user who doesn't know their address. A gift recipient, a new mover, a tourist types what they think the address is, and it might be wrong. The system shows candidates, and the user picks whichever looks right — which can also be wrong. Without ground truthground truthThe correct answer for an example, used as the standard a prediction is graded against. Mailwoman's ground truth is the hand-labeled golden set; its quality caps achievable accuracy. in the loop, this is just two layerslayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6. of guessing.
  • Addresses not in the autocomplete index. The user types a new construction address that isn't in any database. The autocomplete returns nothing. The user cannot proceed. The system needs a fallback — free-text parsingaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. — for addresses outside the index.

Where Mailwoman fits​

Mailwoman is the backend for the autocomplete index. The parser extracts structured components from free-text input. The resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. returns candidates with confidence scores. The autocomplete UI shows the top candidates. The user confirms.

Mailwoman feeds the human-in-the-loop rather than replacing it. The parser tells the UI: "I'm 95% sure this is 350 5th Ave, New York, NY 10118, and 4% sure it's 350 5th Ave, Brooklyn, NY 11215." The UI shows one suggestion (high confidence) or two (ambiguity). The user either confirms or corrects. The correction feeds back into the trainingtrainingThe process of adjusting a model's parameters so its predictions match labeled examples, by repeatedly measuring error and nudging the weights to reduce it. Distinct from inference, when the trained model is run on new input. corpuscorpusThe BIO-labeled training data used to train Mailwoman's neural classifier. Assembled from real sources (OpenAddresses, National Address Database) and synthetic shards (boundary stress, order variants, negative space). Managed by @mailwoman/corpus..

This is the architecture behind the PhasephaseA milestone in the implementation plan (Foundation, Corpus, Training, Integration, and forward-looking phases). Distinct from stage (runtime pipeline) and tier (model vocabulary). 5 Studio: a web UI where humans correct parsesaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates., corrections become trainingtrainingThe process of adjusting a model's parameters so its predictions match labeled examples, by repeatedly measuring error and nudging the weights to reduce it. Distinct from inference, when the trained model is run on new input. data, and the modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' improves. The human-in-the-loop is how the parser gets better over time.

See also​