Regional name resolution architecture

Every co-location cluster is labelled with a human-readable regional name — a North American metropolitan area, a European NUTS-3 region, a Mexican municipio, a Canadian census subdivision. That name is not a field on the source data. It is the output of a layered offline reverse-geocoding engine.

Why it matters: the whole resolution runs from local boundary files with no external geocoding API in the loop, so the substrate keeps its offline-capable, no-per-request-cost posture even for the one step that most obviously invites a hosted service.

The boundary layers

Each cluster anchor's coordinates are tested against a layered set of boundary datasets in a country-specific order. The core routing layers:

Beyond this core set, the engine loads a further layer of settlement-level boundary files — finer-grained city, town, and municipality boundaries for the United States, the European Union, and Canada — which resolve a more specific place name where that data exists. All files load once at engine initialisation, and spatial indexes bring point-in-polygon lookups to logarithmic cost per query.

Why it matters: loading everything once at startup is what makes per-cluster resolution cheap enough to run across the whole manifold on every rebuild.

Country-specific routing

The engine routes each cluster's anchor coordinates by ISO country code:

• United States — CBSA lookup. On a match, the name is formatted: state suffix stripped, "Metro Area" appended if absent.
• Canada — census subdivision first (admin-3). Where both a subdivision and the surrounding census metropolitan area match and differ, the result is composed: "Strathcona County, Edmonton". Where only one matches, that name is returned alone.
• Mexico — municipio lookup (admin-2), with Spanish-text post-processing on a match. On a miss, the engine falls through to the metropolitan-zone layer, and if that also misses, to the Natural Earth state-level fallback.
• European Union, United Kingdom, EFTA, Western Balkans — NUTS-3 lookup.
• Fallback — Natural Earth admin-1 for any country not covered by the layered files, returning state or province names.

Each layer carries a tolerance in its spatial query: when a point falls just outside every polygon — a coastal store on a fjord edge, for instance — the engine accepts the nearest polygon within roughly 15 km.

Why it matters: without the tolerance, legitimate coastal and island stores fall through every specific layer to a state-level fallback, and the map labels a Norwegian town with the name of its county.

Post-processing the raw names

Boundary files carry source-language names with concatenated affixes that are not human-readable. Three transformations clean them.

CamelCase splitter. GADM admin-2 and admin-3 names are stored without word separators: "StrathconaCounty" becomes "Strathcona County".

Spanish preposition splitter. Mexican municipio names occasionally carry preposition concatenation — "Bocadel Río", "Apetatitlánde Antonio Carvajal". A regular expression detects the prepositions de, del, la, las, el, and los glued to a preceding lowercase character and inserts a space before them.

Period normaliser. "Gustavo A.Madero" is normalised to "Gustavo A. Madero".

A separate explicit-override dictionary handles cases outside the regular-expression scope: Greek names transliterated to English, Finnish suffix simplifications, Polish prefix stripping, Belgian bilingual name normalisation. That dictionary held roughly 200 entries as of mid-2026.

Why it matters: the name is the only part of this pipeline a human reads directly, so a mechanical artefact in it undermines confidence in every number shown beside it.

Display overrides

Some municipio names are technically correct but not the form a Spanish-speaking reader expects on a map. A small display-override dictionary maps INEGI metropolitan-zone names to their common short forms — "Zona Metropolitana del Valle de México" becomes "Ciudad de México"; "Zona Metropolitana de Guadalajara" becomes "Guadalajara".

Scale

After layered routing and post-processing, the engine produces roughly 1,200 unique region names across the operational footprint as of May 2026: 671 distinct US metropolitan areas, 245 Canadian regions (census subdivisions and metropolitan areas combined), 104 Mexican municipios, and several hundred European NUTS-3 regions. Each appears in cluster pop-ups and the inspector panel.

See also

• Location intelligence substrate — the flat-file GIS architecture this engine runs inside
• POI data schema — the record structures whose coordinates feed the engine
• Business clustering — the clustering service that consumes the resolved names
• GIS as a BIM substrate — how a resolved region name is used downstream by a BIM pipeline