API Reference

REST API for vessel tracking, commodity flow intelligence, risk scoring, and market data across 40 global ports. All endpoints return JSON unless noted otherwise.

Base URL: https://axiomoverwatch.io/api/v154 endpointsv1

Overview

Authentication

All data endpoints require an API key. Pass it via X-API-Key: <YOUR_KEY> header or Authorization: Bearer <YOUR_KEY>. Only /ports, /health, and /billing/plans are public.

Access Tiers

Free50 req/day, 20 results/call, 7 days history, no position coordinates

Starter1,000 req/day, 100 results/call, 90 days history, full coordinates, CSV export

Pro10,000 req/day, 500 results/call, full history, webhooks, priority support

Rate Limiting

All API routes are rate limited to 60 requests per minute per IP address, plus daily limits per tier. Exceeding either returns 429 Too Many Requests.

Response Format

All responses are JSON. Data is wrapped in a descriptive root key. Errors return { "error": "message" } with appropriate HTTP status codes.

Methodology Transparency

Public cargo-estimate validation methodology and latest bias metrics are available at /docs/methodology/cargo-validation.

Port Slugs

Many endpoints accept a port query parameter as a URL-friendly slug (e.g., santos, houston, new-orleans). Use the /ports endpoint to list all available slugs.

Quick Start

# List all ports (public, no key needed)
curl https://axiomoverwatch.io/api/v1/ports

# Get export estimates (requires API key)
curl -H "X-API-Key: YOUR_KEY" \
  "https://axiomoverwatch.io/api/v1/estimates?port=santos"

# Get high-risk vessels
curl -H "X-API-Key: YOUR_KEY" \
  "https://axiomoverwatch.io/api/v1/risk/vessels?tier=high"

# Get live vessel positions at Houston
curl -H "X-API-Key: YOUR_KEY" \
  "https://axiomoverwatch.io/api/v1/positions?port=houston"

Ports

List monitored ports across all verticals.

GET

/api/v1/ports

List all monitored ports with slug, name, country, and region.

Response: { "ports": [...] }

GET

/api/v1/health

System health check. Returns position counts and ingestion status.

Response: { "status", "positions", "vessels", "positions_last_hour" }

Vessels & Positions

Vessel registry and real-time AIS positions.

GET

/api/v1/vessels

Search vessels by port and type. Returns IMO, name, DWT, flag, dimensions.

Parameters

portstringPort slug

typestringVessel type filter

limitnumberDefault 50, max 200

Response: { "vessels": [...] }

GET

/api/v1/positions

Latest AIS positions for all vessels at a port. Includes course, speed, draft, nav status.

Parameters

portstringrequiredPort slug

Response: [{ imo_number, latitude, longitude, speed, course, draft, nav_status, name, vessel_type }]

Export Estimates

Weekly aggregated cargo volume predictions by port.

GET

/api/v1/estimates

Weekly export volume estimates with vessel count, tonnage, confidence, and USDA actuals.

Parameters

portstringPort slug

limitnumberDefault 52, max 200

Response: { "estimates": [...] }

Risk Intelligence

13-factor risk scoring, dark fleet detection, STS transfers, loitering, identity changes, and draft anomalies.

GET

/api/v1/risk/vessels

All risk-scored vessels. Filter by tier, type, or flag.

Parameters

tierstring'critical' | 'high' | 'medium' | 'low'

typestringVessel type

flagstringFlag state code

limitnumberDefault 500

Response: { "vessels": [...] }

GET

/api/v1/risk/vessel/{imo}

Full risk profile for a single vessel including dark events.

Parameters

imostringrequired7-digit IMO number (path param)

Response: { "vessel": {...}, "dark_events": [...] }

GET

/api/v1/risk/events

Dark fleet AIS gap events. Filter by tier or vessel.

Parameters

tierstringRisk tier filter

vesselstringIMO number

ongoingstring'true' for active gaps only

limitnumberDefault 100, max 500

Response: { "events": [...] }

GET

/api/v1/risk/stats

Aggregate risk statistics: active gaps, critical vessels, hotspots, events by tier.

Response: { "active_gaps", "critical_vessels", "active_hotspots", "new_events_24h", "events_by_tier" }

GET

/api/v1/risk/sts

Ship-to-ship transfer events with confidence and draft transfer data.

Parameters

confidencestringConfidence level filter

vesselstringIMO number (checks both vessels)

methodstringDetection method

limitnumberDefault 100, max 500

Response: { "events": [...] }

GET

/api/v1/risk/sts/stats

