Amenity queries
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. query asks for the nearest instance of a generic category. The user doesn't care which gas station — they care which one is closest, open, or cheapest. The geocoder's job is to translate a category labelcomponent tagOne of the 33 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. into a set of candidate locations and rank them.
What amenity queries look like
| Query | Category | Implicit constraints |
|---|---|---|
gas station | amenity=fuel | Nearest to user's location |
water fountain | amenity=drinking_water | Nearest, publicly accessible |
ATM | amenity=atm | Nearest, preferably in-network |
restroom | amenity=toilets | Nearest, publicly accessible, open |
mailbox | amenity=post_box | Nearest, collection time not passed |
playground | leisure=playground | Nearest, open to public |
pharmacy | amenity=pharmacy | Nearest, open now |
hospital | amenity=hospital | Nearest, emergency department |
bicycle parking | amenity=bicycle_parking | Nearest, secure |
EV charging station | amenity=charging_station | Nearest, compatible plug, available |
pho near me | cuisine=vietnamese | Nearest Vietnamese restaurant |
coffee shop | amenity=cafe | Nearest, open |
The query has two parts: a category (what kind of thing) and an implicit location constraint (near where the user is, or near a specified place). The category is the hard part — the geocoder must map the user's words to a category taxonomy.
Category-taxonomy problem
"Gas station" in English maps to amenity=fuel in 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.'s taxonomy. "Gas station" in Australian English ("servo") maps to the same tag. "Petrol station" in British English also maps to the same tag. The same physical thing — a place that sells fuel for vehicles — has multiple names, and the geocoder must recognize all of them.
The problem compounds across languages: ガソリンスタンド (gasorin sutando, Japanese), 加油站 (jiāyóuzhàn, Chinese), Tankstelle (German), station-service (French). Every language has its own word for "gas station." A geocoder that only recognizes English amenityamenityA point of interest referenced by category ('gas station', 'pharmacy', 'ATM') rather than by name. Resolved by mapping the query onto a category taxonomy. names is useless for most of the world's population.
The geocoder isn't translating labelscomponent tagOne of the 33 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. between languages. "Gas station", "servo", Tankstelle, and station-service all point at one underlying category, the way English "road", Spanish "camino", and Japanese "通り" (do-ri) all name the same kind of thing. The geocoder maps each labelcomponent tagOne of the 33 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. to that shared, language-independent category (amenity=fuel) and searches it once.
How traditional geocoders handle amenity queries
Nominatim (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.'s geocoder) handles amenityamenityA point of interest referenced by category ('gas station', 'pharmacy', 'ATM') rather than by name. Resolved by mapping the query onto a category taxonomy. queries well because 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 every amenityamenityA point of interest referenced by category ('gas station', 'pharmacy', 'ATM') rather than by name. Resolved by mapping the query onto a category taxonomy. with a standardized key-value pair. amenity=fuel maps to every gas station in 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.. Nominatim's search API accepts free-text queries and matches them against 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 and names. gas station near Paris returns 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.-tagged fuel stations near Paris.
The limitation: Nominatim only searches 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.. If a gas station is not in 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., it doesn't exist to Nominatim. 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.'s amenityamenityA point of interest referenced by category ('gas station', 'pharmacy', 'ATM') rather than by name. Resolved by mapping the query onto a category taxonomy. 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. is excellent in Western Europe and sparse in much of the rest of the world. A query for gas station in rural India may return nothing because no one has mapped the gas stations there.
Google's Places API handles amenityamenityA point of interest referenced by category ('gas station', 'pharmacy', 'ATM') rather than by name. Resolved by mapping the query onto a category taxonomy. queries through Google's proprietary place taxonomy. The API accepts a type parameterparameterA 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. (e.g., gas_station, atm, pharmacy) and returns ranked results. Google's taxonomy is larger and more consistent than 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.'s, but it is proprietary — you cannot inspect how a category is defined, add new categories, or correct misclassifications.
PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. has partial amenityamenityA point of interest referenced by category ('gas station', 'pharmacy', 'ATM') rather than by name. Resolved by mapping the query onto a category taxonomy. support. PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. indexes 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. amenities as part of its 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 exposes a /v1/search endpoint with a categories parameterparameterA 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. that maps to 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 (e.g., categories=food filters to amenityamenityA point of interest referenced by category ('gas station', 'pharmacy', 'ATM') rather than by name. Resolved by mapping the query onto a category taxonomy.=restaurant/cafe/fast_food). For queries without the explicit parameterparameterA 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., PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. tokenizes to [gas] [station] and searches 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. by text — this works when an 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. 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.'s name or category text matches, but misses when the user's term differs from 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.'s taxonomy. The category endpoint is the right idea but limited to a fixed set of mappings that doesn't cover regional variantsregional variantA local term for an amenity or brand differing from the global name — 'servo' for a gas station in Australia, 'bodega' for a corner store in NYC. or slang.
What Mailwoman does today
Category queries like gas station are now detected and answerable, via the poiQueryKind flag — default-ON since 2026-07-20. 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) matches the phrase against the @mailwoman/poi-taxonomy lexicon, splits off any location constraint (near Springfield, IL), and runs the anchor 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..
Resolution needs a poi.db — a sealed 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, confidence ≥ 0.85) covering the US, Canada, Mexico, and France. mailwoman poi "gas station near Springfield, IL" --db poi.db returns distance-ranked results; the same lookup is available to agents as the mailwoman_poi_search MCP tool. Categories with no permissive source — fire hydrants, post boxes, and the like — abstain with requires_build_local_layer rather than misfire; see the series index for why that split exists.
Proximity-search products are still out of scope. The CLI and MCP tool answer "nearest X" with distance and coordinates; open-now filtering, routing, and review scores aren't built. See the series index for the current stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. across all 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. categories, and try it against a live amenityamenityA point of interest referenced by category ('gas station', 'pharmacy', 'ATM') rather than by name. Resolved by mapping the query onto a category taxonomy. query.
See also
- Franchise and brand queries — the named-chain version of amenityamenityA point of interest referenced by category ('gas station', 'pharmacy', 'ATM') rather than by name. Resolved by mapping the query onto a category taxonomy. queries
- Regional variant queries — when the same amenityamenityA point of interest referenced by category ('gas station', 'pharmacy', 'ATM') rather than by name. Resolved by mapping the query onto a category taxonomy. has different names
- Exotic POI overview — the series index