Hormuz Monitor API

01 — Pricing

API Plans

All plans include access to the core risk index endpoint. Free tier requires no credit card and resets every hour. Upgrade anytime without losing your API key.

Free

Explorer

$0/month

60 requests/hour
/risk endpoint (composite score)
/crisis endpoint (status + level)
/prices endpoint (delayed 15min)
/traffic endpoint (daily totals)
/vessels/live (positions)
/incidents feed
Webhooks & alerts
WebSocket stream
Historical data

Start for free →

Authentication

All API requests require an API key passed via the X-API-Key header. Keys are available on all plans including free. Never expose your API key in client-side JavaScript — use a server-side proxy for browser applications.

HTTP Header

X-API-Key: hm_live_YOUR_API_KEY_HERE

cURL Example

curl https://api.hormuzmonitor.com/v2/risk \
  -H "X-API-Key: hm_live_YOUR_API_KEY_HERE" \
  -H "Accept: application/json"

03 — Core Endpoints

Endpoints

GET /risk FREE Composite Hormuz risk index — the most important endpoint

Returns the current composite Strait of Hormuz risk score (0–10) with all five sub-dimension scores, risk level label, trend direction, and timestamp. Updated every 15 minutes on the free tier, every 5 minutes on Pro, and continuously on Enterprise.

Request

GET https://api.hormuzmonitor.com/v2/risk
X-API-Key: hm_live_YOUR_KEY

● 200 OK

JSON Response

{
  "status": "success",
  "timestamp": "2026-03-21T14:32:00Z",
  "data": {
    "risk_score": 9.2,
    "risk_level": "critical",           // low | elevated | high | critical
    "trend": "rising",                  // rising | stable | falling
    "previous_score": 8.7,
    "change_24h": +0.5,
    "crisis_active": true,
    "crisis_name": "2026 Hormuz Closure",
    "crisis_day": 22,
    "dimensions": {
      "iranian_naval_posture": 9.5,
      "diplomatic_temperature": 9.2,
      "traffic_anomaly": 8.8,
      "war_risk_insurance": 9.7,
      "incident_frequency": 8.5
    },
    "updated_at": "2026-03-21T14:30:00Z",
    "next_update": "2026-03-21T14:45:00Z"   // free tier: 15min cadence
  }
}

GET /traffic FREE Daily tanker transit counts and traffic status

JSON Response

{
  "status": "success",
  "timestamp": "2026-03-21T14:32:00Z",
  "data": {
    "transits_today": 4,
    "transits_yesterday": 3,
    "transits_7day_avg": 3.7,
    "pre_crisis_avg": 21.2,
    "reduction_pct": 82.5,
    "vessels_anchored_fujairah": 89,
    "vessels_stranded_total": 167,
    "dark_ships_detected_24h": 14,
    "traffic_status": "severely_disrupted",
    "inbound_lane_status": "closed",   // open | restricted | closed
    "outbound_lane_status": "restricted"
  }
}

GET /crisis FREE Current crisis status, summary, and key metrics

JSON Response

{
  "status": "success",
  "data": {
    "crisis_active": true,
    "crisis_name": "2026 Hormuz Closure",
    "crisis_started": "2026-02-27T00:00:00Z",
    "duration_days": 22,
    "severity": "critical",
    "oil_supply_disrupted_mbd": 15.8,
    "brent_price_usd": 121.40,
    "brent_change_since_onset": +44.30,
    "iea_spr_released_mb": 60,
    "bypass_utilisation_pct": 98,
    "summary": "Strait effectively closed since Feb 27 following US-Israel strikes on Iranian infrastructure. War-risk insurance suspended by Lloyd's. 167 vessels stranded.",
    "last_incident_at": "2026-03-21T14:32:00Z",
    "resolution_signal": "none"
  }
}

GET /prices FREE Oil benchmark prices and tanker rates (15-min delay on free tier)

JSON Response

{
  "status": "success",
  "delay_minutes": 15,   // 0 on Pro/Enterprise
  "data": {
    "brent_usd": 121.40,
    "wti_usd": 117.80,
    "dubai_usd": 119.60,
    "lng_jkm_mmbtu": 38.20,
    "vlcc_td3c_ws": 280,
    "war_risk_premium_pct": 3.5,
    "brent_ytd_change_pct": 57.6,
    "updated_at": "2026-03-21T14:17:00Z"
  }
}

GET /dependency PRO Country-level Hormuz Dependency Scores with query parameters

Parameter	Type	Required	Description
country	string	optional	ISO 3166-1 alpha-2 code (e.g. `JP`, `KR`, `IN`). Omit for all countries.
fields	string	optional	Comma-separated list: `score,import_share,spr_days,refinery_flex,economic_intensity`

JSON Response — single country

// GET /dependency?country=JP
{
  "status": "success",
  "data": {
    "country_code": "JP",
    "country_name": "Japan",
    "dependency_score": 9.1,
    "rank_globally": 2,
    "dimensions": {
      "gulf_import_share_pct": 90,
      "spr_coverage_days": 145,
      "alternative_supply_score": 3.2,
      "refinery_flexibility_score": 2.8,
      "economic_oil_intensity": 7.4
    },
    "estimated_closure_impact_gdp_pct": -3.1
  }
}

