API Documentation

Real-time maritime corridor risk intelligence. Integrate risk scores, vessel traffic data, and conflict events into your applications.

Base URL

https://corridorrisk.io/api

Authentication

The API is currently open during the beta period. API keys will be required for production use. Contact hello@corridorrisk.io for early access.

Corridors

The following corridor IDs are used across all endpoints:

east-med Eastern Mediterranean

persian-gulf Persian Gulf & Strait of Hormuz

red-sea Red Sea & Bab-el-Mandeb

south-china-sea South China Sea

black-sea Black Sea & Turkish Straits

gulf-guinea Gulf of Guinea

suez Suez Canal Approach

Endpoints

GET /api/corridors All corridors with latest scores & traffic

Returns all 7 corridors with their current risk score, vessel traffic data, incident counts, and AI-generated intelligence reports.

Example Request

curl https://corridorrisk.io/api/corridors

Response Fields

Field	Type	Description
id	string	Corridor identifier
score	integer	Composite risk score (0-100)
vessel_count	integer	Vessels detected at monitoring port
disruption_pct	integer	Traffic disruption vs baseline (%)
incident_count_7d	integer	Unique incidents in past 7 days
incident_count_30d	integer	Unique incidents in past 30 days
risk_report	object	AI-generated intelligence (situation, impact, outlook, action)
computed_at	datetime	When the score was last computed

Example Response

[
  {
    "id": "persian-gulf",
    "name": "Persian Gulf & Strait of Hormuz",
    "score": 94,
    "vessel_count": 2,
    "disruption_pct": 99,
    "incident_count_7d": 1125,
    "incident_count_30d": 2811,
    "risk_report": {
      "situation": "Acute military escalation...",
      "impact": "Transit RESTRICTED...",
      "key_incidents": ["..."],
      "outlook": "Escalating...",
      "action": "REROUTE via Cape of Good Hope..."
    },
    "computed_at": "2026-03-08T14:06:38"
  }
]

GET /api/score/{corridor_id} Score history & vessel traffic trends

Returns the current score details and historical score data for trend analysis.

Parameters

Param	Type	Default	Description
corridor_id	path	required	Corridor ID (e.g., persian-gulf)
days	query	30	History window (1-90 days)

Example Request

curl https://corridorrisk.io/api/score/persian-gulf?days=30

GET /api/events/{corridor_id} Conflict events with source links

Returns individual conflict events for a corridor, including severity, event type, coordinates, and source URLs.

Parameters

Param	Type	Default	Description
corridor_id	path	required	Corridor ID
days	query	7	Lookback window (1-30 days)

Example Request

curl https://corridorrisk.io/api/events/red-sea?days=7

Event Types

Type	Severity	Description
armed_attack	4-5	Armed conflict, assault, fight
military_deployment	3-4	Military coercion, force posture
material_conflict	3	Material conflict actions
protest	3	Protests affecting shipping/ports
diplomatic	2	Diplomatic tensions
tension	2	Political tension

GET /api/weather/{corridor_id} Marine weather conditions

Returns current marine weather including wave height, wind speed, sea state, and atmospheric conditions.

Example Request

curl https://corridorrisk.io/api/weather/red-sea

Response Fields

Field	Type	Description
conditions	string	Weather description (Clear, Partly cloudy, etc.)
temperature_c	float	Temperature in Celsius
wind_speed_kmh	float	Wind speed in km/h
wave_height_m	float	Wave height in meters (null for enclosed seas)
sea_state	string	Calm, Slight, Moderate, Rough, Very rough, High

POST /api/subscribe Subscribe to Maritime Risk Brief

Subscribe an email address to the weekly Maritime Risk Brief newsletter.

Request Body

{"email": "analyst@company.com"}

Scoring Methodology

The composite risk score (0-100) is computed using a hybrid model that fuses AIS vessel traffic with GDELT conflict event data:

Component	Weight	Source	Description
Traffic Disruption	40%	AIS (Datalastic)	Vessel count vs historical baseline at monitoring port
Event Volume	25%	GDELT	Z-score anomaly of conflict event frequency
Conflict Composition	20%	GDELT	Percentage of material conflict vs verbal tension
Trend	15%	GDELT	Week-over-week change in event frequency

When AIS data is unavailable, the system falls back to a GDELT-only model with adjusted weights.

Rate Limits

During the beta period, the API has a soft limit of 100 requests per minute per IP. For production integrations requiring higher throughput, contact us.

Ready to integrate?

Get corridor-level risk scoring in your TMS, ERP, or insurance platform.

Contact for API Access

CorridorRisk.io — Maritime Intelligence Platform

Data: GDELT + Datalastic AIS • AI: Claude • Weather: Open-Meteo