Creating a Choropleth Map with Folium

Oct 13, 2025 by wbrum.org 103 views

Introduction

Creating interactive and informative maps is a crucial aspect of data visualization, especially when dealing with geospatial data. Folium, a Python library built on top of Leaflet.js, provides an easy-to-use interface for creating web maps. However, when working with Folium choropleth maps, users often encounter errors related to the key_on parameter. In this article, we will discuss the common issue of ValueError: key_on 'FIPS' not found and provide a step-by-step guide to resolve it.

Understanding the Error

The ValueError: key_on 'FIPS' not found error occurs when Folium is unable to find the 'FIPS' column in the GeoDataFrame (GDF) used to create the choropleth map. This error is typically encountered when working with shapefiles from the Census Bureau, which often contain FIPS codes as a unique identifier for each geographic entity.

Prerequisites

Before we dive into the solution, ensure that you have the following libraries installed:

Folium
Geopandas
Pandas
Matplotlib (optional)

You can install these libraries using pip:

pip install folium geopandas pandas matplotlib

Loading and Cleaning Data

To create a choropleth map, you need two DataFrames (DFs): one for the shapefile and another for the data you want to visualize. In this example, we will use a shapefile from the Census Bureau and religion data from the US Religion Census.

import geopandas as gpd
import pandas as pd
shapefile = gpd.read_file('path/to/shapefile.shp')
religion_data = pd.read_csv('path/to/religion_data.csv')

Creating a Choropleth Map

To create a choropleth map, you need to merge the shapefile and the data DataFrame based on a common column. In this case, we will use the 'FIPS' column as the common identifier.

# Merge shapefile and data DataFrame
merged_gdf = gpd.GeoDataFrame(
    geometry=shapefile.geometry,
    data=religion_data,
    crs=shapefile.crs
)

Resolving the Error

Now, let's resolve the ValueError: key_on 'FIPS' not found error. The issue arises when Folium is unable to find the 'FIPS' column in the merged GeoDataFrame. To resolve this, you need to ensure that the 'FIPS' column exists in the merged GDF.

# Check if 'FIPS' column exists in merged GDF
if 'FIPS' in merged_gdf.columns:
    print("FIPS column found in merged GDF")
else:
    print("FIPS column not found in merged GDF")

If the 'FIPS' column is not found, you need to merge the shapefile and the data DataFrame again, this time using the correct common column.

# Merge shapefile and data DataFrame using correct common column
merged_gdf = gpd.GeoDataFrame(
    geometry=shapefile.geometry,
    data=religion_data,
    crs=shapefile.crs
)

Creating a Choropleth Map with Folium

Now that we have resolved the error, let's create a choropleth map using Folium.

import folium
m = folium.Map(location=[40, -100], zoom_start=4)
folium.Choropleth(
geo_data=merged_gdf,
data=merged_gdf,
columns=['FIPS', 'religion'],
key_on='feature.properties.FIPS',
fill_color='YlGnBu',
fill_opacity=0.7,
line_opacity=0.2
).add_to(m)
m.save('choropleth_map.html')

Conclusion

In this article, we discussed the common issue of ValueError: key_on 'FIPS' not found when creating a Folium choropleth map. We provided a step-by-step guide to resolve the error by ensuring that the 'FIPS' column exists in the merged GeoDataFrame. By following these steps, you can create interactive and informative choropleth maps using Folium.

Additional Resources

Folium documentation: https://python-visualization.github.io/folium/
Geopandas documentation: https://geopandas.org/
Pandas documentation: https://pandas.pydata.org/

Example Use Cases

Creating a choropleth map of US states based on population density
Visualizing crime rates in a city using a choropleth map
Creating a map of global temperature anomalies using a choropleth map

Q: What is the `ValueError: key_on` 'FIPS' `not found` error in Folium?

A: The ValueError: key_on 'FIPS' not found error occurs when Folium is unable to find the 'FIPS' column in the GeoDataFrame (GDF) used to create the choropleth map. This error is typically encountered when working with shapefiles from the Census Bureau, which often contain FIPS codes as a unique identifier for each geographic entity.

Q: Why do I get the `ValueError: key_on` 'FIPS' `not found` error when creating a choropleth map?

A: You get the ValueError: key_on 'FIPS' not found error when creating a choropleth map because Folium is unable to find the 'FIPS' column in the merged GeoDataFrame. This can happen if the 'FIPS' column is missing or if the shapefile and data DataFrame are not merged correctly.

Q: How do I resolve the `ValueError: key_on` 'FIPS' `not found` error?

A: To resolve the ValueError: key_on 'FIPS' not found error, you need to ensure that the 'FIPS' column exists in the merged GeoDataFrame. You can do this by checking if the 'FIPS' column exists in the merged GDF using the following code:

if 'FIPS' in merged_gdf.columns:
    print("FIPS column found in merged GDF")
else:
    print("FIPS column not found in merged GDF")

If the 'FIPS' column is not found, you need to merge the shapefile and the data DataFrame again, this time using the correct common column.

Q: What is the difference between `key_on` and `columns` in Folium's `Choropleth` function?

A: The key_on and columns parameters in Folium's Choropleth function are used to specify the column that contains the unique identifiers for each geographic entity. The key_on parameter is used to specify the column that contains the unique identifiers, while the columns parameter is used to specify the two columns that contain the data to be visualized.

Q: How do I create a choropleth map with multiple columns of data?

A: To create a choropleth map with multiple columns of data, you need to specify the columns parameter in Folium's Choropleth function. The columns parameter should be a list of two columns that contain the data to be visualized.

folium.Choropleth(
    geo_data=merged_gdf,
    data=merged_gdf,
    columns=['FIPS', 'column1', 'column2'],
    key_on='feature.properties.FIPS',
    fill_color='YlGnBu',
    fill_opacity=0.7,
    line_opacity=0.2
).add_to(m)

Q: How do I customize the appearance of my choropleth map?

A: You can customize the appearance of your choropleth map by using various options available in Folium's Choropleth function. Some of the options include:

fill_color: specifies the color scheme to use for the choropleth map
fill_opacity: specifies the opacity of the fill color
line_opacity: specifies the opacity of the border color
legend_name: specifies the name of the legend

folium.Choropleth(
    geo_data=merged_gdf,
    data=merged_gdf,
    columns=['FIPS', 'column1', 'column2'],
    key_on='feature.properties.FIPS',
    fill_color='YlGnBu',
    fill_opacity=0.7,
    line_opacity=0.2,
    legend_name='Column 1'
).add_to(m)

Q: How do I save my choropleth map as an HTML file?

A: You can save your choropleth map as an HTML file using the save method in Folium.

m.save('choropleth_map.html')

This will save the choropleth map as an HTML file named choropleth_map.html in the current working directory.