Improve geocode precision

Every geocode you have run so far answered resolution_tier: "admin" — a coordinate for the citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy. rather than for the building. By the end of this page you'll have moved one address 1,521 m, from a city centroidlocality centroidThe representative center point of a city or locality, used as a coarse coordinate when no exact address point is available — the coarsest tier of the geocode cascade. to its rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few meters — the highest tier of the geocode cascade. Sourced from address-point and situs data., with a 127 MB download. You'll know what the seven tiers are and which download reaches which. And you'll know what uncertainty_m is measuring in each one. About twenty minutes.

Prerequisites

• candidate.db on disk, at <data root>/db/wof/candidate.db. Your first ten minutes covers the download.
• About 127 MB of free disk for 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. databases this page pulls, and $MAILWOMAN_DATA_ROOT pointing where you want them. The full US streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. tier is 103 files and about 41.3 GB, so this page pulls one jurisdiction — the District of Columbia, small on disk and dense enough in rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few meters — the highest tier of the geocode cascade. Sourced from address-point and situs data. coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. to show both streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. tiers inside one state.
• mailwoman data pull ships in 8.7.0. If npm view mailwoman version still prints 8.6.0 for you, the CLI is on its way to npm and the URLs in the dry-run below are downloadable by hand in the meantime.

The backend this assumes

One paragraph of recap, because everything below depends on it. The candidate-table 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. ranks places that share a name population-first, is the backend the hosted demo uses, and since 8.7.0 is the default: a candidate.db at <data root>/db/wof/candidate.db is picked up with no configuration. The alternative is a full-text-search path over 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. admin distribution. That path ranks by relevance instead and answers some queries differently. You reach it by pinning --candidate-db none, and it is not a comparison you can run here anyway, because data pull publishes no bundleevidence bundleThe pair of retrieval-augmented input channels (street-type + locality-surface) that feed lexicon membership as soft per-token evidence alongside the text. Shipped in 6.7.0; trained natively from step 0 in the from-scratch base line. for that database and it has to be built locally. The download is on Your first ten minutes. This page assumes you did it.

1. See the tier you have

npx mailwoman geocode "1275 Pennsylvania Ave NW, Washington, DC 20004" --format text

input:            1275 Pennsylvania Ave NW, Washington, DC 20004
resolution_tier:  admin
coordinate:       38.904831, -77.016216
locality:         Washington
region:           DC
postcode:         20004
hierarchy:
  locality             Washington [wof:85931779] (38.9048, -77.0162)
  region               DC [wof:85688741] (38.9048, -77.0163)

The house numberhouse numberThe numeric or alphanumeric identifier of a building on a street. Mailwoman's house_number component; its position relative to the street name flips between locales. was parsed, and it is in the input line, yet no source that knows where house numbershouse numberThe numeric or alphanumeric identifier of a building on a street. Mailwoman's house_number component; its position relative to the street name flips between locales. are was consulted. The coordinate is Washington's, identical to the one every other Washington address returns. No uncertainty_m line, because the admin tier does not report one.

2. Check what the download costs before you start it

--dry-run touches the network only to plan, writes no file, and prints the exact bytes and destinations.

npx mailwoman data pull us --only dc --dry-run

✓ us: street/us/dc/situs.db: [dry-run] 119.9 MB
https://public.mailwoman.ai/mailwoman/street/us/dc/situs.db →
/tmp/mw-trial/mailwoman-data/address-points/address-points-us-dc.db
✓ us: street/us/dc/interp.db: [dry-run] 7.4 MB
https://public.mailwoman.ai/mailwoman/street/us/dc/interp.db →
/tmp/mw-trial/mailwoman-data/interpolation/interpolation-us-dc.db