STS aggregate statistics: total events, by confidence, tonnage, active encounters.

Response: { "total_events", "by_confidence", "total_tonnage", "active_encounters" }

GET

/api/v1/risk/loitering

Loitering events (stationary or slow-roll) with context zones.

Parameters

typestring'stationary' | 'slow_roll'

vesselstringIMO number

contextstringContext zone

limitnumberDefault 100, max 500

Response: { "events": [...] }

GET

/api/v1/risk/identity

Vessel identity change events (flag, name, MMSI).

Parameters

fieldstring'flag' | 'name' | 'mmsi'

vesselstringIMO number

limitnumberDefault 100, max 500

Response: { "events": [...] }

GET

/api/v1/risk/identity/history

Full identity history for a vessel.

Parameters

vesselstringrequiredIMO number

Response: { "history": [...] }

GET

/api/v1/risk/mismatches

Draft mismatch events: directional, magnitude, or zero-change anomalies.

Parameters

typestring'directional' | 'magnitude' | 'zero_change'

vesselstringIMO number

portstringPort ID (UUID)

limitnumberDefault 100, max 500

Response: { "events": [...] }

GET

/api/v1/risk/hotspots

STS hotspot zones (seeded and auto-discovered).

Parameters

activestringDefault 'true'. Pass 'false' for all.

limitnumberDefault 200, max 500

Response: { "hotspots": [...] }

GET

/api/v1/risk/baselines

Port-level draft baselines used for anomaly detection.

Response: { "baselines": [...] }

Congestion

Port congestion indices and wait time trends.

GET

/api/v1/congestion

Latest congestion snapshot for all ports or a specific port.

Parameters

portstringPort slug

vessel_typestringFilter by vessel type

Response: { "congestion": [...] }

GET

/api/v1/congestion/history

Historical congestion data for a port.

Parameters

portstringrequiredPort slug

daysnumberDefault 30, max 365

vessel_typestringFilter by vessel type

Response: { "port", "port_name", "days", "vessel_type", "history" }

POST

/api/v1/congestion/refreshAUTH

Trigger congestion index recomputation.

Response: { "success", "result" }

Berth Utilization

Berth occupancy rates and turnaround times.

GET

/api/v1/berth-utilization

Latest berth utilization snapshots.

Parameters

portstringPort slug

Response: { "berth_utilization": [...] }

GET

/api/v1/berth-utilization/weekly

Weekly berth utilization trends for a port.

Parameters

portstringrequiredPort slug

zone_idstringSpecific zone ID

weeksnumberDefault 12, max 52

Response: { "port", "port_name", "port_country", "weeks", "berth_utilization_weekly" }

Trade Routes

Trade flow analysis, route shifts, and destination deceptions.

GET

/api/v1/routes/flows

Trade route flows between ports with tonnage and market share.

Parameters

originstringOrigin port ID

destinationstringDestination port ID

weekstringWeek start date (ISO)

commoditystringCommodity filter

limitnumberDefault 100, max 500

Response: { "flows": [...] }

GET

/api/v1/routes/shifts

Detected trade route shifts and deviations.

Parameters

severitystring'moderate' | 'high' | 'critical'

originstringOrigin port ID

commoditystringCommodity filter

limitnumberDefault 100, max 500

Response: { "shifts": [...] }

GET

/api/v1/routes/deceptions

Vessels whose actual destination didn't match declared destination.

Parameters

vesselstringIMO number

suspiciousstring'true' | 'false'

actual_portstringActual port ID

limitnumberDefault 100, max 500

Response: { "deceptions": [...] }

Forecasts

Cargo volume forecasts and accuracy tracking.

GET

/api/v1/forecasts

Cargo volume forecasts by port and methodology.

Parameters

portstringPort slug

methodstring'pipeline' | 'statistical' | 'ml'

limitnumberDefault 50, max 200

Response: { "forecasts": [...] }

GET

/api/v1/forecasts/accuracy

Forecast accuracy metrics (MAE, MAPE, directional accuracy).

Parameters

portstringPort slug

methodstringForecast method

Response: { "accuracy": [...] }

GET

/api/v1/destination-reliability

Vessel destination declaration reliability scores.

Parameters

vesselstringIMO number

tierstring'reliable' | 'moderate' | 'unreliable'

limitnumberDefault 100, max 500

Response: { "reliability": [...] }

Earnings & Freight

Voyage earnings estimates and freight rate data.

GET

/api/v1/earnings

Per-voyage earnings estimates.

Parameters

vesselstringIMO number

portstringPort slug

limitnumberDefault 50, max 200

