{"id":31320637,"url":"https://github.com/moking55/hazard-aware-routing-api","last_synced_at":"2026-05-06T17:31:36.644Z","repository":{"id":315661175,"uuid":"1060389534","full_name":"moking55/hazard-aware-routing-api","owner":"moking55","description":"FastAPI service for calculating optimal routes that avoid hazardous areas. Leverages OpenStreetMap data to generate safe paths with customizable risk tolerance. Features hazard zone management, interactive map visualization, and Docker deployment.","archived":false,"fork":false,"pushed_at":"2025-09-19T21:57:55.000Z","size":20,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-30T08:58:18.238Z","etag":null,"topics":["astar-algorithm","fastapi","openstreetmap","python","python3","rest-api"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/moking55.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-19T20:39:00.000Z","updated_at":"2025-09-19T21:57:58.000Z","dependencies_parsed_at":"2025-09-20T00:16:46.290Z","dependency_job_id":"7361f45b-7e89-41e0-b601-e33f0b34439e","html_url":"https://github.com/moking55/hazard-aware-routing-api","commit_stats":null,"previous_names":["moking55/hazard-aware-routing-api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/moking55/hazard-aware-routing-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moking55%2Fhazard-aware-routing-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moking55%2Fhazard-aware-routing-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moking55%2Fhazard-aware-routing-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moking55%2Fhazard-aware-routing-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/moking55","download_url":"https://codeload.github.com/moking55/hazard-aware-routing-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moking55%2Fhazard-aware-routing-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32704276,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-06T08:33:17.875Z","status":"ssl_error","status_checked_at":"2026-05-06T08:33:17.221Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["astar-algorithm","fastapi","openstreetmap","python","python3","rest-api"],"created_at":"2025-09-25T16:53:11.753Z","updated_at":"2026-05-06T17:31:36.639Z","avatar_url":"https://github.com/moking55.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hazard-Aware Routing API\n\nA FastAPI-based REST API for calculating safe routes that avoid hazardous areas.\n\n## 🏗️ Project Structure\n\n```\nroute_optimization/\n├── main.py              # FastAPI app initialization and startup\n├── config.py            # Configuration and constants\n├── models.py            # Pydantic data models\n├── routing_service.py   # Core routing logic and OSM integration\n├── map_service.py       # Map visualization with Folium\n├── storage_service.py   # In-memory data storage (replace with DB in prod)\n├── requirements.txt     # Python dependencies\n├── routes/              # API endpoint modules\n│   ├── __init__.py\n│   ├── health.py        # Health check endpoints\n│   ├── hazards.py       # Hazard zone CRUD operations\n│   └── routing.py       # Route calculation and maps\n└── __pycache__/         # Python cache files\n```\n\n## 🚀 Features\n\n- **Safe Route Calculation**: Uses A* algorithm to find optimal paths avoiding hazards\n- **Hazard Zone Management**: CRUD operations for dangerous areas\n- **Interactive Maps**: Folium-based visualization with routes and hazard zones\n- **Multiple Transport Modes**: Support for driving, walking, and cycling\n- **Caching**: Intelligent caching of OSM graphs and route results\n- **RESTful API**: Clean, documented endpoints with FastAPI\n\n## 📦 Installation \u0026 Deployment\n\n### Local Development\n\n1. Install dependencies:\n\n```bash\npip install -r requirements.txt\n```\n\n2. Run the development server:\n\n```bash\nuvicorn main:app --reload --host 0.0.0.0 --port 8000\n```\n\n### Docker Deployment\n\n#### Quick Start with Docker Compose\n\n```bash\n# Clone and navigate to project\ncd route_optimization\n\n# Start all services\ndocker-compose up -d\n\n# View logs\ndocker-compose logs -f\n\n# Stop services\ndocker-compose down\n```\n\n#### Manual Docker Build\n\n```bash\n# Build development image\ndocker build -t hazard-routing-api .\n\n# Build production image\ndocker build -t hazard-routing-api:prod -f Dockerfile.prod .\n\n# Run container\ndocker run -p 8000:8000 hazard-routing-api\n```\n\n#### Windows Build Script\n\n```cmd\n# Build with default settings\nbuild.bat\n\n# Build with custom tag\nbuild.bat v1.0.0\n\n# Build production image\nbuild.bat prod Dockerfile.prod\n```\n\n#### Linux/Mac Build Script\n\n```bash\n# Make script executable\nchmod +x build.sh\n\n# Build with default settings\n./build.sh\n\n# Build with custom tag\n./build.sh v1.0.0\n\n# Build production image\n./build.sh prod Dockerfile.prod\n```\n\n3. Access the API:\n- **API Documentation**: http://localhost:8000/docs\n- **API Interface**: http://localhost:8000/\n- **Health Check**: http://localhost:8000/health\n\n## 🛠️ API Endpoints\n\n### Route Calculation\n- **POST /route** - Calculate safe route between two points\n- **GET /map/{route_id}** - Get interactive HTML map\n- **GET /route/{route_id}/stats** - Get route statistics\n\n### Hazard Management\n- **GET /hazards** - List all hazard zones\n- **POST /hazards** - Add new hazard zone\n- **DELETE /hazards/{hazard_id}** - Remove hazard zone\n\n### System\n- **GET /health** - API health check\n- **GET /** - API documentation page\n\n## 🔧 Configuration\n\nKey settings in `config.py`:\n- **Default location**: Chiang Mai, Thailand\n- **Transport speeds**: Drive (50 km/h), Walk (5 km/h), Bike (15 km/h)\n- **Hazard levels**: 1-10 scale\n- **Default danger threshold**: 3 (blocks hazards level 4+)\n\n## 📊 Code Architecture\n\n### Services Layer\n- **RoutingService**: OSM graph management and pathfinding\n- **MapService**: Folium map generation and styling\n- **StorageService**: Data persistence and caching\n\n### API Layer\n- Modular route handlers grouped by functionality\n- Consistent error handling and response models\n- Automatic API documentation with Pydantic\n\n### Data Models\n- Type-safe Pydantic models for all API inputs/outputs\n- Validation for coordinates, hazard levels, and route parameters\n\n## 🔍 Example Usage\n\n### Calculate Route\n```bash\ncurl -X POST \"http://localhost:8000/route\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"start\": {\"lat\": 18.7876, \"lon\": 98.9917},\n    \"end\": {\"lat\": 18.7913, \"lon\": 99.0014},\n    \"danger_threshold\": 3\n  }'\n```\n\n### Add Hazard Zone\n```bash\ncurl -X POST \"http://localhost:8000/hazards\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"lat\": 18.787,\n    \"lon\": 98.9905,\n    \"level\": 5,\n    \"name\": \"Construction Zone\",\n    \"radius_m\": 150\n  }'\n```\n\n## 🚧 Production Considerations\n\n1. **Database**: Replace `StorageService` with PostgreSQL/MongoDB\n2. **Authentication**: Add API key or OAuth2 authentication\n3. **Rate Limiting**: Implement request throttling\n4. **Monitoring**: Add logging, metrics, and health checks\n5. **Deployment**: Use production WSGI server with multiple workers\n\n## 🐳 Docker Configuration\n\n### Available Dockerfiles\n\n- **`Dockerfile`**: Multi-stage development build with all tools\n- **`Dockerfile.prod`**: Optimized production build with minimal layers\n\n### Docker Compose Services\n\n- **route-api**: Main FastAPI application\n- **redis**: Optional caching layer (commented)\n- **postgres**: Optional database backend (commented)\n\n### Environment Variables\n\n- `PYTHONPATH`: Set to `/app`\n- `LOG_LEVEL`: Logging level (INFO, DEBUG, WARNING, ERROR)\n- `WORKERS`: Number of Uvicorn workers (production)\n- `MAX_WORKERS`: Maximum worker limit\n\n### Health Checks\n\nThe Docker containers include health checks that:\n- Test the `/health` endpoint every 30 seconds\n- Allow 40 seconds for startup\n- Retry 3 times before marking unhealthy\n- Timeout after 10 seconds per check","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoking55%2Fhazard-aware-routing-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmoking55%2Fhazard-aware-routing-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoking55%2Fhazard-aware-routing-api/lists"}