Folium Interactive Maps — Core Concepts

Folium is a Python wrapper around Leaflet.js, the most widely used open-source JavaScript mapping library. It lets you create interactive web maps entirely from Python, generating self-contained HTML files that work in any browser.

Creating a basic map

import folium

m = folium.Map(location=[40.7128, -74.0060], zoom_start=12)
m.save("nyc.html")

This creates an interactive map centered on New York City at zoom level 12. The result is a standalone HTML file with all JavaScript and CSS embedded.

Adding markers

folium.Marker(
    location=[40.7484, -73.9857],
    popup="Empire State Building",
    tooltip="Click for details",
    icon=folium.Icon(color="red", icon="building", prefix="fa"),
).add_to(m)

Markers support custom icons via Font Awesome (prefix="fa") or Bootstrap Glyphicons. The popup appears on click; the tooltip appears on hover.

Circle markers for data points

When you have hundreds of points, standard pin markers clutter the map. Circle markers are lighter:

folium.CircleMarker(
    location=[40.7580, -73.9855],
    radius=8,
    color="blue",
    fill=True,
    fill_opacity=0.6,
    popup="Times Square",
).add_to(m)

Choropleth maps

Choropleths color regions (countries, states, zip codes) based on data values — perfect for visualizing statistics like population density or election results.

import pandas as pd

df = pd.read_csv("state_unemployment.csv")

folium.Choropleth(
    geo_data="us_states.json",
    data=df,
    columns=["State", "Unemployment"],
    key_on="feature.properties.name",
    fill_color="YlOrRd",
    fill_opacity=0.7,
    legend_name="Unemployment Rate (%)",
).add_to(m)

The geo_data is a GeoJSON file defining region boundaries. key_on links the GeoJSON features to your DataFrame.

Tile layers

The default map uses OpenStreetMap tiles. Folium supports many alternatives:

folium.TileLayer("CartoDB positron").add_to(m)   # minimal, great for data viz
folium.TileLayer("CartoDB dark_matter").add_to(m) # dark theme
folium.TileLayer("Stamen Terrain").add_to(m)      # terrain with hillshading

Add folium.LayerControl().add_to(m) to let users switch between tile layers interactively.

GeoJSON overlays

Load any GeoJSON file to display custom shapes — delivery zones, park boundaries, transit routes:

folium.GeoJson(
    "bike_lanes.geojson",
    style_function=lambda feature: {
        "color": "green",
        "weight": 3,
        "opacity": 0.8,
    },
).add_to(m)

Marker clusters

When showing thousands of points (store locations, sensor readings), individual markers become unusable. MarkerCluster groups nearby markers and shows a count:

from folium.plugins import MarkerCluster

cluster = MarkerCluster().add_to(m)
for _, row in df.iterrows():
    folium.Marker([row.lat, row.lng], popup=row.name).add_to(cluster)

Heatmaps

Visualize density without individual markers:

from folium.plugins import HeatMap

heat_data = df[["lat", "lng", "intensity"]].values.tolist()
HeatMap(heat_data, radius=15, blur=10).add_to(m)

Common misconception

People often think Folium maps require a server. They do not — the output is a static HTML file. You can email it, host it on GitHub Pages, or embed it in a Jupyter notebook. The interactivity comes from JavaScript running in the viewer’s browser, not from a backend.

Integration with Jupyter

In Jupyter notebooks, displaying a map is as simple as putting m as the last line of a cell. Folium renders it inline as an interactive iframe. This makes it excellent for exploratory data analysis.

The one thing to remember: Folium bridges Python data analysis and interactive web maps — you work in Python, your audience gets a zoomable, clickable map in their browser.