Response: { "earnings": [...] }

GET

/api/v1/earnings/port-revenue

Weekly port revenue aggregates.

Parameters

portstringPort slug

limitnumberDefault 52, max 200

Response: { "port_revenue": [...] }

GET

/api/v1/freight-rates

Freight rate data by vessel type.

Parameters

vessel_typestringVessel type filter

limitnumberDefault 50, max 200

Response: { "freight_rates": [...] }

POST

/api/v1/freight-ratesAUTH

Submit a new freight rate record.

Response: { "freight_rate": {...} }

Emissions

Scope 3 maritime emissions accounting and disclosure-ready exports.

GET

/api/v1/emissionsAUTH

Per-voyage and fleet-level CO2 estimates using ton-mile model with uncertainty bounds.

Parameters

imostringFilter by vessel IMO

portstringPort slug filter

startstringISO start timestamp

endstringISO end timestamp

fuel_typestring'vlsfo' | 'mgo' | 'lng' | 'methanol'

distance_nmnumberAssumed voyage distance (nautical miles)

speed_knotsnumberAssumed speed for intensity model

group_bystring'none' | 'imo' | 'port' | 'commodity'

formatstring'json' (default) or 'csv'

cursorstringCursor offset for pagination

limitnumberDefault 50, tier-clamped

Response: { "fleet": {...}, "grouped": [...], "voyages": [...], "pagination": {...} }

GET

/api/v1/emissions/reportAUTH

CSRD / SEC Scope 3 report export in JSON, CSV, or PDF format.

Parameters

entitystringReporting entity name

startstringISO start timestamp

endstringISO end timestamp

imostringFilter by vessel IMO

portstringPort slug filter

fuel_typestring'vlsfo' | 'mgo' | 'lng' | 'methanol'

distance_nmnumberAssumed voyage distance (nautical miles)

speed_knotsnumberAssumed speed for intensity model

formatstring'json' (default), 'csv', or 'pdf'

Response: { "report": {...}, "voyages": [...], "pagination": {...} } or CSV/PDF file

Fleet Age

Fleet age demographics and aging vessel risk.

GET

/api/v1/fleet-age

Fleet age statistics by port, including age buckets and risk percentages.

Parameters

portstringPort slug

vessel_typestringVessel type filter

Response: { "fleet_age": [...] }

GET

/api/v1/fleet-age/history

Weekly fleet age trends for a port.

Parameters

portstringrequiredPort slug

vessel_typestringVessel type filter

weeksnumberDefault 12, max 52

Response: { "port", "port_name", "weeks", "vessel_type", "history" }

Satellite Imagery

MODIS + Sentinel-2 NDVI crop health, yield estimates, and production forecasts.

GET

/api/v1/satellite/regions

All monitored crop regions with latest NDVI and health assessments.

Response: { "regions": [...] }

GET

/api/v1/satellite/health

Crop health assessments with NDVI deviation and yield estimates.

Parameters

regionstringRegion slug

statusstringHealth status filter

cropstringCrop type

limitnumberDefault 100, max 500

Response: { "assessments": [...] }

GET

/api/v1/satellite/production

Production forecasts linked to port export estimates.

Parameters

regionstringRegion slug

portstringPort slug

cropstringCrop type

limitnumberDefault 100, max 500

Response: { "forecasts": [...] }

LNG

LNG carrier tracking across 5 terminals.

GET

/api/v1/lng

LNG dashboard: carriers at terminals, 7-day volume estimates, departures.

Response: { "carriers_at_terminals", "estimated_volume_7d_tons", "departures_7d", "active_terminals", "total_terminals", "terminals" }

GET

/api/v1/lng/terminals

List all LNG terminals.

Response: { "terminals": [...] }

Mining

Mining terminal tracking: iron ore and coal across 8 terminals.

GET

/api/v1/mining

Mining dashboard: carriers, volumes, coal vs iron ore departures.

Response: { "carriers_at_terminals", "estimated_volume_7d_tons", "departures_7d", "coal_departures_7d", "iron_ore_departures_7d", "terminals" }

GET

/api/v1/mining/terminals

List all mining terminals.

Response: { "terminals": [...] }

P&I Coverage

Protection & Indemnity club coverage for vessels.

GET

/api/v1/pi-clubs

List all P&I clubs with risk tier and IG membership.

Response: { "clubs": [...] }

GET

/api/v1/pi-coverage

P&I coverage records for vessels.

Parameters

vesselstringIMO number

Response: { "coverage": [...] }

POST

/api/v1/pi-coverage/importAUTH