04 — Playground

Live API Playground

Try the API directly from your browser — no API key required for the sandbox. Responses are live demo data reflecting current crisis conditions.

Interactive API Tester

SANDBOX LIVE

Method

Endpoint

API Key (optional)

GET https://api.hormuzmonitor.com/v2/risk

// Response will appear here. Click RUN to execute.

Fetching response

05 — Real-time

Webhooks & WebSocket Stream

Receive push notifications when key thresholds are crossed — no need to poll. Pro and Enterprise plans support webhook endpoints and real-time WebSocket streaming.

🔔

risk.threshold.crossed

Fires when the composite risk score crosses a configured threshold (e.g. rises above 8.0)

PRO

🚢

incident.new

Fires on each new confirmed maritime security incident in or near the Strait of Hormuz

PRO

💰

price.spike

Fires when Brent crude moves more than a configured percentage in a rolling 1-hour window

PRO

⚡

crisis.status.change

Fires on any change to crisis_active status or crisis severity level

PRO

📡

WebSocket stream — wss://stream.hormuzmonitor.com/v2

Real-time continuous feed of all risk scores, traffic updates, incident events, and price ticks

ENTERPRISE

Webhook payload example — risk.threshold.crossed

{
  "event": "risk.threshold.crossed",
  "timestamp": "2026-03-21T14:32:00Z",
  "data": {
    "previous_score": 7.8,
    "current_score": 8.1,
    "configured_threshold": 8.0,
    "direction": "crossed_above",
    "risk_level": "high"
  },
  "webhook_id": "wh_01HXYZ"
}

06 — SDKs

SDKs & Client Libraries

Official client libraries for the most common languages. All SDKs are open source on GitHub. Community contributions welcome.

🟩

🐍

🔷

☕

🦀

Node.js — npm install hormuz-api

import { HormuzClient } from 'hormuz-api';

const client = new HormuzClient({
  apiKey: process.env.HORMUZ_API_KEY
});

// Get current risk score
const risk = await client.risk.getCurrent();
console.log(`Risk score: ${risk.data.risk_score} (${risk.data.risk_level})`);

// Subscribe to threshold alerts
client.webhooks.subscribe('risk.threshold.crossed', {
  threshold: 8.0,
  url: 'https://your-app.com/webhooks/hormuz'
});

Python — pip install hormuz-api

from hormuz_api import HormuzClient
import os

client = HormuzClient(api_key=os.environ['HORMUZ_API_KEY'])

# Get current risk score
risk = client.risk.get_current()
print(f"Risk: {risk.data.risk_score} — {risk.data.risk_level}")

# Get historical data (Pro+)
history = client.risk.get_history(days=30)
for point in history.data:
    print(f"{point.date}: {point.risk_score}")

07 — Rate Limits

Rate Limits

Rate limits are enforced per API key. All responses include X-RateLimit-Remaining and X-RateLimit-Reset headers. Exceeding the limit returns a 429 Too Many Requests response.

Plan	Requests / hour	Burst (per minute)	Concurrent WebSocket
Free (Explorer)	60	10	—
Pro (Professional)	5,000	200	—
Enterprise (Institutional)	Unlimited	Unlimited	Up to 50 connections

Rate limit response headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1742569800   // Unix timestamp of next window reset
X-Plan: free

08 — Errors

Error Codes

All errors return a consistent JSON envelope with a machine-readable error_code and a human-readable message.

400

Bad Request — Invalid query parameters. Check parameter types and allowed values in the endpoint docs.

401

Unauthorized — Missing or invalid X-API-Key header. Verify your key at the dashboard.

403

Forbidden — Your current plan does not include this endpoint. Upgrade to access badge-pro or badge-ent endpoints.

429

Too Many Requests — Rate limit exceeded. Check X-RateLimit-Reset header and retry after that timestamp.

500

Internal Server Error — Unexpected server error. Retry with exponential backoff. If persistent, check status.hormuzmonitor.com.

Error response envelope

{
  "status": "error",
  "error_code": "PLAN_LIMIT_EXCEEDED",
  "message": "This endpoint requires a Pro or Enterprise plan.",
  "upgrade_url": "https://mhh.gic.mybluehost.me/hormuz-live-api/#pricing",
  "http_status": 403
}

09 — Get Started

Get Your Free API Key

No credit card required. Free tier includes 60 requests/hour, the /risk, /crisis, /traffic, and /prices endpoints. Your key is issued instantly.

Email address

Use case

Plan

Generate My API Key →

By requesting an API key you agree to the API Terms of Service. Free tier keys are for non-commercial use. Production deployments require a paid plan.

Hormuz Monitor API

Hormuz Live API

API Plans

Authentication

Endpoints

Live API Playground

Webhooks & WebSocket Stream

SDKs & Client Libraries

Rate Limits

Error Codes

Get Your Free API Key