Skip to main content

Falsehoods programmers believe about address shapes and dimensions

An address is not always a point on a map, a polygon, or a discrete building. It may not sit at ground level, may not be the only address at its coordinates, and may not stay in one place.

Falsehoods​

"An address is a lat/lon point."​

PostcodespostcodeThe 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., rural routes, and descriptive addresses all represent areas or paths, not points. A ZIP code centroid in rural Montana is off by 10-15 miles from any actual delivery point. The centroid is a convenience for map rendering, not a geographic truth about the address.

The US Census Bureau's ZIP Code Tabulation Areas (ZCTAsZCTA (ZIP Code Tabulation Area). The US Census Bureau's polygon approximation of a ZIP code, generalized from census blocks rather than USPS delivery routes. Explicitly not USPS ground truth and often wrong in rural areas.) generalize ZIP codes into polygons, but ZCTAsZCTA (ZIP Code Tabulation Area). The US Census Bureau's polygon approximation of a ZIP code, generalized from census blocks rather than USPS delivery routes. Explicitly not USPS ground truth and often wrong in rural areas. are explicitly NOT USPS 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.. USPS does not publish ZIP code boundaries as polygons — they are carrier routescarrier routeThe delivery path one postal carrier covers on a shift. A ZIP code is fundamentally a set of carrier routes, not a geographic polygon, which is why ZIP boundaries are fuzzy and shift over time., not areas. A ZIP code follows the path a carrier walks.

UK postcodespostcodeThe 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. cover ~15 addresses on average — effectively points. But UK 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. sectors (the first half of the 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., e.g., SW1A) cover neighborhoods. The same 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. system produces both point-level and area-level resolution depending on which part you use.

Irish Eircodes are unique per delivery point — the 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. IS the point. French postcodespostcodeThe 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. correspond to commune boundaries — the 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. IS the polygon. The same concept ("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.") has fundamentally different spatial semantics in different countries.

"An address is a polygon."​

No address is a polygon in the geospatial sense. A building footprint is a polygon. A parcelparcelA property polygon or record carrying a situs (site) address and often a separate owner mailing address. County GIS parcel aggregations are a training source for address-point variety and situs-vs-owner divergence. boundary is a polygon. An address is a labelcomponent tagOne of the 33 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag. applied to one or more of these spatial objects, but the address itself has no shape.

Buildings with multiple addresses (apartment buildings, office towers) are one polygon with many address labelscomponent tagOne of the 33 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag.. A single-family home is one polygon with one address labelcomponent tagOne of the 33 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag.. A rural route is a path with many address labelscomponent tagOne of the 33 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag. distributed along it. A PO boxPO boxA numbered mailbox at a post office used as a delivery address instead of a physical street location. Mailwoman tags it as the po_box component; structurally the same family as a subpremise. is an address labelcomponent tagOne of the 33 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag. with no spatial object at all — it exists only at the post office counter.

Geocoders that return a polygon for an address are returning the polygon of the spatial object the address is associated with (a building, a parcelparcelA property polygon or record carrying a situs (site) address and often a separate owner mailing address. County GIS parcel aggregations are a training source for address-point variety and situs-vs-owner divergence., a ZIP code approximation). The address itself is the labelcomponent tagOne of the 33 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag., not the shape.

"An address is a discrete building."​

