Skip to content

docs: document country name matching in region maps #11421

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
igorlukanin wants to merge 2 commits into
base: master
Choose a base branch
from
+9 −1
Open

docs: document country name matching in region maps #11421

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5d7004f
docs: document country name matching in region maps
igorlukanin Jul 29, 2026
c16cc12
docs: fix Region map section placement, US-code wording and spelling
igorlukanin Jul 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion docs-mintlify/docs/explore-analyze/charts/chart-types/map.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ Clustering groups nearby points into a single circle that expands on zoom. It is
A region map requires:

- **Source** — the GeoJSON to render: `World countries`, `US states`, or `Custom`.
- **Property** — which property in each GeoJSON feature acts as the join key (e.g. `name`, `ISO3166-1-Alpha-2`, `state_code`).
- **Property** — which property in each GeoJSON feature acts as the join key (e.g. `name`, `ISO3166-1-Alpha-2`, `ISO3166-1-Alpha-3`, `state_code`).
- **Dimension** — which column from your query joins to **Property**.
- **Measure** — the numeric measure that drives the choropleth fill.

Expand All @@ -69,6 +69,14 @@ When the chart enters Region mode, the join dimension and measure are auto-picke

The choropleth gradient comes from the active palette — pick from the built-in palettes or supply a custom one, see [Color and stacking](/docs/explore-analyze/charts/configuration/color-and-stacking).

### Country name matching

With **World countries**, country names do not have to be spelled the way the boundary data spells them. Long forms, endonyms, and common abbreviations all resolve to the same country, so `United States`, `United States of America`, and `USA` are interchangeable, as are `Brasil` and `Brazil`, or `Deutschland` and `Germany`. The same applies to the 2- and 3-letter ISO code properties, and it works in either direction — a name in your data still matches when **Property** is set to a code.

Matching is exact, never approximate: `United States` resolves to the United States and never to `United States Minor Outlying Islands`. Bare 2-letter codes such as `US` are only treated as country codes when **Property** is set to one of the ISO code properties, so a column of US state codes joined against country names stays unmatched rather than coloring `DE` as Germany.

This applies to **World countries** only. With **US states** or **Custom**, values must match the chosen **Property** exactly (ignoring case and surrounding whitespace).

### Custom GeoJSON

When **Source** is set to **Custom**, paste a URL serving a GeoJSON `FeatureCollection`. Requirements:
Expand Down