Geo Visualizer
Create interactive HTML maps from geographic data using Folium.
Features
- Markers: Plot points with custom icons, popups, and tooltips
- Heatmaps: Visualize density/intensity data
- Choropleth: Color regions by data values
- Routes/Lines: Draw paths between points
- Circles/Areas: Show radius-based coverage
- Layer Control: Toggle multiple layers
- Clustering: Auto-cluster dense markers
Quick Start
from geo_visualizer import GeoVisualizer
# Simple marker map
viz = GeoVisualizer()
viz.add_markers([
{"lat": 40.7128, "lon": -74.0060, "name": "New York"},
{"lat": 34.0522, "lon": -118.2437, "name": "Los Angeles"}
])
viz.save("cities.html")
# From CSV
viz = GeoVisualizer()
viz.from_csv("locations.csv", lat_col="latitude", lon_col="longitude")
viz.save("map.html")CLI Usage
# Plot markers from CSV
python geo_visualizer.py --input locations.csv --lat latitude --lon longitude --output map.html
# Add heatmap
python geo_visualizer.py --input data.csv --lat lat --lon lng --heatmap --output heat.html
# With clustering
python geo_visualizer.py --input stores.csv --lat lat --lon lon --cluster --output stores.html
# Choropleth map
python geo_visualizer.py --geojson states.geojson --data stats.csv --key state --value population --output choropleth.htmlAPI Reference
GeoVisualizer Class
class GeoVisualizer:
def __init__(self, center=None, zoom=10, tiles="OpenStreetMap")
# Data loading
def from_csv(self, filepath, lat_col, lon_col, **kwargs) -> 'GeoVisualizer'
def from_dataframe(self, df, lat_col, lon_col, **kwargs) -> 'GeoVisualizer'
def from_geojson(self, filepath) -> 'GeoVisualizer'
# Markers
def add_marker(self, lat, lon, popup=None, tooltip=None, icon=None, color="blue")
def add_markers(self, locations: list, name_col=None, popup_cols=None)
def cluster_markers(self, enabled=True) -> 'GeoVisualizer'
# Layers
def add_heatmap(self, points=None, weight_col=None, radius=15) -> 'GeoVisualizer'
def add_choropleth(self, geojson, data, key_on, value_col, **kwargs) -> 'GeoVisualizer'
def add_route(self, points, color="blue", weight=3) -> 'GeoVisualizer'
def add_circle(self, lat, lon, radius_m, color="blue", fill=True)
# Output
def save(self, filepath) -> str
def get_html(self) -> str
def fit_bounds(self) -> 'GeoVisualizer'Marker Options
# Custom icons
viz.add_marker(lat, lon, icon="fa-coffee", color="red")
# With popup content
viz.add_marker(lat, lon, popup="<b>Store #123</b><br>Open 9-5")
# From CSV with popup columns
viz.from_csv("stores.csv", lat_col="lat", lon_col="lon")
viz.add_markers(viz.data, popup_cols=["name", "address", "phone"])Heatmap Options
# Basic heatmap
viz.add_heatmap()
# Weighted heatmap (e.g., by sales volume)
viz.add_heatmap(weight_col="sales", radius=20, blur=15, max_zoom=12)Choropleth Maps
# Color regions by data
viz.add_choropleth(
geojson="us-states.geojson",
data=state_data,
key_on="feature.properties.name", # GeoJSON property
value_col="population",
fill_color="YlOrRd", # Color scale
legend_name="Population"
)Tile Layers
Available base maps:
OpenStreetMap(default)CartoDB positron(light, minimal)CartoDB dark_matter(dark theme)Stamen Terrain(terrain features)Stamen Toner(high contrast B&W)
viz = GeoVisualizer(tiles="CartoDB positron")Example Workflows
Store Locator Map
viz = GeoVisualizer()
viz.from_csv("stores.csv", lat_col="lat", lon_col="lon")
viz.add_markers(viz.data, popup_cols=["name", "address", "hours"])
viz.cluster_markers(True)
viz.fit_bounds()
viz.save("store_locator.html")Sales Heatmap
viz = GeoVisualizer(tiles="CartoDB dark_matter")
viz.from_csv("sales.csv", lat_col="lat", lon_col="lon")
viz.add_heatmap(weight_col="revenue", radius=25)
viz.save("sales_heat.html")Delivery Route
viz = GeoVisualizer()
stops = [(40.7, -74.0), (40.8, -73.9), (40.75, -73.95)]
viz.add_route(stops, color="blue", weight=4)
for i, (lat, lon) in enumerate(stops):
viz.add_marker(lat, lon, popup=f"Stop {i+1}")
viz.save("route.html")Output
- HTML: Interactive map viewable in any browser
- Auto-fit: Automatically zooms to show all data
- Responsive: Works on mobile devices
Dependencies
- folium>=0.14.0
- pandas>=2.0.0
- branca>=0.6.0