Switching from Photon

Photon is the type-ahead geocoder — search-as-you-type, GeoJSON out. It's also an Elasticsearch cluster you feed a Photon import before it answers anything. Mailwoman speaks the same /api contract from a SQLite file, so your autocomplete keeps working without the cluster.

Try it first. We host a live instance at photon.sister.software — nothing to install, no import to wait on. Open /api?q=berlin&limit=3 in a browser (or point your existing Photon client at the host) and read the GeoJSON that comes back. When it looks right, the one command below runs the same thing on your own machine.

One command

npx @mailwoman/photon serve --port 2322

curl "http://localhost:2322/api?q=berlin&limit=5&lat=52.5&lon=13.4"
curl "http://localhost:2322/reverse?lat=52.52&lon=13.405"

Endpoint map

Photon	Mailwoman	ParametersparameterA single learned number inside a model — one weight or bias. Mailwoman's encoder has roughly 30 million of them; training is the search for good values. honored
GET /api	GET /api	q, limit, lat/lon bias
GET /reverse	GET /reverse	lat / lon

limit returns the top-N ranked matches (an ambiguous name like Springfield yields each instance), and lat/lon is a proximity bias — the same query near different map centers re-ranks the results toward the viewport. lang and osm_tag are accepted for wire compatibility but not yet applied: lang because the 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.' ships a single (en-US) localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for., and osm_tag 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. filtering is on the roadmap.

Both return a GeoJSON FeatureCollection of Point featuresfeatureAn 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. with properties (name, street, postcode, city, county, state, country, countrycode, osm_key, osm_value, type, …) — the shape a Photon client already parsesaddress 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..

What's different

• No Elasticsearch. Resolution runs over the same SQLite 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. the rest of Mailwoman uses, and /api is backed by the FSTFST (finite-state transducer). A compact automaton that reads an input sequence and emits an output sequence. Mailwoman encodes gazetteer names and street affixes as FSTs for fast prefix matching and prior injection without search overhead. autocomplete tiertierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous. plus the neural parser.
• Properties come from the 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. / Overture placetypeplacetypeThe Who's On First hierarchical classification of places: planet → continent → country → region → county → locality → neighbourhood. The resolver uses placetype to rank candidates — an exact locality match outranks a county-level match. chain rather than raw 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. tags, mapped to Photon's key names.

What's missing

• Prefix ranking is its own art. Mailwoman's /api resolves the query through the geocoder today; the dedicated prefix-first FSTFST (finite-state transducer). A compact automaton that reads an input sequence and emits an output sequence. Mailwoman encodes gazetteer names and street affixes as FSTs for fast prefix matching and prior injection without search overhead. front is the refinement that closes the last gap with Photon's tuned type-ahead ordering.
• 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. mirrors 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. — strong in the US, improving across the EU.

Photon in the wild

For a sense of what Photon looks like in production, Cartes (an open-source French web map we admire) runs its own Photon instance and layerslayerOne 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. France's BAN address API on top for house-number queries. The pairing works well for them. It's also the kind of 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. shim a parser-first geocoder makes unnecessary: Mailwoman reads 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. in the query and resolves it against the same BANBAN (Base Adresse Nationale). France's authoritative open national address register — the highest-quality training source for French addresses, with full component structure. rooftop datasitus 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. directly.

See how Mailwoman compares for the full capability matrix and the longer Cartes note. For structured lookup (the Nominatim shape) instead of autocomplete, see Switching from Nominatim.