When to use a choropleth

A choropleth map colors geographic regions based on a value — the shape of the region is fixed (it’s a real border), and only the fill color changes to encode your metric:

• Covid cases by country
• Sales by state
• Population density

It’s the right chart whenever “where” is part of the story and the reader would recognize the region shapes (countries, states) — if the regions aren’t recognizable, a plain bar chart sorted by value usually communicates the ranking better.

Example dataset (country metrics)

import pandas as pd
 
df = pd.DataFrame({
    "country": ["India", "United States", "Brazil"],
    "iso_alpha": ["IND", "USA", "BRA"],
    "value": [120, 200, 150],
})
print(df)

import pandas as pd
 
df = pd.DataFrame({
    "country": ["India", "United States", "Brazil"],
    "iso_alpha": ["IND", "USA", "BRA"],
    "value": [120, 200, 150],
})
print(df)

Plotly Express choropleth

Plotly works best with ISO-3 codes (iso_alphaiso_alpha) — a standard 3-letter country code (INDIND, USAUSA, BRABRA) that Plotly matches against its built-in map geometry, instead of trying to guess borders from a country name string.

import plotly.express as px
 
fig = px.choropleth(
    df,
    locations="iso_alpha",
    color="value",
    hover_name="country",
    color_continuous_scale="Viridis",
    title="Metric by country",
)
 
fig.show()

import plotly.express as px
 
fig = px.choropleth(
    df,
    locations="iso_alpha",
    color="value",
    hover_name="country",
    color_continuous_scale="Viridis",
    title="Metric by country",
)
 
fig.show()

color_continuous_scalecolor_continuous_scale picks the gradient used to map valuevalue to a color — Plotly interpolates between the scale’s colors for every value in between the min and max.

Tips

• Prefer ISO codes for reliable mapping — country/state names have spelling and alias mismatches (e.g. “USA” vs “United States”) that silently drop rows from the map.
• Consider log scale for heavy-tailed metrics — a few huge values otherwise wash out all the smaller ones into the same pale color.
• Always add a clear title and color legend so a reader can translate color back into a number.

  flowchart LR
  A["DataFrame:
region id + value"] --> B["locations= column
(e.g. iso_alpha)"]
  B --> C["Plotly matches id
to built-in map geometry"]
  C --> D["color=value
mapped through color_continuous_scale"]
  D --> E["Shaded map,
hover shows exact value"]

Next

Continue to: Interactive Histograms and Distributions for exploring how values are spread out.

🧪 Try It Yourself

Exercise 1 – Match Regions with locations

Exercise 2 – Pick a Color Scale

Exercise 3 – Show Full Country Names on Hover