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., not 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 four 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>/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. shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. 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 same-named placesvenueA 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. population-first, is the backend the hosted demo uses, and since 8.7.0 is the default: a candidate.db at <data root>/wof/candidate.db is picked up with nothing configured. 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, which 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 — it's in the input line — and then nothing was consulted 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. 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 nothing, 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.sister.software/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.sister.software/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, which carries 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, which has 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. shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row..

--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 nothing reports an error, because a shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. with no matching row and a shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. 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. shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row., which 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.sister.software/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.sister.software/mailwoman/street/us/dc/situs.db
[DEBUG] (mailwoman data): 200 (uncached) HEAD: https://public.sister.software/mailwoman/street/us/dc/situs.db
▸ pull https://public.sister.software/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.sister.software/mailwoman/street/us/dc/interp.db
[DEBUG] (mailwoman data): 200 (uncached) HEAD: https://public.sister.software/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 shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. 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, same shell, nothing else 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 carry:

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 shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. 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 four tiers

resolution_tier takes one of four values, best first. 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, not 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
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

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-gate → kind-classifier → phrase-grouper → classifier → decoder) connected by typed handoffs. Each stage is published as its own npm package. gets", not "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 shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. 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. carries 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 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. alone, 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 postal code (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.

That ordering matters when the localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy. is missing. A bare 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 nothing above it:

npx mailwoman geocode "20004" --format text

input:            20004
resolution_tier:  admin
coordinate:       53.093382, 14.259291
postcode:         20004

That is in Germany. 20004 is a valid 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. in at least Germany, Spain, the United States and Poland — this 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. holds a row for each — and a bare five-digit string carries nothing that says which. --locale en-US does not rescue it: 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, which is the same design that lets a French address resolve in France while the localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. still reads en-US. Nothing scoped this query, so the global ranking decided it.

A bare 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 ambiguous across countries and the result will not warn you — so scope it, either with --default-country or by sending the citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy. along with it:

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

input:            20004
resolution_tier:  admin
coordinate:       38.894885, -77.028638
postcode:         20004

Still admin, because 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. centroid is an admin coordinate — but 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 1,521 m. When 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. shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. are missing, a resolved 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 a much better answer than a resolved citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy., and the tier labelcomponent tagOne of the 25 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. does not distinguish them. Read hierarchy when you need to know which one you got.

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 gate, 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. shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row., 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.sister.software/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 the shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. 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. shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row., 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 carry 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 nothing between — 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. Parsing French addresses well is 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

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, which is the shape every deployment has — 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.