Two files, two tiers. situs.db is the rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few meters — the highest tier of the geocode cascade. Sourced from address-point and situs data. registerinput modeThe Decision-A register switch: 'fragmented' (human-typed fragments — feeds the evidence channels) vs 'formatted' (complete records — runs the trained absence identity). Explicit on CLI/API; per-endpoint defaults (batch→formatted, autocomplete→fragmented); kind-derived otherwise.: address pointssitus dataA dataset of exact address-point coordinates (rooftop-level). Mailwoman's geocoder uses a national situs layer (124.9M US points built from state address-point sources) as the highest-precision tier of the geocode cascade. with a coordinate each. interp.db is the TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. network. It stores a house-number range per segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. and estimates a position along it. Every state ships both, except the US Virgin Islands. The US Virgin Islands have no interpolationinterpolationA geocoding technique that estimates a coordinate along a street segment based on the house number range. Used as the middle tier of Mailwoman's geocode cascade when exact address-point data is unavailable. database.

--only matches on the slug, the remote path or the local path, so --only dc picks the two DC files out of the 103. Drop it and you get the whole 41.3 GB tier.

A small download is not a cheap state, and the plan is where you can tell the two apart. New Hampshire's rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few meters — the highest tier of the geocode cascade. Sourced from address-point and situs data. registerinput modeThe Decision-A register switch: 'fragmented' (human-typed fragments — feeds the evidence channels) vs 'formatted' (complete records — runs the trained absence identity). Explicit on CLI/API; per-endpoint defaults (batch→formatted, autocomplete→fragmented); kind-derived otherwise. downloads, verifies and installs at 20,480 bytes — and holds 0 rows. The file exists. The tier it should serve does not, and no error is reported, because a database with no matching row and a database with no rows at all look identical from the lookup. NH addresses fall through to its interpolationinterpolationA geocoding technique that estimates a coordinate along a street segment based on the house number range. Used as the middle tier of Mailwoman's geocode cascade when exact address-point data is unavailable. database. That database is a real 57.6 MB. Read the sizes in the dry-run as a coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. signal before you plan around a state.

3. Pull it

npx mailwoman data pull us --only dc

▸ pull https://public.mailwoman.ai/mailwoman/street/us/dc/situs.db (~119.9 MB) → /tmp/mw-trial/mailwoman-data/address-points/address-points-us-dc.db
[DEBUG] (mailwoman data): HEAD: https://public.mailwoman.ai/mailwoman/street/us/dc/situs.db
[DEBUG] (mailwoman data): 200 (uncached) HEAD: https://public.mailwoman.ai/mailwoman/street/us/dc/situs.db
▸ pull https://public.mailwoman.ai/mailwoman/street/us/dc/interp.db (~7.4 MB) → /tmp/mw-trial/mailwoman-data/interpolation/interpolation-us-dc.db
[DEBUG] (mailwoman data): HEAD: https://public.mailwoman.ai/mailwoman/street/us/dc/interp.db
[DEBUG] (mailwoman data): 200 (uncached) HEAD: https://public.mailwoman.ai/mailwoman/street/us/dc/interp.db
✓ us: street/us/dc/situs.db: content-length verified (119.9 MB) → /tmp/mw-trial/mailwoman-data/address-points/address-points-us-dc.db
✓ us: street/us/dc/interp.db: content-length verified (7.4 MB) → /tmp/mw-trial/mailwoman-data/interpolation/interpolation-us-dc.db
PASS (2/2 checks)

21 seconds on this connection. The [DEBUG] lines are the download client asking the remote how big the file is before it starts; content-length verified is that same number checked against what landed. There is no checksum in that check, because the bucket publishes no checksum sidecar. A truncated transfer is caught, a corrupted one of the right length is not.

No configuration follows. The databases are found by filename under the data root, keyed to the regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. the 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. resolved.

4. See the tier you have now

Same command and same shell, with no other setting changed:

npx mailwoman geocode "1275 Pennsylvania Ave NW, Washington, DC 20004" --format text

input:            1275 Pennsylvania Ave NW, Washington, DC 20004
resolution_tier:  address_point
coordinate:       38.895665, -77.029255
uncertainty_m:    1
locality:         Washington
region:           DC
postcode:         20004
hierarchy:
  locality             Washington [wof:85931779] (38.9048, -77.0162)
  region               DC [wof:85688741] (38.9048, -77.0163)

