Introduction
Maps are powerful for dashboards, delivery tracking, and location-based apps. Folium wraps Leaflet.js for Python, and streamlit-folium renders it in Streamlit. This post builds interactive maps with markers, heatmaps, and GeoJSON.
Setup
pip install streamlit folium streamlit-folium
Step 1: Basic map
import streamlit as st
import folium
from streamlit_folium import st_folium
st.title("🗺️ Map")
m = folium.Map(location=[20.5937, 78.9629], zoom_start=5) # India center
st_folium(m, width=700, height=500)
st_folium returns click events (lat/lng of clicks) — useful for interactive maps.
Step 2: Markers
m = folium.Map(location=[20.5937, 78.9629], zoom_start=5)
# Single marker
folium.Marker(
location=[19.0760, 72.8777],
popup="Mumbai",
tooltip="Click for info",
icon=folium.Icon(color="red", icon="info-sign"),
).add_to(m)
# Circle marker
folium.CircleMarker(
location=[28.6139, 77.2090],
radius=10,
color="blue",
fill=True,
popup="Delhi",
).add_to(m)
st_folium(m, width=700, height=500)
Step 3: Marker clusters
from folium.plugins import MarkerCluster
m = folium.Map(location=[20.5937, 78.9629], zoom_start=5)
cluster = MarkerCluster().add_to(m)
cities = [
("Mumbai", 19.0760, 72.8777),
("Delhi", 28.6139, 77.2090),
("Bangalore", 12.9716, 77.5946),
("Chennai", 13.0827, 80.2707),
("Kolkata", 22.5726, 88.3639),
]
for name, lat, lng in cities:
folium.Marker(location=[lat, lng], popup=name).add_to(cluster)
st_folium(m, width=700, height=500)
Clusters group nearby markers — essential for 100+ points.
Step 4: Heatmap
from folium.plugins import HeatMap
import numpy as np
m = folium.Map(location=[20.5937, 78.9629], zoom_start=5)
# Generate random points (lat, lng, weight)
data = [[np.random.uniform(8, 35), np.random.uniform(68, 97), np.random.random()] for _ in range(500)]
HeatMap(data, radius=15, blur=10).add_to(m)
st_folium(m, width=700, height=500)
Heatmaps show density — great for crime maps, sales density, delivery hotspots.
Step 5: Choropleth (colored regions)
import pandas as pd
# GeoJSON for Indian states
geojson_url = "https://raw.githubusercontent.com/geohacker/india/master/state/india_telengana.geojson"
data = pd.DataFrame({
"state": ["Maharashtra", "Delhi", "Karnataka", "Tamil Nadu", "West Bengal"],
"value": [100, 80, 60, 50, 40],
})
m = folium.Map(location=[20.5937, 78.9629], zoom_start=5)
folium.Choropleth(
geo_data=geojson_url,
name="choropleth",
data=data,
columns=["state", "value"],
key_on="feature.properties.NAME_1",
fill_color="YlOrRd",
fill_opacity=0.7,
line_opacity=0.2,
legend_name="Value",
).add_to(m)
st_folium(m, width=700, height=500)
Step 6: GeoJSON layers
import json
geojson = {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {"type": "Point", "coordinates": [72.8777, 19.0760]},
"properties": {"name": "Mumbai", "popup": "Financial capital"},
},
],
}
m = folium.Map(location=[20.5937, 78.9629], zoom_start=5)
folium.GeoJson(geojson, tooltip=folium.GeoJsonTooltip(fields=["name"])).add_to(m)
st_folium(m, width=700, height=500)
Step 7: Click events (interactive)
m = folium.Map(location=[20.5937, 78.9629], zoom_start=5)
output = st_folium(m, width=700, height=500)
if output["last_clicked"]:
lat = output["last_clicked"]["lat"]
lng = output["last_clicked"]["lng"]
st.write(f"Clicked: {lat:.4f}, {lng:.4f}")
st_folium returns click coordinates — use them to add markers, query a DB, etc.
Step 8: Real-time updates
@st.fragment(run_every=5)
def live_map():
m = folium.Map(location=[20.5937, 78.9629], zoom_start=5)
# Fetch latest positions from DB/API
positions = get_latest_positions()
for p in positions:
folium.Marker(location=[p["lat"], p["lng"]], popup=p["name"]).add_to(m)
st_folium(m, width=700, height=500, key="live_map")
live_map()
Auto-refresh map with live data. Great for delivery tracking, fleet management.
Common mistakes
- Not using
st_folium—folium.Mapalone doesn’t render in Streamlit. Always usest_folium. - Missing
width/height— default is small. Set explicitly. - Too many markers — 1000+ markers lag. Use
MarkerCluster. - Not handling click events —
st_foliumreturns them; use them for interactivity. - Large GeoJSON — simplifies or use
folium.GeoJsonwithsmooth_factor.
Key Concepts
- Folium = Python wrapper for Leaflet.js maps
st_folium= render Folium map in Streamlit- Marker = point on the map
- MarkerCluster = group nearby markers
- HeatMap = density visualization
- Choropleth = colored regions by value
- GeoJSON = geographic data format
What to Try Next
- Build a delivery tracking dashboard with live maps.
- Combine with Supabase for persistent location data.
- Add auth for per-user maps.
- Use with caching for large GeoJSON files.
FAQ
Folium vs Plotly maps vs PyDeck?
Folium = Leaflet.js, great for markers/heatmaps/choropleths, static-ish. Plotly = interactive scatter maps, good for data exploration. PyDeck = deck.gl, 3D, high-performance for millions of points. Pick Folium for simplicity, PyDeck for scale.
Can Folium handle 10k+ markers?
Not smoothly — rendering 10k DOM markers is slow. Use MarkerCluster (groups them) or switch to PyDeck/Plotly for large datasets. For 100k+ points, use a heatmap or hexbin.
Does Folium work offline?
The map tiles (OpenStreetMap) require internet. For offline, use local tile servers or folium.TileLayer with a local MBTiles file. Most apps need internet for tiles.