Sandbox Home Full Docs Status

Welcome to SOSRoute 👋

Your API is ready. Follow the 3 steps below to ship safety features into your app in under 5 minutes.

1

Copy Your API Key

Use the sandbox key below — it works immediately. No signup, no credit card, no OAuth.

2

Make Your First Call

Hit any endpoint with X-API-Key header. Try the interactive explorer below.

3

Ship It

Parse the JSON response and render it in your UI. Average response time: 42ms.

Your Sandbox API Key

sos_test_demo1234567890abcdef12345678
Quick Start — Copy & Paste
cURL
# Find the 3 nearest hospitals to Times Square
curl -X GET "https://api.sosroute.dev/v1/contacts/nearest?lat=40.7580&lng=-73.9855&type=hospital&limit=3" \
  -H "X-API-Key: sos_test_demo1234567890abcdef12345678"
JavaScript (fetch)
const response = await fetch(
  "https://api.sosroute.dev/v1/contacts/nearest?lat=40.7580&lng=-73.9855&type=hospital&limit=3",
  { headers: { "X-API-Key": "sos_test_demo1234567890abcdef12345678" } }
);

const { data } = await response.json();

data.forEach(facility => {
  console.log(`${facility.name} — ${facility.phone} (${facility.distance_km}km)`);
});
Python (requests)
import requests

response = requests.get(
    "https://api.sosroute.dev/v1/contacts/nearest",
    params={"lat": 40.7580, "lng": -73.9855, "type": "hospital", "limit": 3},
    headers={"X-API-Key": "sos_test_demo1234567890abcdef12345678"}
)

for facility in response.json()["data"]:
    print(f"{facility['name']} — {facility['phone']} ({facility['distance_km']}km)")

🧪 Interactive API Explorer

Enter coordinates and hit "Send Request" to see a live response from the SOSRoute API.

GET /v1/contacts/nearest — Find nearest emergency facilities

Query Parameters

NameTypeRequiredDescription
latnumberRequiredLatitude (-90 to 90)
lngnumberRequiredLongitude (-180 to 180)
typestringOptionalFilter: hospital, fire_station, police_station, ems_station, urgent_care, pharmacy, 911_center
radiusstringOptionalSearch radius (default: 50km)
limitnumberOptionalMax results 1-25 (default: 5)

Response Fields

FieldTypeDescription
iduuidUnique facility identifier
typestringFacility type
namestringFacility name
phonestringContact phone number
addressstringStreet address
citystringCity
statestringState/province code
lat, lngnumberGPS coordinates
distance_mnumberDistance in meters
distance_kmnumberDistance in kilometers
GET /v1/location/risk-score — Composite 0-100 safety score

Query Parameters

NameTypeRequiredDescription
latnumberRequiredLatitude
lngnumberRequiredLongitude
radiusnumberOptionalAnalysis radius in km (1-100, default: 10)

Response

Returns a composite risk score (0 = safest, 100 = highest risk) computed from 7 weighted factors: seismic activity, weather alerts, air quality, wildfire proximity, flood zone status, crime index, and emergency facility density.

GET /v1/location/nearby-hazards — Active threats by distance

Query Parameters

NameTypeRequiredDescription
latnumberRequiredLatitude
lngnumberRequiredLongitude
radiusstringOptionalSearch radius (default: 25km)
limitnumberOptionalMax results 1-50 (default: 10)
GET /v1/alerts — Real-time hazard alerts

Query Parameters

NameTypeRequiredDescription
latnumberRequiredLatitude
lngnumberRequiredLongitude
radiusstringOptionalSearch radius (default: 50km)
sourcestringOptionalFilter by source: noaa, usgs, epa, nifc
severitystringOptionalFilter: extreme, severe, moderate, minor
POST /v1/incidents — Report a safety incident

Request Body (JSON)

FieldTypeRequiredDescription
categorystringRequiredhazmat, fire, flood, earthquake, weather, crime, infrastructure, medical, other
titlestringRequiredShort description
latnumberRequiredLatitude
lngnumberRequiredLongitude
severitystringOptionallow, medium, high, critical
POST /v1/geofences — Create a safety perimeter

Request Body (JSON)

FieldTypeRequiredDescription
namestringRequiredGeofence name
center_latnumberRequiredCenter latitude
center_lngnumberRequiredCenter longitude
radius_kmnumberRequiredRadius in km (0.1-500)
alert_typesstring[]OptionalTypes to monitor: weather, seismic, wildfire, air_quality, flood, all
webhook_urlstringOptionalURL for push notifications
POST /v1/webhooks — Subscribe to real-time push

Request Body (JSON)

FieldTypeRequiredDescription
urlstringRequiredYour webhook endpoint URL (HTTPS)
eventsstring[]RequiredEvents: alert.created, alert.updated, geofence.triggered, incident.created
secretstringOptionalSigning secret for HMAC-SHA256 payload verification
GET /v1/health — Service health check (no auth)

No authentication required. Returns service status, version, and uptime. Use this for monitoring and uptime checks.

Resources
📖

Full Documentation

Complete API reference with response schemas, error codes, and pagination.

📋

OpenAPI Spec

Download the OpenAPI 3.0 YAML spec. Import into Postman, Swagger UI, or your SDK generator.

SDK & Examples

Official JavaScript SDK, Python examples, and MCP server for AI agent integration.

💎

Upgrade to Pro

Unlock higher rate limits, live keys, webhook push, and dedicated support.

🎯

Use Case Gallery

10 app mockups showing safety features in ride-sharing, dating, delivery, insurance, and more.

🤖

AI / LLM Integration

llms.txt, MCP server, and function-calling schemas for Cursor, Claude, GPT, and other AI agents.