Exotic point-of-interest queries

Not every geocoder query is an address. A large fraction of real-world searches ask for points of interest — 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., categories of things, brands, landmarks, and transit infrastructure: "Find the nearest gas station," "Where is the Eiffel Tower?", "Show me every Hilton in Manhattan." None of these are addresses.

These queries are structurally different from address queries. An address has ordered components (number, streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels., citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy., stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality., 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.) with predictable patterns. A POI query is a name, a category, or a category with a location constraint. The parser that handles 350 5th Ave, New York, NY 10118 will fail on water fountain near me — not because the parser is broken, but because the input is a different kind of query.

This series catalogues the categories of 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. queries, how traditional geocoders handle them, and what Mailwoman's architecture does (and doesn't) do for each.

Try it — an in-browser tester for the shipped category branch: type a query, see the detected subject and anchor, and get either ranked results or an OverpassQL export.

Categories

Query type	Example	What the user wants
Amenities	water fountain, gas station, ATM, restroom	The nearest instance of a generic category
Franchises and brands	Walmart, McDonalds, Hilton, Starbucks	The nearest or all locations of a named chain
Regional variants	servo, bodega, マクド, off-licence, chemist	The same thing as an amenityamenityA point of interest referenced by category ('gas station', 'pharmacy', 'ATM') rather than by name. Resolved by mapping the query onto a category taxonomy. or brand, but using local terminology
Landmarks	Eiffel Tower, Golden Gate Bridge, Empire State Building	A specific named placevenueA 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., usually unique or nearly unique
Transit	subway station, bus stop, airport, train station	A transit facility, named or unnamed

Why POI queries break the parser

Mailwoman's parser is designed for address strings. Its output is {house_number: 123, street: Main St, locality: Springfield, region: IL} — structured address components. A POI query like gas station has none of these components. Handed to the address parser alone, gas and station would get forced into 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 localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. guess and produce a low-confidence 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 right behavior for a 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. query is:

1. Recognize that it's a 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. query, not an address. The kind classifierkind classifierStage 2.5 of the runtime pipeline: categorizes the input into one of seven query kinds (structured_address, postcode_only, locality_only, intersection, po_box, landmark, vague) so the coordinator can route to the right parsing strategy. (StagestageOne 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). 2.5) carries a poi_query kind alongside postcode_only, structured_address, intersection, and the rest, driven by the poiQueryKind runtime flag (default-ON since 2026-07-20). Try it against a category query like fire hydrant.
2. Extract 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. type and location constraint. gas station near Springfield, IL splits into category gas_station and anchor Springfield, IL. The anchor is an address or place nametoponymA proper name for a geographic place., and it runs through the normal 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. 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. once split off.
3. Resolve against a 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. database. With a built poi.db, the executor answers "nearest gas station" with distance-ranked results, nearest first. Without one, the 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. still reports the matched category and anchor but cannot rank results.

What ships today

The category branch — detect, extract, resolve — is built:

• Detection + extraction. The kind classifierkind classifierStage 2.5 of the runtime pipeline: categorizes the input into one of seven query kinds (structured_address, postcode_only, locality_only, intersection, po_box, landmark, vague) so the coordinator can route to the right parsing strategy. matches category phrases against the @mailwoman/poi-taxonomy lexicon (23 categories in the current seed, with localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.-gated synonyms), then splits the anchor off and 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. it through the normal address 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..
• poi.db. A sealed, readonly spatial 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. built from Overture Places (CDLA-Permissive-2.0) at confidence ≥ 0.85, covering the US, Canada, Mexico, and France — the localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. Mailwoman already trains against. Build it yourself with mailwoman gazetteer build poi.
• The CLI. mailwoman poi "coffee near Honolulu" --db poi.db returns distance-ranked results — a live run against a built database returned 20 results, nearest 1,265 m away.
• @mailwoman/mcp. An MCP server (mailwoman-mcp) exposing five stdio tools to agents: mailwoman_parse, mailwoman_geocode, mailwoman_poi_search, mailwoman_overpass_export, mailwoman_layer_manifest. This is the intended consumer for most 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. queries: an agent calling tools, with the planning left to the agent.
• OverpassQL export. --overpass on the CLI, the matching MCP tool, and the tester all render a query you can paste into Overpass Turbo. Overpass is an export target here, never a serving backend — Mailwoman prints the query and never runs it.

What abstains by design

Some categories — fire hydrants, post boxes, drinking water fountains, data centers — have no permissively licensed source. They live in 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. and in Overture's base theme, both ODbL share-alike. Mailwoman ships the builder, not the data: run poi build --source osm against your own 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. extract and the resulting 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. sits on the same schema as the shipped one, on your disk, never distributed by us.

Until you've built that 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., a query for one of these categories abstains with requires_build_local_layer — a distinct result that names the missing 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., rather than an empty list that reads as "no such places exist."

What's still ahead

• Brand and franchise detection. The taxonomy lexicon matches categories, not chains — there's no brand lexicon yet, and no Wikidata QID table joining "Walmart" or "McDonalds" to Overture's brand.wikidata field. See Franchise queries.
• Proximity-search products. The CLI and MCP tool answer "nearest X" today; turning that into a packaged product (routing, open-now filtering, review scores) is out of scope for now.
• Read-time ancestry. Results don't yet carry 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. ancestry or a gers_id for cross-referencing against other Overture-keyed data. Recorded as debt against the current spec.
• Landmarks and transit codes. Named-landmark disambiguation and airport/station code resolution aren't part of the taxonomy lexicon. See Landmark queries and Transit queries.
• More localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.. poi.db covers the same four countries the parser trains against today; expanding either expands both.

See also

• What is an address? — the boundary between addresses and POIspoint 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.
• Why a neural parser? — the architecture that could handle both
• The knowledge ladder — where query-type classification fits in the 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.