Why not use geocode.earth?
If Google's API is the proprietary default, geocode.earth is the open-source default. It runs PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. — the geocoder Mailwoman forked — as a hosted service with 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., open data, and transparent pricing. For many applications, geocode.earth is the right answer. For applications that need to own their parser, it has the same fundamental limitation as every hosted API: you do not own the parsingaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. 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..
What geocode.earth is
Geocode.earth is a hosted 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. service built on PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor., the open-source 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. engine. It uses the same rule-based parser that Mailwoman v1 was built on, combined with Elasticsearch-backed 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 against Who's On FirstWOF (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., OpenStreetMapOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names., OpenAddressesOpenAddresses (OA). A global open aggregation of address points collected from many official sources. A primary source of component-supervised training data outside proprietary registries., and other open data sources.
The key differences from Google:
| Factor | geocode.earth | |
|---|---|---|
| Parser | Proprietary, neural (assumed) | PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor., rule-based (open-source) |
| Data sources | Proprietary, global | 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., OSMOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names., OpenAddressesOpenAddresses (OA). A global open aggregation of address points collected from many official sources. A primary source of component-supervised training data outside proprietary registries. — all open |
| Pricing | $5/1K requests | ~$0.50/1K requests |
| Terms | No caching beyond 30 days | Cacheable, self-hostable |
| Audit trail | No | Yes — open data sources are traceable |
| Self-hosting | No | Yes — PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. is open-source |
Geocode.earth's core selling point is that you can inspect the data, run it yourself, or pay them to run it for you. The hosted service is a convenience, not a lock-in.
Pelias parser
Geocode.earth uses the same PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. rule-based parser that Mailwoman v1 was forked from. This parser is:
- Deterministic. The same input always produces the same output.
- Debuggable. When a classification is wrong, you can read the rule and see why.
- Battle-tested. PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. has been 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. addresses in production since 2014.
It also has the same limitations that motivated Mailwoman's neural classifierneural 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.':
- The tokenization tautology. Rules classify 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. independently; context-dependent decisions (multi-word place namestoponymA proper name for a geographic place., 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.-vs-address ambiguity) require solver post-processing.
- The exception pile. Each new address format adds a new rule; rules accumulate and conflict.
- International fragility. Every localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. needs its own rule set, hand-written by someone who reads the language.
- No graceful degradation. Rules match or don't — binary. There is no confidence gradientgradientThe direction and rate at which the loss would change if each parameter were nudged. Training follows the gradient downhill to reduce error. Huge gradients are tamed by gradient clipping. between "confident" and "guess."
For geocode.earth's use case, these are acceptable tradeoffs: PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. on hosted infrastructure is fast, reliable, and good enough for most address formats. They are also why Mailwoman exists as a separate project, built to learn from data rather than encode every address shape as a rule.
Why not self-host Pelias?
If the parser is open-source, why not run your own PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. instance and avoid the API cost?
Self-hosting PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. is operationally expensive. A production PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. deployment requires:
- Elasticsearch cluster (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. index — hundreds of GB).
- Multiple data import pipelinesstaged 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. (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., OSMOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names., OpenAddressesOpenAddresses (OA). A global open aggregation of address points collected from many official sources. A primary source of component-supervised training data outside proprietary registries. — each requires downloading, transforming, and indexing).
- Ongoing data updates (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. is updated weekly, OSMOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names. continuously).
- Infrastructure management (Elasticsearch tuning, monitoring, failover).
The team at Geocode Earth estimates that running a production PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. instance costs $500-2,000 per month in infrastructure alone, plus engineering time for maintenance and updates. For a company with one or two full-time geospatial engineers, this is viable. For a team without dedicated infrastructure staff, it is not.
Geocode.earth's hosted service abstracts this cost: you pay per request instead of managing infrastructure. For most organizations, this is a better deal than self-hosting.
The parser is the ceiling
Whether you use geocode.earth's hosted service or self-host PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor., the parser is the same rule engine. If a specific address class fails — a regional addressing convention, a non-Western format, a 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.-vs-address ambiguity — you cannot fix it by paying geocode.earth more or by tuning Elasticsearch. The parser is the bottleneck, and the parser is rules.
Mailwoman exists because the parser ceiling is real and the only fix is a different parser architecture. A neural 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.' that learns from data can handle the long tail of address formats without accumulating rules. The neural parser can coexist with PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. — the policy registrypolicy registryThe per-component table that decides which classifier (rule or neural) has authority for each address component. The Ship-of-Theseus dial. lets you use the neural 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.' for components where it outperforms rules and keep the rule classifiers for components where they are already correct.
When geocode.earth is the right choice
Geocode.earth is the right choice when:
- You need 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. today and cannot invest in building a parser.
- You value open data and auditability over the highest possible accuracy.
- Your address volume is moderate (under 1M requests per month) and the API cost is lower than infrastructure cost.
- You need to self-host eventually but want to start with a hosted service.
- You are already in the PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. ecosystem and want a managed version.
When Mailwoman is the right choice
Mailwoman is the right choice when:
- You need to fix specific address failure modes that the PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. rule engine cannot handle.
- You want a parser that improves over time as you add trainingtrainingThe process of adjusting a model's parameters so its predictions match labeled examples, by repeatedly measuring error and nudging the weights to reduce it. Distinct from inference, when the trained model is run on new input. data.
- You need browser-side or edge deployment (the ONNX runtimeONNX (Open Neural Network Exchange). An open format for machine learning models that enables interoperability between training frameworks and inference runtimes. Mailwoman ships its trained model as an ONNX file so it can run in Node.js and the browser via onnxruntime. runs in environments where Elasticsearch cannot).
- You are building a new 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. product and want a parser with an explicit policy registrypolicy registryThe per-component table that decides which classifier (rule or neural) has authority for each address component. The Ship-of-Theseus dial. for component-level migration.
- You want structured candidate output with concordanceconcordanceA joint-decode signal that rewards a parse whose spans form a consistent Who's On First parent-child chain and vetoes contradictory ones — a hard veto for conflicts, a log-space bonus for full agreement. scoring rather than a single best-guess coordinate.
Mailwoman is not a geocode.earth competitor — it addresses a different 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. of the stack. Geocode.earth could run Mailwoman as its parser in the future. The projects are complementary: geocode.earth solves the infrastructure problem, Mailwoman solves the parser problem.
See also
- Why not just use Google's API? — the proprietary alternative
- From Pelias to Mailwoman — the fork history
- The tokenization tautology — the PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. parser's structural ceiling
- How it used to work — Mailwoman v1 (pre-fork PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor.) in detail