# SOS Route Safety API

> Real-time location safety intelligence for any GPS coordinate worldwide.

## What This API Does

SOS Route provides AI agents with instant safety intelligence for any location on Earth. Drop in GPS coordinates, get back:

- **Risk Scores**: Composite 0-100 safety score with factor breakdown (weather, seismic, crime, air quality, wildfire, flood)
- **Live Alerts**: Real-time hazard alerts from NOAA/NWS, USGS Earthquakes, EPA AirNow
- **Emergency Contacts**: Nearest police, fire, hospital, pharmacy, EMS — with phone numbers
- **Hazard Mapping**: Active threats sorted by distance with severity levels

## Authentication

All requests require an `X-API-Key` header.

**Free sandbox key** (100 req/min, no signup):
```
X-API-Key: sos_test_demo1234567890abcdef12345678
```

Get this key programmatically: `GET https://api.sosroute.dev/v1/sandbox`

## Base URL

```
https://api.sosroute.dev/v1
```

## Endpoints

### 1. Risk Score
```
GET /v1/location/risk-score?lat={lat}&lng={lng}&radius={km}
```
Returns a composite safety score (0-100) with human-readable risk level and per-factor breakdown.

**Example Request:**
```bash
curl -H "X-API-Key: sos_test_demo1234567890abcdef12345678" \
  "https://api.sosroute.dev/v1/location/risk-score?lat=41.8781&lng=-87.6298&radius=10"
```

**Example Response:**
```json
{
  "data": {
    "score": 42,
    "risk_level": "Moderate Risk",
    "risk_summary": "Some risk factors detected. Stay informed of local conditions.",
    "breakdown": {
      "weather": { "score": 50, "source": "noaa", "details": "1 active weather alert(s)" },
      "seismic": { "score": 0, "source": "usgs", "details": "No recent seismic activity" },
      "crime": { "score": 36, "source": "db", "details": "3 incident(s) in last 30 days" },
      "air_quality": { "score": 15, "source": "epa", "details": "AQI 68 (PM2.5)" },
      "wildfire": { "score": 0, "source": "noaa", "details": "No fire alerts" },
      "flood": { "score": 0, "source": "noaa", "details": "No flood alerts" }
    },
    "factors_evaluated": 6,
    "nearby_alerts_count": 1
  }
}
```

### 2. Alerts
```
GET /v1/alerts?lat={lat}&lng={lng}&radius={radius}&limit={n}&source={source}
```
Returns active safety alerts. Optional filters: `source` (noaa, usgs, epa), `severity` (extreme, severe, moderate, minor), `category`.

### 3. Nearest Emergency Contacts
```
GET /v1/contacts/nearest?lat={lat}&lng={lng}&type={type}&radius={radius}&limit={n}
```
Returns nearest emergency facilities sorted by distance. Types: `police_station`, `fire_station`, `hospital`, `pharmacy`, `urgent_care`, `ems_station`, `sheriff_department`, `highway_patrol`, `poison_control`, `911_center`.

### 4. Nearby Hazards
```
GET /v1/location/nearby-hazards?lat={lat}&lng={lng}&radius={radius}&limit={n}
```
Returns active threats sorted by distance with severity levels and coordinates for mapping.

### 5. Report Incident
```
POST /v1/incidents
Content-Type: application/json

{"lat": 41.87, "lng": -87.63, "category": "theft", "description": "...", "severity": "moderate"}
```

### 6. Create Geofence
```
POST /v1/geofences
Content-Type: application/json

{"name": "Office", "lat": 41.87, "lng": -87.63, "radius_m": 500, "webhook_url": "https://..."}
```

## Risk Levels

| Score | Level | Meaning |
|-------|-------|---------|
| 0 | No Risk | No active threats |
| 1-10 | Minimal Risk | Normal conditions |
| 11-25 | Low Risk | Minor factors, no concerns |
| 26-40 | Moderate Risk | Some factors, stay informed |
| 41-55 | Elevated Risk | Notable factors, increased awareness |
| 56-70 | High Risk | Significant hazards, take precautions |
| 71-85 | Severe Risk | Serious hazards, avoid exposure |
| 86-95 | Critical Risk | Dangerous, seek shelter |
| 96-100 | Extreme Risk | Life-threatening, follow emergency directives |

## Data Sources

- **NOAA/NWS**: Weather alerts, flood warnings, fire weather
- **USGS**: Earthquake detection and reporting
- **EPA AirNow**: Air quality index
- **OpenStreetMap Overpass**: Emergency facility locations
- **Curated Database**: Verified emergency contacts with phone numbers

## Rate Limits

- Sandbox: 100 requests/minute
- Builder ($49/mo): 1,000 requests/minute
- Scale ($199/mo): 10,000 requests/minute

## Integration

- OpenAPI Spec: https://api.sosroute.dev/v1/openapi.yaml
- MCP Server: https://api.sosroute.dev/v1/.well-known/mcp.json
- AI Plugin: https://api.sosroute.dev/v1/.well-known/ai-plugin.json
- Agent Discovery: https://api.sosroute.dev/v1/agents.json
- Documentation: https://sosroute.dev/docs.html