Choropleth Maps

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)

Example data

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_alpha) — a standard 3-letter country code (IND, USA, BRA) that Plotly matches against its built-in map geometry, instead of trying to guess borders from a country name string.

Choropleth map

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_scale picks the gradient used to map value to a color — Plotly interpolates between the scale’s colors for every value in between the min and max.

sketch Choropleth = shape stays fixed, only fill color changes p5.js Pause Restart

Each cell is a stand-in 'region'; darker amber means a higher value, mimicking a continuous color scale.

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.

Analyst’s tip

A continuous color scale is a weaker channel than position or length — most people can’t reliably tell whether one shade of a gradient is “20% more” than another. Choropleths are best for spotting broad patterns (“the north is darker than the south”), not for reading precise values off the color alone; lean on the hover tooltip for exact numbers.

diagram Choropleth data flow mermaid

  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"]

Your value column is matched to map geometry through a region identifier, then colored by a scale.

Next

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

🧪 Try It Yourself

Exercise 1 – Match Regions with locations

pch.exerciseTag pch.exerciseTitle

Exercise 2 – Pick a Color Scale

pch.exerciseTag pch.exerciseTitle

Exercise 3 – Show Full Country Names on Hover

pch.exerciseTag pch.exerciseTitle