address_point, and the coordinate moved 1,521 m — from the middle of the District to the building. The hierarchy block did not change: the admin ancestry is still Washington and DC, still at the centroid coordinates. The rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few meters — the highest tier of the geocode cascade. Sourced from address-point and situs data. is the answer. The hierarchy is the context.

Now one the rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few meters — the highest tier of the geocode cascade. Sourced from address-point and situs data. registerinput modeThe Decision-A register switch: 'fragmented' (human-typed fragments — feeds the evidence channels) vs 'formatted' (complete records — runs the trained absence identity). Explicit on CLI/API; per-endpoint defaults (batch→formatted, autocomplete→fragmented); kind-derived otherwise. does not contain:

npx mailwoman geocode "620 H St NE, Washington, DC 20002" --format text

input:            620 H St NE, Washington, DC 20002
resolution_tier:  interpolated
coordinate:       38.900204, -76.997978
uncertainty_m:    141
locality:         Washington
region:           DC
postcode:         20002
hierarchy:
  locality             Washington [wof:85931779] (38.9048, -77.0162)
  region               DC [wof:85688741] (38.9048, -77.0163)

interpolated, and a radius you can act on. The second database found the H St NE segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. whose house-number range contains 620 and placed the point proportionally along it.

5. Read the seven tiers

resolution_tier takes one of seven values. The five in the ladder below are ordered best first. The last two come from a different route. Check it on every result. It is how a coordinate tells you what kind of coordinate it is.

