Franchise and brand queries

A franchise queryfranchise queryA point-of-interest query naming a brand or chain ('nearest Starbucks') rather than a category or an address. names a specific chain or brand. The user doesn't want the nearest restaurant — they want the nearest McDonalds. The brand name is the query, and the geocoder's job is to resolve it to one or more specific locations.

What franchise queries look like

Query	Implicit meaning
Walmart	Nearest Walmart store
McDonalds	Nearest McDonalds restaurant
Hilton	Nearest Hilton hotel
Starbucks	Nearest Starbucks coffee shop
7-Eleven	Nearest 7-Eleven convenience store
Home Depot near Springfield, IL	Nearest Home Depot to a specific place
Walmart Supercenter vs Walmart Neighborhood Market	A specific sub-brandsub-brandA branded variant within a larger franchise — Walmart Supercenter vs Walmart Neighborhood Market vs Sam's Club, all under Walmart. of the franchise
McDonalds with PlayPlace	A franchise location with a specific amenityamenityA point of interest referenced by category ('gas station', 'pharmacy', 'ATM') rather than by name. Resolved by mapping the query onto a category taxonomy.

Franchise queries have three components: a brand name, an optional sub-brandsub-brandA branded variant within a larger franchise — Walmart Supercenter vs Walmart Neighborhood Market vs Sam's Club, all under Walmart. or 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. filter, and an optional location constraint. The brand name is the hard part — it may not match what the franchise calls itself, and it varies by regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality..

Brand-name problem

"McDonalds" is the official brand name. Users also search for:

• McDonalds (correct spelling)
• McDonald's (possessive, correct per corporate branding)
• Mcdonalds (incorrect but common)
• Mickey D's (slang, US)
• Macca's (slang, Australia)
• マクドナルド (makudonarudo, Japan — full name)
• マクド (makudo, Japan — abbreviated, Kansai regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality.)
• McDo (abbreviated, France/Quebec)
• Mek (abbreviated, German-speaking countries)

A geocoder that only matches "McDonald's" against an exact-string index will miss every slang and 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.. A geocoder that matches all variants requires an alias table mapping user-facing terms to brand identifiers.

The alias table isn't a translation dictionary — it maps every name people use for a chain onto one brand identifier, so "Macca's" in Australia, "Mickey D's" in the US, and "マクド" in Kansai all resolve to the same brand.

Sub-brand problem

Franchises have sub-brandssub-brandA branded variant within a larger franchise — Walmart Supercenter vs Walmart Neighborhood Market vs Sam's Club, all under Walmart. that differ in meaningful ways:

• Walmart has Walmart Supercenter (full grocery), Walmart Discount Store (general merchandise, no grocery), Walmart Neighborhood Market (grocery-only, smaller footprint), and Sam's Club (warehouse membership).
• Hilton has Hilton Hotels & Resorts (full-service), Hilton Garden Inn (mid-scale), Hampton by Hilton (budget), Homewood Suites (extended stay), and several others.
• Starbucks has company-operated stores, licensed stores (in airports, hotels, grocery stores), and Starbucks Reserve Roastery (premium, limited locations).

A query for Walmart could mean any of the sub-brandssub-brandA branded variant within a larger franchise — Walmart Supercenter vs Walmart Neighborhood Market vs Sam's Club, all under Walmart.. A query for Walmart Supercenter is specific. The geocoder should return the nearest Supercenter for the specific query and the nearest any-Walmart for the generic query. This requires 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. index to include sub-brandsub-brandA branded variant within a larger franchise — Walmart Supercenter vs Walmart Neighborhood Market vs Sam's Club, all under Walmart. classification.

Location-constraint problem

Walmart near Springfield, IL requires two operations:

1. Resolve the location constraint (Springfield, IL) to coordinates or an area.
2. Find the nearest Walmart to that location.

The location constraint is an address or place nametoponymA proper name for a geographic place. — the kind of query Mailwoman already handles. The franchise lookup is new. The composition of "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 location constraint, then query the franchise index near that location" is a two-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). resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. query: resolve the place, then find 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. near it.

This is the same pattern as "gas station near Springfield, IL" (amenityamenityA point of interest referenced by category ('gas station', 'pharmacy', 'ATM') rather than by name. Resolved by mapping the query onto a category taxonomy. + location constraint) but with a named brand instead of a generic category.

How traditional geocoders handle franchise queries

Google's Places API handles franchise queries through Google's place database. A search for "McDonalds" returns McDonalds locations ranked by proximity and prominence. Google's database includes franchise locations globally, with sub-brandsub-brandA branded variant within a larger franchise — Walmart Supercenter vs Walmart Neighborhood Market vs Sam's Club, all under Walmart. classification (Walmart Supercenter vs Walmart Neighborhood Market) and user-contributed attributes (PlayPlace, drive-through, 24-hour). Google handles spelling variants and some slang 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.'.

Nominatim handles franchise queries by matching the brand name 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.'s name and brand tags. 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. has good 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. of franchise locations in well-mapped areas. However, 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 brand tagging is inconsistent: some locations are tagged brand=McDonald's, others name=McDonald's, and the relationship between franchise brand and individual location name varies by mapper. Nominatim does not handle slang or 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. — Macca's returns nothing unless an Australian mapper tagged a location with alt_name=Macca's.

PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. indexes franchise locations as part of its 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. and 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. gazetteersgazetteerA 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 same 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. tagging inconsistency applies. PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor.'s search matches "McDonalds" against name and brand fields, and its 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. can filter by broad types (e.g., food), but it has no brand-alias resolution — slang and variants don't match unless the exact text appears in the data. Sub-brandsub-brandA branded variant within a larger franchise — Walmart Supercenter vs Walmart Neighborhood Market vs Sam's Club, all under Walmart. classification is not modeled.

What Mailwoman does today

The category infrastructure that 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 use — the poi_query kind, the anchor split, poi.db resolution — exists now, but brand matching isn't wired into it. Mailwoman's parser will still see Walmart and try to classify it as an address component: a lone brand name with no other 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. is a one-tokentokenOne 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. address, and the parser may read it as locality (there are towns named Walmart) or venue (the 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. classifier exists but is weak, see Landmark queries).

Franchise queries are still deferred. There's no brand lexicon yet — no table mapping "Walmart," "Macca's," or マクド to a chain identifier, and no join from Overture's brand.wikidata field to a name. The location-constraint half (near Springfield, IL) already works, through the same anchor-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. path 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 use; the brand-lookup half doesn't exist. See the series index for what's built and what isn't across the whole 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. arc.

See also

• Amenity queries — the generic-category version
• Regional variant queries — when the same brand has different local names
• Exotic POI overview — the series index