A FastAPI-based web server for interactive maps with real-time event handling. This server allows you to create map sessions, display interactive maps (Leaflet or deck.gl), and control map behavior through API endpoints.
- Create and manage map sessions
- Display interactive maps with two rendering options:
- Leaflet (traditional 2D maps)
- deck.gl (WebGL-powered 3D maps)
- Animated zoom transitions with smooth fly-to effects
- Real-time event handling through polling
- Zoom to coordinates, bounding boxes, or GeoJSON polygons
- Plot GeoJSON polygons on the map
- Python 3.8+
- Poetry (for dependency management)
- Clone the repository
- Install dependencies with Poetry:
cd map_server
poetry installcd map_server
poetry run uvicorn app.main:app --reloadThe server will be available at http://localhost:8000
POST /session- Create a new map sessionGET /session/{session_id}- Get session information
GET /map/{session_id}- Display an interactive map for the session
POST /zoom_to_coordinate- Zoom to a specific coordinatePOST /zoom_to_geojson- Zoom to fit a GeoJSON polygonPOST /zoom_to_bounding_box- Zoom to a specific bounding boxPOST /plot_polygon- Plot a GeoJSON polygon on the map
GET /events/{session_id}- Poll for new events in the session
A test script is included to demonstrate the functionality with both map types:
# Run with Leaflet (default)
cd map_server
poetry run python test_map_server.py
# Run with deck.gl
poetry run python test_map_server.py --map-type deckglThis will:
- Create a new map session with the specified map type
- Open the map in your default web browser
- Demonstrate various map operations:
- Zoom to San Francisco
- Zoom to California (bounding box)
- Zoom to New York (to demonstrate long-distance animation)
- Plot a triangle polygon in San Francisco
- Plot a GeoJSON feature for Los Angeles
- Traditional 2D map with tile layers
- Lightweight and fast
- Excellent compatibility across browsers
- Smooth animated transitions between locations
- WebGL-powered 3D visualization
- Enhanced polygon rendering with 3D effects
- Improved visual styling for GeoJSON features
- Advanced animation capabilities
- Better for data visualization use cases
curl -X POST http://localhost:8000/sessioncurl -X POST http://localhost:8000/zoom_to_coordinate \
-H "Content-Type: application/json" \
-d '{
"session_id": "your-session-id",
"coordinate": {
"lat": 37.7749,
"lng": -122.4194
},
"zoom_level": 12
}'curl -X POST http://localhost:8000/plot_polygon \
-H "Content-Type: application/json" \
-d '{
"session_id": "your-session-id",
"polygon_data": {
"polygon": {
"type": "Polygon",
"coordinates": [
[
[-122.4, 37.7],
[-122.5, 37.8],
[-122.3, 37.9],
[-122.4, 37.7]
]
]
}
}
}'The server uses an event-based architecture:
- Clients create a map session
- The map page polls the server for events
- API endpoints create events (zoom, plot_polygon, etc.)
- The map reacts to these events in real-time
All session data is stored in memory for simplicity.