How to Make a Choropleth Map in Python (Without the Name-Matching Headaches)

What a choropleth map actually is (and when to use one)

A choropleth map shades predefined areas — countries, states, districts — by a value, using color intensity to encode that value. It answers questions like “which districts have the highest literacy rate?” or “how does median income vary across US states?”

Use a choropleth when your data is tied to administrative units and expressed as a rate or normalized quantity (per-capita income, percent unemployed, density). Do not map raw counts on a choropleth: big areas look important just because they are big. For raw event locations, reach for a hexbin spatial analysis map or a dot-density map instead. The choropleth's whole job is to compare like-for-like areas, so the value must already be comparable across them.

The two ingredients: boundaries + a value table

Every choropleth map in Python needs exactly two inputs: (1) polygon geometry for your areas, and (2) a table of values keyed by area name. The classic geopandas stack gets the geometry from a shapefile or GeoJSON — GADM (via the pygadm package) for national and sub-national units, Natural Earth for world and coarse admin-1 layers, or OpenStreetMap for fine detail. Your value table is usually a CSV you already have.

In plain geopandas you would gpd.read_file() the boundaries, pd.read_csv() the data, and merge() them. AcadGIS collapses the boundary step to one call and ships Bangladesh, Iraq, India and the USA offline:

import acadgis as agis

# admin-1 (states/divisions) or admin-2 (districts)
gdf = agis.load_boundaries("USA", level="state")
data = agis.pd.read_csv("income_by_state.csv")  # columns: state, income
print(gdf.head(), data.head())

The part every tutorial skips: name matching

Here is where a python choropleth from csv falls apart. Your CSV and your boundaries were made by different people, so the join keys disagree. A plain merge() on the name column drops every row that doesn't match exactly, and those areas render as blank holes in your map. Common failure cases:

• Spelling / romanization: Comilla vs Cumilla, Jessore vs Jashore, Kolkata vs Calcutta.
• Spacing / punctuation: “West Bengal” vs GADM's “WestBengal”; “St. Louis” vs “Saint Louis”.
• Case and trailing whitespace that you can't see but == can.

The honest fix in raw geopandas is to normalize both sides (lowercase, strip, deburr) and hand-build a crosswalk for the stragglers — tedious but doable. AcadGIS bakes fuzzy matching into choropleth() and warns you about any names it still couldn't place instead of silently dropping them, so you get a list of fixes rather than a mysteriously patchy map:

import acadgis as agis

gdf = agis.load_boundaries("Bangladesh", level="district")
data = agis.pd.read_csv("literacy.csv")   # "Comilla" -> matches "Cumilla"

# fuzzy join by name; unmatched names raise a warning, not a silent blank
agis.choropleth(gdf, data, value="literacy", scheme="quantiles",
                title="District literacy rate")
agis.show()

Choosing a classification scheme (with a cheat-sheet)

Once the join works, the single most consequential decision is how you bin values into color classes. The same data can look alarming or unremarkable depending on the scheme. Under the hood this is the mapclassify library, which geopandas and AcadGIS both use; the difference is only how you invoke it. Pass the name you want to choropleth(..., scheme=...). Here is when to reach for each:

Putting it together: CSV to publication-ready map

This is the full geopandas choropleth workflow, condensed. Because choropleth() defaults to the academic theme, you get a north arrow, scale bar, graticule and a classed legend without extra code — the things you'd otherwise wire up by hand with matplotlib. Point key at your CSV's join column, then swap palette and scheme to retell the story:

import acadgis as agis

gdf = agis.load_boundaries("USA", level="state")
data = agis.pd.read_csv("income_by_state.csv")

agis.choropleth(gdf, data, value="income", key="state",
                scheme="natural_breaks", palette="viridis",
                title="Median household income by state")
agis.save("income_choropleth.png", dpi=300)

When to script it and when not to

Reproducible, versioned, part of a paper's figure pipeline? Script it in Python — the choropleth() call above is deterministic and diff-able. Need a world map with labels, or a national/district base you don't want to hunt down? AcadGIS's administrative boundary map generator covers the geometry side, and load_boundaries() downloads any country by name.

If you're not a coder, or you just want to drag in a spreadsheet and get a shaded map back, the point-and-click choropleth map generator runs the same fuzzy join and classification in the browser. Same result, no environment to set up. For honest comparison: QGIS and folium can both make choropleths too — QGIS is superb for interactive exploration and folium for web maps — but neither solves the name-matching problem for you, and that is usually where the hour actually goes.

Frequently asked questions