An address can represent:

  • A specific apartment within a building (same building footprint, different address).
  • A floor of an office tower (same lat/lon, different vertical coordinate).
  • A PO boxPO boxA numbered mailbox at a post office used as a delivery address instead of a physical street location. Mailwoman tags it as the po_box component; structurally the same family as a subpremise. at a post office (the address is at the post office, not at the recipient's home).
  • A mailbox on a rural route (the address is a point along a path, not a building).
  • A berth in a marina (the address is a slip of water between docks).
  • A campsite in a national park (the address is a designated area, not a structure).
  • A grid coordinate in Mannheim, Germany (R 5, 6-13 — block R, row 5, buildings 6-13, no streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.).
  • A distance marker: 50 miles West of Socorro, New Mexico — no building, a point relative to a known place.
  • A descriptive location: From where the Chinese restaurant used to be, two blocks down, half a block toward the lake — no fixed reference, entirely relational.

"An address is at ground level."​

Z-dimension matters. Buildings have floors, and different floors can have different addresses:

  • Below ground. Basement apartments, underground parking, subway stations, wine cellars, bomb shelters, data centers. 123 Main St, Basement is a different delivery point from 123 Main St, Apt 1 — same building footprint, different vertical position, possibly different entrance.
  • Above ground. Floor 50 of a skyscraper. The Empire State Building has different ZIP+4 codes for different floors and tenants. A geocode to the building centroid places all addresses at the same coordinate. A geocode with floor-level resolution places Floor 50 at 200 meters above ground level — but no geocoder returns elevation data.
  • Sky lobbies. Some skyscrapers have separate entrance lobbies at ground level and sky lobbies at transfer floors. A delivery to "85th Floor, 1 World Trade Center" may route through the sky lobby on the 64th floor, not the ground floor. The address's entrance is at elevation.
  • Underground complexes. Tokyo Station has a citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.'s worth of retail and office space underground, with addresses that resolve to the surface station coordinates. Montreal's RÉSO (underground citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.) connects 1,600 shops and 200 restaurants — all with surface addresses, all functionally underground.

"An address doesn't share its lat/lon with another address."​

A shopping mall at one lat/lon can have 100+ addresses — one per store. An office tower can have one address per floor, per suite, or per tenant. Each address shares the same horizontal coordinates but differs in vertical position or internal routing.

A marina has addresses for each berth — the berths are adjacent, not stacked, but they share approximate coordinates and differ by a few meters. A trailer park has addresses for each padpadding tokenA filler token added to short sequences to reach a fixed length, masked out during attention so it carries no meaning. — same lat/lon to within 10 meters, differentiated by padpadding tokenA filler token added to short sequences to reach a fixed length, masked out during attention so it carries no meaning. number.

A post office with PO boxesPO boxA numbered mailbox at a post office used as a delivery address instead of a physical street location. Mailwoman tags it as the po_box component; structurally the same family as a subpremise. has hundreds of addresses (the PO boxPO boxA numbered mailbox at a post office used as a delivery address instead of a physical street location. Mailwoman tags it as the po_box component; structurally the same family as a subpremise. numbers) all at one lat/lon — the post office building. 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. a PO boxPO boxA numbered mailbox at a post office used as a delivery address instead of a physical street location. Mailwoman tags it as the po_box component; structurally the same family as a subpremise. to the post office building is correct at the building level but wrong for the recipient's actual location.

"An address stays where it is."​

Houseboats, ships, and mobile homes have addresses that move. A houseboat moored at a marina changes coordinates when it relocates. A cruise ship employee's address follows the ship's itinerary. A mobile home moved to a new park gets a new address even though the physical structure is the same.

Offshore platforms have addresses but not fixed coordinates relative to land. A North Sea oil platform's address is its name and block number, not a lat/lon on a standard map projection. Military forward operating bases have addresses that exist only as long as the base exists.

Douglas Perreault's condo in Florida changed address three times in a few years — same physical location, four different written addresses due to post office changes and block renaming.

"An address has a street-facing entrance."​

Buildings can have entrances on multiple streetsstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. (corner buildings), entrances at different elevations (hillside buildings with ground-floor entrances on different floors), or entrances that are not on the labeled streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. at all (rear-access buildings, alleys, internal courtyards). The address's streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. name may not be the streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. the entrance faces.

A building at the corner of Main St and Elm St might have address 123 Main St but the delivery entrance is around the corner on Elm St. The geocoder places the coordinate on Main St. The delivery driver approaches from Elm St. Both are correct for their respective purposes.

How traditional geocoders handled these​

libpostallibpostalAn open-source C address parser used by Pelias. Mailwoman's rule-based v0 and neural classifier supersede it. operates exclusively on text strings. It does not produce spatial output — no coordinates, no polygons, no elevation. The spatial questions are downstream of libpostallibpostalAn open-source C address parser used by Pelias. Mailwoman's rule-based v0 and neural classifier supersede it.'s parser. This is the correct architecture: the parser labelscomponent tagOne of the 33 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag. tokenstokenOne word or subword in the tokenized input. For the neural classifier, tokens come from SentencePiece (subword units); for the rule classifiers, tokens are whitespace- and punctuation-separated words., 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. turns labelscomponent tagOne of the 33 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag. into spatial objects. The parser should not need to know about shapes.

PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. resolves addresses to point coordinates via Elasticsearch. Multi-address buildings (apartments, malls) all resolve to the same building centroid unless the data source includes unitunitA subdivision of a building — apartment, suite, floor — that refines a street address. Mailwoman's unit component; a designator plus identifier forms a subpremise.-level coordinates. PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. has no concept of vertical position — Floor 50 and the basement of the same building are the same coordinate. PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. does not 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.' mobile addresses (houseboats, ships) or non-building addresses (rural route boxes, grid coordinates).

Google's API returns a location type with each geocode: ROOFTOP (precise to the building entrance), RANGE_INTERPOLATED (estimated along a streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context.), GEOMETRIC_CENTER (centroid of a regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality.), or APPROXIMATE (best guess). This is the right taxonomy — it tells the consumer the spatial precisionprecisionOf the spans the model labeled as a given tag, the fraction it got right. High precision means few false positives. Paired with recall to compute F1. of the result. Google's Places API returns latitude, longitude, and an optional viewport (bounding box) for each place, distinguishing point-level from area-level results. Google does not return elevation data for addresses.

What the neural approach changes​

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. (StagestageOne of the dataflow stages in the runtime pipeline (normalize, locale gate, kind classify, phrase group, token classify, sequence correct, reconcile, resolve). Distinct from tier (model vocabulary) and phase (plan milestone). 6) returns each candidate's placetypeplacetypeThe Who's On First hierarchical classification of places: planet → continent → country → region → county → locality → neighbourhood. The resolver uses placetype to rank candidates — an exact locality match outranks a county-level match. alongside its coordinates. A WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. record has a placetype (countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head., regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality., localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy., neighbourhood, venuevenueA named, non-address place — a business, building, park, or stadium. Mailwoman's free-text point-of-interest component, added as a Tier 2 fine label.) and optionally a bounding box. 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 the placetypeplacetypeThe Who's On First hierarchical classification of places: planet → continent → country → region → county → locality → neighbourhood. The resolver uses placetype to rank candidates — an exact locality match outranks a county-level match. alongside the coordinate, so the downstream system knows whether it received a point for a building, a centroid for a citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy., or an approximate coordinate for a 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..

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 top-K candidates, not a single coordinate. Springfield returns 34 candidates, each with a coordinate and placetypeplacetypeThe Who's On First hierarchical classification of places: planet → continent → country → region → county → locality → neighbourhood. The resolver uses placetype to rank candidates — an exact locality match outranks a county-level match.. The downstream system can display them on a map, offer a selection UI, or aggregate them statistically. 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. does not pretend that there is one correct coordinate for an ambiguous address.

Vertical resolution is outside Mailwoman's scope. The schema has a unit tag for apartment and suite numbers, but 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. does not 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.' elevation. A unit=4B address resolves to the building centroid, not Floor 4, Unit B. Vertical resolution requires building-interior data (floor plans, unitunitA subdivision of a building — apartment, suite, floor — that refines a street address. Mailwoman's unit component; a designator plus identifier forms a subpremise. layouts) that no open 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. provides. This is a commercial address verification problem (SmartyStreets, Melissa Data), not an open-source parser problem.

Moving addresses are outside Mailwoman's scope. A houseboat's current berth is a 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. question — the parser correctly extracts Berth 42, Marina del Rey as a location component, but 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. needs a current marina database to map that to coordinates. The parser's job is structural — "this is a location reference" — not "this is where it currently is."

What Mailwoman still can't do​

  • Vertical disambiguation. Two addresses at the same building but different floors resolve to the same coordinate. The unit tag preserves the floor/apartment information in the output, but 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. does not use it for spatial disambiguation.
  • Non-building addresses. 50 miles West of Socorro — the parser can identify "Socorro" as a localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. reference, but "50 miles West of" is a relative offset that requires spatial computation, not 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. Mailwoman's 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. does not compute relative offsets from 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. points.
  • Shape output. 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 a coordinate and optionally a bounding box from WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations.. It does not return the building footprint, the parcelparcelA property polygon or record carrying a situs (site) address and often a separate owner mailing address. County GIS parcel aggregations are a training source for address-point variety and situs-vs-owner divergence. boundary, or the ZIP code area. Shape-level output requires a spatial database (PostGIS, Elasticsearch with geo_shape), not a SQLite point-in-polygon index.
  • Elevation data. WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. does not include elevation. Address-level elevation requires a DEM (Digital Elevation Model) lookup at the coordinate, which is a GIS operation, not a 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. operation.

References​