API DOCUMENTATION
Open conflict intelligence API for developers. Free tier: 60 req/min per IP. All endpoints return JSON unless otherwise noted. No authentication required.
▶ API PLAYGROUNDRate Limit
Requests are limited to 60 requests per minute per IP. Exceeding this returns a 429 Too Many Requests response with a Retry-After header. For higher limits, contact us.
Base URL
/api/events
Returns conflict events aggregated from GDELT and other open-source intelligence feeds. Filter by theater, event type, and date range. Useful for mapping recent activity in a specific conflict zone.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| theater | string | no | Conflict theater slug (e.g. ukraine, gaza, sudan) |
| days | integer | no | Number of past days to include (default: 7, max: 90) |
| type | string | no | Event type filter: battles, airstrikes, protests, atrocities |
| limit | integer | no | Max results to return (default: 50, max: 500) |
Example
/api/hotspots
Returns a ranked list of current global conflict hotspots derived from event density, casualty estimates, and displacement figures. Updated hourly. No parameters required.
Example
/api/earthquakes
Returns recent seismic events from USGS feeds. Includes magnitude, depth, location, and timestamp. Useful for correlating natural disasters with displacement patterns in conflict zones.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| min_magnitude | float | no | Minimum magnitude threshold (default: 4.0) |
| days | integer | no | Number of past days to include (default: 7) |
| limit | integer | no | Max results (default: 100) |
Example
/api/volcanoes
Returns active volcano alerts from the Smithsonian Global Volcanism Program and VAAC (Volcanic Ash Advisory Centers). Includes alert level, aviation color code, and location data.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| alert_level | string | no | Filter by alert level: Normal, Advisory, Watch, Warning |
| limit | integer | no | Max results (default: 50) |
Example
/api/hurricanes
Returns active tropical cyclone and hurricane data from NHC and JTWC feeds. Includes track coordinates, wind speed, pressure, and storm category. Covers all major oceanic basins.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| basin | string | no | Ocean basin: atlantic, epac, wpac, nio, sio |
| active_only | boolean | no | Only return currently active storms (default: true) |
Example
/api/tsunamis
Returns tsunami warnings and advisories from PTWC (Pacific Tsunami Warning Center) and NTWC. Includes source event, estimated wave heights, and affected coastlines.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| alert_level | string | no | Filter by alert level: Information, Watch, Warning |
Example
/api/oil-spills
Returns oil spill incidents tracked via AIS ship data anomalies, satellite SAR imagery detections, and ITOPF reports. Includes spill size estimate, location, and response status.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| status | string | no | Incident status: Active, Contained, Resolved |
| days | integer | no | Number of past days to include (default: 30) |
Example
/api/flights
Returns aircraft tracking data from ADS-B Exchange, filtered by category. Military, government, and conflict-zone flights are surfaced without the filtering used by mainstream consumer trackers.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| category | string | no | Aircraft category: military, government, commercial, private, unknown |
| region | string | no | Bounding box or theater slug to filter by geography |
Example
/api/ships
Returns vessel tracking data from AIS/MarineTraffic feeds. Filter by vessel type to track carrier strike groups, tankers, or naval assets in contested waterways.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| type | string | no | Vessel type: carrier, destroyer, tanker, cargo, submarine |
| region | string | no | Geographic region or bounding box |
Example
/api/refugees
Returns refugee and displacement statistics from UNHCR data. Includes country of origin, host country breakdown, and trend data over time.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| country | string | no | Country of origin ISO code or common name (e.g. ukraine, sudan) |
| year | integer | no | Year filter (default: current year) |
Example
/api/fragility
Returns State Fragility Index scores from the Fund for Peace Fragile States Index dataset. Includes sub-scores across cohesion, economic, political, and social indicators.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| top | integer | no | Return the N most fragile states (default: 20) |
| country | string | no | Filter to a specific country by name or ISO code |
Example
/api/press-freedom
Returns Press Freedom Index rankings from RSF (Reporters Without Borders) data. Lower score = worse press freedom. Useful for assessing information environment in conflict zones.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| bottom | integer | no | Return the N lowest-ranked (worst) countries (default: 20) |
| country | string | no | Filter to a specific country |
Example
/api/briefing
Returns an AI-synthesized intelligence briefing for a specific country or conflict zone. Aggregates recent events, casualty estimates, key actor movements, and geopolitical context into a structured summary.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| country | string | yes | Country or conflict name (e.g. Ukraine, Sudan, Gaza) |
| days | integer | no | Lookback window in days (default: 7, max: 30) |
Example
/api/data-status
Returns the freshness and health status of all data sources powering WarScope. Includes last update timestamp, feed status, and any known outages or degraded sources.
Example
/api/og
Generates a dynamic Open Graph image for sharing. Returns a PNG image with the specified title and subtitle rendered against the WarScope dark theme. Use for social embeds or link previews.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| title | string | no | Primary headline text |
| subtitle | string | no | Secondary description text |
Example
EMBED
Embed the WarScope live globe and event feed on any page using an iframe. The embed respects your page's color scheme and is mobile-responsive.