Tier	Source	uncertainty_m
address_point	the state's rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few meters — the highest tier of the geocode cascade. Sourced from address-point and situs data. registerinput modeThe Decision-A register switch: 'fragmented' (human-typed fragments — feeds the evidence channels) vs 'formatted' (complete records — runs the trained absence identity). Explicit on CLI/API; per-endpoint defaults (batch→formatted, autocomplete→fragmented); kind-derived otherwise. (situs.db)	1 — a floor rather than a measurement
interpolated	the TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. network (interp.db)	the calibrated bracket, 141 above
street	a national registerinput modeThe Decision-A register switch: 'fragmented' (human-typed fragments — feeds the evidence channels) vs 'formatted' (complete records — runs the trained absence identity). Explicit on CLI/API; per-endpoint defaults (batch→formatted, autocomplete→fragmented); kind-derived otherwise.'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. centroids	half 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.'s bounding-box diagonal
postcode	the postcodepostcodeThe country-specific postcode (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one.'s own row in candidate.db	half the row's extent diagonal, or null for a point-only row
admin	the 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., candidate.db	null — no sub-localitydependent localityA sub-locality (neighborhood or borough) hierarchically inside a larger locality — e.g. Brooklyn within New York City. Provides finer geographic specification below the primary locality. estimate exists
venue	a matched place nametoponymA proper name for a geographic place. in the POIpoint of interest (POI). A named place that is not strictly an address — landmark, transit stop, venue, amenity, or franchise. Mailwoman tags these as venue and resolves them through the gazetteer. layerlayerOne 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.	the 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. match's own radius
plus_code	a plus code in the input, decoded to its cell	half the cell's diagonal, at least 1

Three notes on that table.

The 1 at the rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few meters — the highest tier of the geocode cascade. Sourced from address-point and situs data. tier is a constant. The situssitusThe physical site address of a property, as opposed to the owner's mailing address. Parcel records often carry both; the divergence is a real-world data-quality challenge. point is 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. or building coordinate and the code writes a 1 m floor rather than a measured error. It means "this is as good as this pipelinestaged pipelineMailwoman's runtime architecture: a sequence of pure-function stages (normalize → query-shape → locale-hint → kind-classifier → phrase-grouper → classifier → decoder) connected by typed handoffs. Each stage is published as its own npm package. gets" rather than "this is accurate to a meter".

The 141 at the interpolated tier is calibrated, and per regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality.. The raw radius — half the matched segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context.'s length — covers about 72% of true errors, so it is multiplied by a per-regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. conformal factor for roughly a 90% bound. The measured factors run 1.44 for DC, the densest, to 3.12 for Arizona, with 1.95 applied to states the sweep did not reach. The table is embedded in interp-calibration.ts and states its own source.

The street tier needs a database no published bundleevidence bundleThe pair of retrieval-augmented input channels (street-type + locality-surface) that feed lexicon membership as soft per-token evidence alongside the text. Shipped in 6.7.0; trained natively from step 0 in the from-scratch base line. contains today. It comes from a national registerinput modeThe Decision-A register switch: 'fragmented' (human-typed fragments — feeds the evidence channels) vs 'formatted' (complete records — runs the trained absence identity). Explicit on CLI/API; per-endpoint defaults (batch→formatted, autocomplete→fragmented); kind-derived otherwise.'s derived streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.-centroid database, built locally. The fr bundleevidence bundleThe pair of retrieval-augmented input channels (street-type + locality-surface) that feed lexicon membership as soft per-token evidence alongside the text. Shipped in 6.7.0; trained natively from step 0 in the from-scratch base line. ships only the rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few meters — the highest tier of the geocode cascade. Sourced from address-point and situs data. registerinput modeThe Decision-A register switch: 'fragmented' (human-typed fragments — feeds the evidence channels) vs 'formatted' (complete records — runs the trained absence identity). Explicit on CLI/API; per-endpoint defaults (batch→formatted, autocomplete→fragmented); kind-derived otherwise., and the per-state US provider never opens one. Until that changes, 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.-only query falls to admin.

6. The admin tier is a ladder too

admin is not one coordinate source. When 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.-level tier answers, 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. walks the resolved nodes in a fixed order — localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy., then dependent localitydependent localityA sub-locality (neighborhood or borough) hierarchically inside a larger locality — e.g. Brooklyn within New York City. Provides finer geographic specification below the primary locality., then postcodepostcodeThe country-specific postcode (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one., then regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality., then 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. — and takes the first with a coordinate. Which is why the DC address in step 1 returned Washington's centroid and not its ZIP Code's, even though both resolved.

When the postcodepostcodeThe country-specific postcode (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. supplies the coordinate, the tier reports that. A bare postcodepostcodeThe country-specific postcode (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. has no localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy. above it:

npx mailwoman geocode "20004" --default-country US --format text

input:            20004
resolution_tier:  postcode
coordinate:       38.894885, -77.028638
uncertainty_m:    926
postcode:         20004

The postcode tier is the postcodepostcodeThe country-specific postcode (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one.'s own row: 102 m from the rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few meters — the highest tier of the geocode cascade. Sourced from address-point and situs data. in step 4 rather than the citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy. centroid's 1,521 m. Its uncertainty_m is half the diagonal of the extent stored for the postcodepostcodeThe country-specific postcode (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one., and it is null when the source stores the postcodepostcodeThe country-specific postcode (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. as a single point, as the UK's Code-Point Open does.

20004 is also a valid postcodepostcodeThe country-specific postcode (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. in Germany, Spain and Poland, and a bare five-digit string has no signal saying which. With the candidate backend active the localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. stops implying a 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. filter, so scope a bare postcodepostcodeThe country-specific postcode (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. with --default-country or send the citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy. along with it.

7. Outside the US

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. tier is per 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., and France is the one with a published national registerinput modeThe Decision-A register switch: 'fragmented' (human-typed fragments — feeds the evidence channels) vs 'formatted' (complete records — runs the trained absence identity). Explicit on CLI/API; per-endpoint defaults (batch→formatted, autocomplete→fragmented); kind-derived otherwise.: data pull fr stagesstageOne of the dataflow stages in the runtime pipeline (normalize, locale check, kind classify, phrase group, token classify, sequence correct, reconcile, resolve). Distinct from tier (model vocabulary) and phase (plan milestone). the BANBAN (Base Adresse Nationale). France's authoritative open national address register — the highest-quality training source for French addresses, with full component structure. rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few meters — the highest tier of the geocode cascade. Sourced from address-point and situs data. registerinput modeThe Decision-A register switch: 'fragmented' (human-typed fragments — feeds the evidence channels) vs 'formatted' (complete records — runs the trained absence identity). Explicit on CLI/API; per-endpoint defaults (batch→formatted, autocomplete→fragmented); kind-derived otherwise., 26 million points under the Licence Ouverte.

npx mailwoman data pull fr --dry-run

✓ fr: street/fr/2026-07-10/situs.db: [dry-run] 6952.5 MB
https://public.mailwoman.ai/mailwoman/street/fr/2026-07-10/situs.db →
/tmp/mw-trial/mailwoman-data/ban/address-points-fr.db

Nearly 7 GB, against 127 MB for the District of Columbia — check that number against your free disk before you start it. With that registerinput modeThe Decision-A register switch: 'fragmented' (human-typed fragments — feeds the evidence channels) vs 'formatted' (complete records — runs the trained absence identity). Explicit on CLI/API; per-endpoint defaults (batch→formatted, autocomplete→fragmented); kind-derived otherwise. in place, French addresses answer at the rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few meters — the highest tier of the geocode cascade. Sourced from address-point and situs data. tier with no localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. flag and no other change:

npx mailwoman geocode "12 Rue de Rivoli, 75004 Paris" --format text

input:            12 Rue de Rivoli, 75004 Paris
resolution_tier:  address_point
coordinate:       48.855602, 2.359950
uncertainty_m:    1
locality:         Paris
postcode:         75004
hierarchy:
  locality             Paris [wof:1159322569] (48.8566, 2.3428)

The hierarchy block survives the tier change here exactly as it did in DC: Paris still at its own centroid, underneath a rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few meters — the highest tier of the geocode cascade. Sourced from address-point and situs data. coordinate 1,257 m away from it.

One gap to plan around, and it is structural rather than temporary. France ships a rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few meters — the highest tier of the geocode cascade. Sourced from address-point and situs data. registerinput modeThe Decision-A register switch: 'fragmented' (human-typed fragments — feeds the evidence channels) vs 'formatted' (complete records — runs the trained absence identity). Explicit on CLI/API; per-endpoint defaults (batch→formatted, autocomplete→fragmented); kind-derived otherwise. and no interpolationinterpolationA geocoding technique that estimates a coordinate along a street segment based on the house number range. Used as the middle tier of Mailwoman's geocode cascade when exact address-point data is unavailable. database, so a house numberhouse numberThe numeric or alphanumeric identifier of a building on a street. Mailwoman's house_number component; its position relative to the street name flips between locales. BANBAN (Base Adresse Nationale). France's authoritative open national address register — the highest-quality training source for French addresses, with full component structure. does not contain falls straight to admin. There is no middle tier to catch it, the way 620 H St NE was caught in DC. Rue de Rivoli runs to number 258 in BANBAN (Base Adresse Nationale). France's authoritative open national address register — the highest-quality training source for French addresses, with full component structure., so 500 is off the end of it:

npx mailwoman geocode "500 Rue de Rivoli, 75004 Paris" --format text

input:            500 Rue de Rivoli, 75004 Paris
resolution_tier:  admin
coordinate:       48.856599, 2.342841
locality:         Paris
postcode:         75004
hierarchy:
  locality             Paris [wof:1159322569] (48.8566, 2.3428)

An FR result is therefore rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few meters — the highest tier of the geocode cascade. Sourced from address-point and situs data. or citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy., with no intermediate tier, so branch on resolution_tier rather than on uncertainty_m being small, and treat an admin answer in France as a miss to re-check rather than as a coarse hit. The French address 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.' requires a separate download, @mailwoman/neural-weights-fr-fr; What ships today has the per-localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. picture.

What you have now

You have a data root that answers rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few meters — the highest tier of the geocode cascade. Sourced from address-point and situs data. coordinates for one jurisdiction and city centroidslocality centroidThe representative center point of a city or locality, used as a coarse coordinate when no exact address point is available — the coarsest tier of the geocode cascade. everywhere else. Every deployment has that shape. The question is only which jurisdictions you downloaded. Pull the states your customers are in with --only, check resolution_tier on every result, and read uncertainty_m as a bound rather than as an error bar.

Next

• Geocode a CSV of customer addresses — the same tiers, per row, at file scale.
• What ships today — which countries have 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. tier at all.