diff --git a/docs-mintlify/docs/explore-analyze/charts/chart-types/map.mdx b/docs-mintlify/docs/explore-analyze/charts/chart-types/map.mdx
index df9754e14fb7e..165ce16af1217 100644
--- a/docs-mintlify/docs/explore-analyze/charts/chart-types/map.mdx
+++ b/docs-mintlify/docs/explore-analyze/charts/chart-types/map.mdx
@@ -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.
 
@@ -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: