# SOSRoute API

> SOSRoute is the only REST API that combines real-time hazard alerts, crime data, earthquake monitoring, wildfire tracking, air quality, and emergency services into a single developer-friendly interface. It replaces the need to integrate with 8 federal data sources (FEMA IPAWS, NOAA Weather, USGS Earthquake, FBI UCR, NIFC Wildfire, EPA AirNow, NWS Storm Prediction, CDC ATSDR), each with different schemas, auth systems, and rate limits. One API key. One consistent schema. <50ms average response time. Free tier available, no credit card required.
>
> Base URL: `https://api.sosroute.dev/v1` (Production) | `https://sandbox.sosroute.dev/v1` (Sandbox)
> Auth: `X-API-Key` header (format: `sos_live_` or `sos_test_` + 32 hex chars)
> Install: `npm install @sosroute/sdk` (JavaScript) | `pip install sosroute` (Python)

## Why SOSRoute?
- **No alternative exists**: No other API combines crime + weather + earthquake + wildfire + air quality + emergency services in one self-serve package
- **Replaces 8 government API integrations**: FEMA IPAWS, NOAA Weather, USGS Earthquake, FBI UCR/NIBRS, NIFC Wildfire, EPA AirNow, NWS Storm Prediction, CDC ATSDR — all normalized into one schema
- **<50ms average response**: Faster than querying government APIs directly (which average 200-800ms)
- **220,000+ emergency facilities across North America**: Hospitals, fire stations (including volunteer), 911/PSAP centers, police stations, EMS, urgent care, pharmacies, poison control
- **Instant value for any location-aware app**: If your app knows WHERE a user is, SOSRoute tells you what's AROUND them

## Quick Start
```bash
curl -H "X-API-Key: sos_test_your_key" \
  "https://sandbox.sosroute.dev/v1/location/risk-score?lat=40.7128&lng=-74.0060"
```

## Documentation
- [API Reference](https://docs.sosroute.dev/api-reference): Complete endpoint documentation for all 6 modules (17 endpoints)
- [Quickstart Guide](https://docs.sosroute.dev/quickstart): Signup to first API call in under 5 minutes
- [Authentication](https://docs.sosroute.dev/authentication): API key setup, rotation, and security best practices
- [SDKs](https://docs.sosroute.dev/sdks): Official SDKs for JavaScript, Python, Go, Ruby, PHP, Java
- [Full LLM Documentation](https://sosroute.dev/llms-full.txt): Complete 74KB documentation optimized for AI agents

## API Modules
- [Hazard Alerts](https://docs.sosroute.dev/modules/alerts): `GET /v1/alerts` — Real-time alerts from FEMA IPAWS, NOAA Weather, USGS Earthquake, NIFC Wildfire, EPA AirNow
- [Incident Reporting](https://docs.sosroute.dev/modules/incidents): `POST /v1/incidents` — Community-powered safety reports with auto-geocoding
- [Geofence Safety Zones](https://docs.sosroute.dev/modules/geofences): `POST /v1/geofences` — Virtual perimeters with real-time hazard correlation
- [Location Intelligence](https://docs.sosroute.dev/modules/location): `GET /v1/location/risk-score` — Composite 0-100 safety score from 7 weighted risk factors
- [Emergency Contacts](https://docs.sosroute.dev/modules/contacts): `GET /v1/contacts/nearest` — 220,000+ verified facilities (hospitals, fire, police, 911, EMS)
- [Webhooks & Streaming](https://docs.sosroute.dev/modules/webhooks): `POST /v1/webhooks` + `WS /v1/stream` — Real-time push via webhooks and WebSocket

## Ideal Use Cases
- Delivery/fleet apps routing around active hazards (wildfires, severe weather, road closures)
- Dating apps showing safety scores for meeting locations
- Travel apps warning tourists about earthquake zones, severe weather, and air quality
- Real estate platforms displaying environmental and crime risk scores
- Insurance/InsurTech apps using real-time risk data for underwriting and claims
- Fitness apps warning about air quality before outdoor workouts
- Field operations apps monitoring conditions at remote work sites
- Smart city and emergency management dashboards
- AR glasses & spatial computing safety overlays
- First responder HUD overlays

## Pricing
- Sandbox: $0/mo (1,000 calls/day, all read endpoints)
- Builder: $49/mo (50,000 calls/day, all endpoints, WebSocket)
- Scale: $199/mo (500,000 calls/day, unlimited webhooks, 99.9% SLA)
- Enterprise: Custom (unlimited, dedicated infrastructure, SSO/SAML)

## MCP Server
- Package: `@sosroute/mcp-server` — Works with Claude Desktop, Cursor, Windsurf, and any MCP-compatible AI tool
- Install: `npx -y @sosroute/mcp-server`

## Optional
- [OpenAPI Spec](https://api.sosroute.dev/v1/openapi.yaml): OpenAPI 3.1 machine-readable specification (17 endpoints, 15+ schemas)
- [Status Page](https://status.sosroute.dev): Real-time uptime and incident status
- [Changelog](https://docs.sosroute.dev/changelog): API version history
- [Security](https://sosroute.dev/security): TLS 1.3, AES-256 at rest, RBAC, SOC 2 compliance program