Google Maps Platform
The question
You can start 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. this afternoon with an API key and a fetch call. Alternatively, you can install a package, download 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., and geocode in a process you already run. Both approaches work. They are built for different situations, and they differ mainly in where the data lives and who operates it.
What Google Maps Platform is
The Geocoding API is a hosted HTTP service. Its own documentation, read on 2026-08-04, defines it as:
"The Geocoding API is a service that accepts a place as an address, latitude and longitude coordinates, or Place ID. It converts the address into latitude and longitude coordinates and a Place ID, or converts latitude and longitude coordinates or a Place ID into an address."
The same page describes forward 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., reverse 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., and 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. by Place ID, plus an Address Descriptors 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.. It notes that developers in the European Economic Area are covered by different terms with effect from 8 July 2025.
Understand the Place ID before you compare anything else, because the service is designed around it. A Place ID is a stable identifier into Google's own place graph. Once your records store Place IDs, they hold keys that resolve only in Google's system. That link is useful, because it keeps the geocoder, the Places data and the map rendering consistent. It also means the IDs cannot be used with another provider.
For what the service costs and what the terms permit, read Google's pricing and terms. Those pages change and depend on your usage. A copy quoted in another project's documentation can go stale, so read the originals.
What each one is built to do
| Google Maps Platform | Mailwoman | |
|---|---|---|
| Shape | Hosted HTTP service | npm package, in-process. HTTP servers optional |
| Where the query goes | Google's infrastructure | Your process |
| 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. | Global and uniform, without setup | Per-localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for., measured where claimed. A download 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. |
| Reference data | Google's, maintained by Google | Public registersinput 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. on your disk, refreshed by you |
| Identifier | Place ID into Google's place graph | A component decomposition, plus an address key you compute |
| Non-address queries | Landmarks, business names, partials | Not the design. The parser needs an address |
| What arrives | A matched place | Labeled spansspanA contiguous range of characters or tokens in the input string, tagged with an address component type (street, locality, postcode, etc.). Parsed addresses are represented as collections of spans, possibly nested in a tree. with offsets, plus a coordinate and a tier |
| Cost 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.' | Per request | Infrastructure and disk |
Two rows account for most of the decision.
"Where the query goes" can settle an evaluationevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. early, in either direction. If your addresses are patient records, employee home addresses, or other data your compliance team regulates, an in-process library keeps the data inside your systems, so the compliance question does not arise. If they are public business addresses, compliance is not a concern and this row does not matter.
"What arrives" decides how much of your own code you write. A hosted geocoder returns a matched place. If you need to know which characters of your input were 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., you must work that out downstream. A 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.-then-look-up parser returns the decomposition as its primary output, and deduplicationrecord matchingThe process of determining whether two database records refer to the same real-world entity. Mailwoman's matcher uses a geocode-first approach (match the resolved place, not the address string) with Fellegi-Sunter probabilistic scoring., validation, formatting and record matchingrecord matchingThe process of determining whether two database records refer to the same real-world entity. Mailwoman's matcher uses a geocode-first approach (match the resolved place, not the address string) with Fellegi-Sunter probabilistic scoring. all need that decomposition. If you need only a coordinate, this row makes no difference.
When to choose Google Maps Platform
In the situations below, a hosted geocoder is the correct engineering decision, and installing Mailwoman would be a mistake.
- Your queries are not addresses. Examples include "Starbucks near Union Station", a business name without 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., or a half-typed landmark. These are place-search problems over a business graph, and a parser has no field to 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.. Mailwoman will still 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. the input, and the result will be wrong.
- You need uniform global 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. today. A hosted API covers every 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. the day you sign up. Mailwoman covers the localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. where a coordinate-graded evaluationevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. exists, and results elsewhere are unverified. See Locales and tiers. If your file spansspanA contiguous range of characters or tokens in the input string, tagged with an address component type (street, locality, postcode, etc.). Parsed addresses are represented as collections of spans, possibly nested in a tree. 40 countries and you cannot wait for tiers, choose the hosted service.
- You already use the Google ecosystem. If you render Google maps, use Places, and store Place IDs, a second geocoder gives you two place graphs to reconcile. Consistency within one system outweighs the marginal benefits of another one.
- Your volume is low and engineering time is scarce. Below the volume where per-request pricing becomes a material cost, sourcing and refreshing reference data is ongoing work that gains you no benefit.
- You have no place to put 2.88 GB. 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. needs a disk. A serverless function with a small 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. limit and no attached volume is a poor host for this design. Deploy serverless describes the shapes that work.
When to choose Mailwoman
- The addresses cannot leave your systems. Mailwoman sends no query data out of your process, and the other benefits follow from that.
- You need fields rather than only a point. Mailwoman returns spansspanA contiguous range of characters or tokens in the input string, tagged with an address component type (street, locality, postcode, etc.). Parsed addresses are represented as collections of spans, possibly nested in a tree. with offsets into your original string. Deduplicationrecord matchingThe process of determining whether two database records refer to the same real-world entity. Mailwoman's matcher uses a geocode-first approach (match the resolved place, not the address string) with Fellegi-Sunter probabilistic scoring. and validation can use those offsets.
- The volume makes per-request pricing your largest line item. Mailwoman replaces that cost with infrastructure and disk. Those costs grow differently with volume.
- You want to store the results indefinitely. Reference data on your disk is usable as far as the source license permits, and you read that license instead of a service agreement.
- You need to inspect or override a wrong answer. Every resolved spanspanA contiguous range of characters or tokens in the input string, tagged with an address component type (street, locality, postcode, etc.). Parsed addresses are represented as collections of spans, possibly nested in a tree. identifies 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. record it landed on, so you can trace a bad result to the stagestageOne 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). that produced it.
Run it yourself
You can check both claims above on your own file. Our published numbers come from two panels, and their scripts are public:
curl -fsSLO https://mailwoman.ai/benchmarks/be-panel.mjs
curl -fsSLO https://mailwoman.ai/benchmarks/be-panel.json
mailwoman data pull candidate
node be-panel.mjs --data-root <DATA_ROOT>
Benchmarks has the results and the method. To test your addresses,
replace the panel file with your own rows, and be-panel.mjs grades them.
Related
- The landscape — hosted, self-hosted and in-process, with the bounded case where none of them is needed.
- Eliminate the per-request bill — the volume argument, worked.
- Keep addresses inside — the residency argument, worked.
- Locales and tiers — the 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. boundary.