# RoadSoS — Emergency Services Locator for Road Accidents
## National Road Safety Hackathon 2026 | IIT Madras

---

## 📋 Software Packages Used

| Package | Version | Purpose |
|---------|---------|---------|
| Python | 3.10+ | Core programming language |
| Gradio | ≥4.0.0 | Web UI framework (responsive, mobile-friendly) |
| Folium | ≥0.19.0 | Interactive map generation (Leaflet.js wrapper) |
| Geopy | ≥2.4.0 | Geocoding (Nominatim integration) |
| SQLite3 | Built-in | Local database for incident logging |
| urllib | Built-in | HTTP requests to Overpass API |
| json | Built-in | Data serialization |
| math | Built-in | Haversine distance calculation |

### External APIs (No API key required — Free and Open):
| API | Provider | Purpose |
|-----|----------|---------|
| Overpass API | OpenStreetMap | Real-time query for hospitals, police, fire stations |
| Nominatim | OpenStreetMap | Forward/reverse geocoding (text → coordinates) |

---

## 🏗️ System Architecture

```
USER (Web/Mobile) → GRADIO UI → PYTHON BACKEND → Overpass API (OSM) + SQLite DB
                                                 → Nominatim (Geocoding)
                                                 → Folium (Map Generation)
```

---

## 📝 Assumptions

1. Internet connectivity required for real-time Overpass API queries
2. Users provide text location or GPS coordinates
3. OpenStreetMap data is comprehensive for metro cities; Tier-3 may be sparse
4. National emergency numbers (112, 108, 100) always shown as fallback
5. Designed for Golden Hour use — speed over comprehensiveness
6. English-only (production would need i18n for 22 Indian languages)
7. SQLite sufficient for hackathon; production needs PostgreSQL + PostGIS
8. No personal identifiers stored; location logged for analytics only

---

## 🚀 How to Run

```bash
pip install -r requirements.txt
python database/init_db.py
python app.py
# → http://localhost:7860
```

---

## 📊 Database Schema

- **incidents**: timestamp, lat/lon, type, severity, description, services found
- **emergency_searches**: timestamp, lat/lon, location text, radius, results count
- **trauma_centers**: name, city, state, lat/lon, phone, type, ICU/blood bank flags

---

## 🔗 Data Sources

1. OpenStreetMap (Overpass API) — live hospital/police/fire station data
2. Motor Vehicles Amendment Act 2019 — Section 134A (Good Samaritan Law)
3. MoRTH — Emergency number directory
4. NHAI — Highway helpline data
5. GVK EMRI — 108 Ambulance coverage
6. Supreme Court of India — Good Samaritan Guidelines (2016)