Regional variant queries
A regional variantregional 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. is a local term for 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., brand, or category that differs from the global or standard name. "Servo" means gas station in Australia. "Bodega" means corner store in New York City. "マクド" (makudo) means McDonalds in the Kansai regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. of Japan. In their regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality., these are the standard — the everyday word millions of people use.
A geocoder that only recognizes the global standard name ("gas station," "convenience store," "McDonald's") is useless for users who search with 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.. The geocoder doesn't need to translate the variant — it needs to recognize it as equivalent to the standard category.
Variant taxonomy
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. fall into several categories:
Amenity variants
| Standard term | Regional variantregional 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. | RegionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. |
|---|---|---|
| gas station | servo | Australia |
| gas station | petrol station | UK, Ireland, Commonwealth |
| convenience store | bodega | NYC, parts of US Northeast |
| convenience store | corner shop | UK |
| convenience store | depanneur (dépanneur) | Quebec |
| convenience store | milk bar | Australia (declining) |
| liquor store | off-licence | UK, Ireland |
| liquor store | bottle shop | Australia |
| liquor store | package store | New England, US |
| pharmacy | chemist | UK, Australia |
| pharmacy | apothecary | Historical, some US regionsregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. |
| restaurant (delivery only) | takeaway | UK, Australia |
| restaurant (delivery only) | takeout | US, Canada |
| public restroom | loo | UK |
| public restroom | washroom | Canada |
| garbage can | rubbish bin | UK, Australia |
| garbage can | dustbin | UK (older) |
| residential building | flat | UK |
| residential building | apartment | US |
| elevator | lift | UK |
Brand variants
| Brand | Regional variantregional 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. | RegionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. |
|---|---|---|
| McDonald's | Macca's | Australia |
| McDonald's | マクド (makudo) | Kansai, Japan |
| McDonald's | マック (makku) | Kantō, Japan |
| McDonald's | McDo | France, Quebec |
| McDonald's | Mek | Germany, Austria |
| McDonald's | Mickey D's | US (slang) |
| KFC | PFK (Poulet Frit Kentucky) | Quebec (legal name) |
| Burger King | Hungry Jack's | Australia (trademark issue) |
| 7-Eleven | セブンイレブン (sebun irebun) | Japan |
| Starbucks | スタバ (sutaba) | Japan (slang) |
Japanese brand abbreviation patterns
Japanese brand name variants follow predictable patterns that a geocoder could learn:
- TruncationtruncationCutting an input down to the max sequence length (or an LLM response to its token limit), discarding everything past the cap. to 2 mora: マクドナルド → マクド (first 2 kanas of the loanword). スターバックス → スタバ. セブンイレブン → セブイレ or セブン. ファミリーマート → ファミマ.
- Regional variation: The same brand can have different abbreviations in different regionsregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality.. マクド (Kansai) vs マック (Kantō) for McDonalds. This is a known linguistic phenomenon — Kansai speakers prefer the first two mora of the first word, Kantō speakers prefer the full first word.
- Loanword adaptation: Brand names borrowed into Japanese are adapted to Japanese phonology. "McDonald's" → マクドナルド (makudonarudo). "Starbucks" → スターバックス (sutābakkusu). In Japanese, these are the name — the form on every storefront and menu.
Code-switching queries
Some queries mix languages: スタバ near Shibuya Station. The brand name is in Japanese slang. The location constraint is in English and Japanese. The geocoder must handle the code-switch — recognize スタバ as Starbucks, 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. Shibuya Station as a transit location, and compose the query.
How traditional geocoders handle regional variants
Google handles 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. through its search 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.', trained on global query logs. "Servo" returns gas stations in Australia because Google's Australian users search for "servo" and click on gas station results. The mapping is learned from user behavior, not hand-curated.
This is the right approach for a global-scale geocoder with query log data. It does not work for a geocoder without query logs — you cannot learn that "servo" means gas station if you've never seen an Australian user search for it.
Nominatim does not handle 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.. The search is 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, which use standard English categories. "Servo" returns nothing unless an Australian mapper added alt_name=servo to a gas station — which almost none have.
PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. has the same limitation. The search matches text 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. against name fields. 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. don't match unless they appear in the data.
What a variant-aware geocoder needs
-
An alias table. A mapping from regional terms to standard categories and brands. This is hand-curated data — about 200-500 entries for major global variants, maintained as a data file. It's the same kind of maintenance burden as a stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. abbreviation dictionary, just larger.
-
A localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. signal. The geocoder needs to know where the user is to disambiguate variants. "Chemist" means pharmacy in the UK and Australia but not in the US. The locale gatelocale gateStage 2 of the runtime pipeline: rule-based locale detection from the query shape's script and known-format signals. Returns a LocaleHint with the top candidate and alternatives, surfacing disagreement with an explicit --locale flag. (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) provides this signal for Mailwoman — it detects the script and format of the query, which is a proxy for the user's regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality..
-
Fuzzy matching. Some variants are informal and appear nowhere in formal databases. "Mickey D's" for McDonalds, regional colloquialisms for common amenities. Exact alias matching won't catch these. A fuzzy-matching 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. that handles common informal variants requires 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 — either query logs or hand-curated examples.
What Mailwoman does today
Mailwoman's locale gatelocale gateStage 2 of the runtime pipeline: rule-based locale detection from the query shape's script and known-format signals. Returns a LocaleHint with the top candidate and alternatives, surfacing disagreement with an explicit --locale flag. (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) can detect the query's language/script family, and the alias table half of this problem now has a real home: @mailwoman/variant-aliases is the curated localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.-slang table ("servo," "PFK," "Macca's"), and it finally has a consumer — it resolves each slang term to a @mailwoman/poi-taxonomy category id, so "servo" reaches the same gas_station category and the same poi.db lookup an English "gas station" query would. AmenityamenityA point of interest referenced by category ('gas station', 'pharmacy', 'ATM') rather than by name. Resolved by mapping the query onto a category taxonomy.-variant slang works today the way amenity queries do.
Brand-variant slang doesn't yet, for the same reason franchise queries don't: there's no brand table for "servo" to resolve into. "マクド" (makudo) is recognized as Japanese text by the locale gatelocale gateStage 2 of the runtime pipeline: rule-based locale detection from the query shape's script and known-format signals. Returns a LocaleHint with the top candidate and alternatives, surfacing disagreement with an explicit --locale flag., but nothing maps it to McDonald's until the brand lexicon exists. Fuzzy matching for informal variants that never made it into the curated table is also still unbuilt.
See also
- Amenity queries — the generic-category version of what variants refer to
- Franchise and brand queries — the brand-name version of what variants refer to
- Exotic POI overview — the series index