Bulk import P&I coverage from CSV.

Response: { "rows_processed", "matched", "unmatched_clubs" }

River Levels

Real-time USGS gauge data for waterways critical to grain barge transport.

GET

/api/v1/river-levelsAUTH

Live river water levels for Mississippi, Ohio, Illinois, Columbia rivers and Houston. Returns level in feet with status alerts (normal/low/critical/flood).

Response: { "readings": [{ "name", "river", "level_ft", "status", "critical_low_ft", "flood_stage_ft" }], "alerts": [...] }

SAR Satellite

Check Sentinel-1 radar satellite imagery coverage for dark fleet verification.

GET

/api/v1/sar-coverageAUTH

Query Copernicus Sentinel-1 SAR catalog to check if radar imagery exists near a location and time. Used to verify dark fleet events.

Parameters

latnumberrequiredLatitude

lngnumberrequiredLongitude

datestringISO date (default: now)

radiusnumberSearch radius in km (default 50)

Response: { "has_coverage", "products": [{ "name", "start", "size_mb" }], "closest_pass_hours", "verification_potential": "high|medium|low|none" }

Alerts

Platform alerts for sanctions matches, river level warnings, dark fleet events.

GET

/api/v1/alertsAUTH

Get active platform alerts. Filter by severity or type.

Parameters

severitystring'critical', 'warning', or 'info'

typestring'sanctions_match', 'river_level', 'dark_fleet'

unacknowledgedstring'true' to only show unread alerts

Response: { "alerts": [...], "count", "unacknowledged" }

GET

/api/v1/alerts/unifiedAUTH

Unified cross-product inbox combining maritime and Locus alerts in a single chronological feed.

Parameters

productstring'all' (default), 'overwatch', or 'locus'

severitystring'critical', 'warning', or 'info'

watchliststring'true' to only include watched vessels

portfoliostringLocus portfolio id filter

statestring'all' (default), 'open', 'read', 'resolved', 'snoozed'

cursorstringISO cursor for pagination

limitnumberDefault 25, max 100

Response: { "alerts": [...], "count", "pagination": { "has_more", "next_cursor" }, "filters": {...} }

POST

/api/v1/alerts/unified/stateAUTH

Set per-user state for a unified alert (read, resolve, snooze, reopen).

Parameters

alert_idstringrequiredAlert id in source:id format (e.g. dark_event:123)

actionstringrequired'read' | 'resolve' | 'snooze' | 'open'

snooze_untilstringISO timestamp (optional for snooze; defaults to +24h)

Response: { "ok": true, "alert_id", "action", "state": { "read_at", "resolved_at", "snoozed_until" } }

Disruptions

GDELT-sourced news signals about commodity trade disruptions.

GET

/api/v1/disruptionsAUTH

Real-time disruption signals from global news: port closures, sanctions, trade disputes, weather events, canal blockages.

Parameters

hoursnumberLookback window (default 24)

querystringTitle text filter

limitnumberMax results (default 20)

Response: { "signals": [{ "title", "url", "source_name", "published_at", "tone" }], "count", "timespan_hours" }

Market Data

Commodity prices, USDA transport data, and seasonal anomalies.

GET

/api/v1/commodity-prices

World Bank commodity benchmark prices (wheat, corn, oil, iron ore, LNG, etc.).

Parameters

commoditystringe.g. 'wheat', 'crude_oil_brent', 'iron_ore'

sincestringISO date

limitnumberDefault 100, max 500

Response: { "commodity_prices": [...] }

GET

/api/v1/transport-data

USDA Grain Transportation Report data: barge, rail, and truck volumes.

Parameters

modestring'barge' | 'rail' | 'truck'

commoditystringCommodity filter

regionstringOrigin region (fuzzy match)

sincestringISO date

limitnumberDefault 100, max 500

Response: { "transport_data": [...] }

GET

/api/v1/anomalies

Seasonal and trailing anomalies in export volumes.

Parameters

portstringPort ID

typestring'trailing' | 'yoy' | 'seasonal_avg' | 'seasonal_range'

severitystring'moderate' | 'high' | 'critical'

limitnumberDefault 100, max 500

Response: { "anomalies": [...] }

GET

/api/v1/anomalies/maturity

Seasonal analysis maturity levels per port (data sufficiency).

Response: { "maturity": [...] }

GET

/api/v1/calibration

Volume estimation calibration data (per-vessel-type and self-calibrated).

Response: { "calibration", "overrides", "self_calibrated", "manual_overrides" }

Trade Flows

