Building Interactive Choropleth Maps in Folium

What Is an Interactive Choropleth Map?

An interactive choropleth map shades geographic areas—states, counties, countries—based on the magnitude of a numerical variable, and lets viewers pan, zoom, and reveal contextual tooltips. In Python, the folium library makes building such maps straightforward by combining Leaflet.js capabilities with a pure-Python API.

Why You Should Care

Spatial data is everywhere: public health statistics by county, sales by region, election results by district. A static chart forces readers to parse hundreds of data points at once, while an interactive choropleth lets them explore details on demand. Folium removes the front-end friction—you write Python, and Folium emits interactive, browser-ready HTML.

Key Concepts and Terminology

GeoJSON

A JSON format for encoding geographic features and their properties. Folium expects your region boundaries in GeoJSON or TopoJSON.

Color scale

A gradient that maps your numerical variable onto colors (e.g., light ⇢ dark). Folium integrates with branca.colormap for custom scales.

Tooltip / Popup

UI elements that appear when the user hovers or clicks a region, typically showing the region’s name and metric value.

Layer Control

Allows toggling multiple data layers on/off. Handy for side-by-side comparisons (e.g., population vs. income).

Step-by-Step Guide

1. Install Dependencies

pip install folium geopandas branca

2. Acquire Boundaries (GeoJSON)

You can download ready-made GeoJSON files from sources like GADM or eric.clst.org. Alternatively, convert a shapefile with geopandas:

import geopandas as gpd
shp = gpd.read_file("cb_2023_us_state_5m.shp")
shp.to_file("us_states.geojson", driver="GeoJSON")

3. Prepare a DataFrame

Your DataFrame must contain a key that matches a property in the GeoJSON. Example:

import pandas as pd
state_data = pd.read_csv("state_unemployment.csv") # columns: state, rate

4. Create the Base Map

import folium
m = folium.Map(
location=[38.5, -96],
zoom_start=4,
tiles="cartodbpositron" # light background for better contrast
)

5. Add the Choropleth Layer

folium.Choropleth(
geo_data="us_states.geojson",
data=state_data,
columns=["state", "rate"],
key_on="feature.properties.NAME", # property in GeoJSON
fill_color="YlGnBu",
fill_opacity=0.8,
line_opacity=0.2,
legend_name="Unemployment Rate (%)",
nan_fill_color="white",
).add_to(m)

6. Enhance with Tooltips

folium.GeoJson(
"us_states.geojson",
style_function=lambda x: {"fillOpacity": 0}, # keep style from Choropleth
tooltip=folium.features.GeoJsonTooltip(
fields=["NAME"],
aliases=["State:"],
localize=True,
sticky=False,
labels=True,
toLocaleString=True,
),
).add_to(m)

7. Save or Display

m.save("unemployment_map.html") # or display in Jupyter by just `m`

Best Practices

• Match keys exactly: Ensure the join field in your DataFrame matches the GeoJSON property with identical spelling and case.
• Normalize values when necessary: Use rates or percentages, not raw counts, to avoid misleading area-based maps.
• Add a legend and attribution: Folium’s legend_name parameter and folium.map.CustomPane can host credits.
• Keep colorblind users in mind: Choose perceptually uniform palettes (e.g., Viridis or Cividis).
• Limit the number of layers: Too many overlays can slow the browser and overwhelm the viewer.

How Galaxy Fits In

If your data lives in a SQL warehouse (Snowflake, Redshift, BigQuery), Galaxy’s modern SQL editor can generate the aggregated table that feeds your Folium map. Write, test, and share the query in Galaxy, then export the results to a CSV or directly fetch them via a DB-API client in Python for visualization.

Common Pitfalls and How to Fix Them

GeoJSON Key Mismatch

Your choropleth renders blank because key_on doesn’t match any GeoJSON properties. Inspect a sample feature (print(json.dumps(geojson['features'][0], indent=2))) to confirm the property path.

Missing CRS Transform

Shapefile in EPSG:3857 but map expects EPSG:4326 (WGS84). Reproject with shp.to_crs(4326) before export.

Using Raw Counts

Mapping raw population skews perception by area size. Compute per-capita metrics in SQL or Pandas before mapping.

Going Deeper

For multi-temporal data, you can animate choropleths using the TimeSliderChoropleth plugin. For very large GeoJSONs (>5 MB), consider simplifying geometry with shp.simplify(0.01) or using vector tiles.

Conclusion

Folium empowers Python users to build publication-quality, interactive choropleth maps with only a few dozen lines of code. Clean data joins, thoughtful color scales, and performance-minded geometry choices separate a good map from a great one.