Bilateral commodity trade data from UN Comtrade, mirror data discrepancy detection, entity resolution, and sanctions cross-referencing.

GET

/api/v1/trade-flowsAUTH

Bilateral trade flow data. Use ?view param for different analyses.

Parameters

viewstring'flows' (default) | 'mirror' | 'sanctions' | 'entity'

exporterstringExporter country name filter

importerstringImporter country name filter

commoditystringCommodity name filter (e.g. Wheat, Soybeans)

periodstringYear filter (e.g. '2024')

limitnumberMax results (default 50)

Response: { "flows": [...] } or { "discrepancies": [...] } or { "matches": [...] } or { "entities": [...] }

GET

/api/v1/trade-flows?view=mirror

Mirror data discrepancies: exporter-reported vs importer-reported volumes for the same commodity/country pair. Large discrepancies signal trade re-routing or misclassification.

Response: { "discrepancies": [{ "exporter_name", "importer_name", "commodity_name", "exported_mt", "imported_mt", "discrepancy_pct", "status" }] }

GET

/api/v1/trade-flows?view=sanctions

Vessels matched against OFAC sanctions list via IMO, MMSI, or name-based entity resolution.

Response: { "matches": [{ "imo_number", "vessel_name", "sanctioned_entity", "list_source", "match_type" }], "match_types": { "direct_imo", "mmsi", "name" } }

GET

/api/v1/trade-flows?view=entity

Supply chain entity graph: vessels linked to owners, ports, sanctions, P&I coverage, and dark fleet history.

Parameters

imostringFilter by IMO number

Response: { "entities": [{ "imo_number", "vessel_name", "port_name", "is_sanctioned", "dark_event_count", "risk_score" }] }

Data Export

Download data as CSV files.

GET

/api/v1/export

Export visits or estimates as CSV. Authenticated users get higher limits.

Parameters

portstringPort slug

typestring'visits' | 'estimates' (default: visits)

limitnumberDefault 100, max 10000 with auth

Response: CSV file (Content-Type: text/csv)

Webhooks

Subscribe to real-time event notifications.

GET

/api/v1/webhooksAUTH

List your registered webhooks.

Response: { "webhooks": [...] }

POST

/api/v1/webhooksAUTH

Response: { "webhook": {...} }

POST

/api/v1/webhooks/slack-testAUTH

Send a test notification to a Slack webhook URL.

Response: { "success", "message" }

Admin & Billing

API key management, billing, and subscription plans.

GET

/api/v1/keysAUTH

List your API keys.

Response: { "keys": [...] }

POST

/api/v1/keysAUTH

Create a new API key.

Response: { "api_key", "warning" }

GET

/api/v1/billing/plans

List available subscription plans with pricing and features.

Response: { "plans": [...] }

GET

/api/v1/billing/entitlementsAUTH

Resolve current user entitlements across Overwatch and Locus products.

Response: { "entitlements": { "plan", "product", "hasBundle", "canAccessOverwatch", "canAccessLocus" } }

POST

/api/v1/billing/checkoutAUTH

Create a Stripe checkout session for a subscription plan.

Response: { "url" }

SDKs & MCP

Client libraries and AI agent integration.

Python SDK

pip install axiom-overwatch

from axiom_overwatch import AxiomClient

client = AxiomClient(api_key="your-key")
positions = client.positions(port="santos")
df = client.to_dataframe(positions)

MCP Server (AI Agents)

Give Claude, GPT, or any MCP-compatible AI agent access to maritime intelligence.

AXIOM_API_KEY=your-key npx @axiom/mcp-server

12 tools: vessel positions, export estimates, congestion, risk scores, dark fleet events, trade flows, mirror discrepancies, sanctions, commodity prices, forecasts, ports, crop health.

Pricing

All plans include access to every endpoint. Tiers differ in volume, history depth, and features.

Free

$0/mo

50 requests / day
20 results per call
7 days of history
Port-level data only (no exact coordinates)
No CSV export
No webhooks

Popular

Starter

$49/mo

1,000 requests / day
100 results per call
90 days of history
Full coordinates (lat/lon)
CSV export
No webhooks

Pro

$199/mo

10,000 requests / day
500 results per call
Full history (unlimited)
Full coordinates (lat/lon)
CSV export (up to 10k rows)
Real-time webhooks
Priority support

Flagship

Supply Chain Risk

$499/mo

Unified Overwatch + Locus entitlement
Cross-domain product access (single account)
Single Stripe subscription and invoice
Priority implementation support

Enterprise? Need higher limits, custom SLAs, or dedicated support? Contact us.