docs/maritime-intelligence.mdx

Rama main · réplica de lectura del repositorio original.

---
title: "Maritime Intelligence"
description: "Real-time vessel tracking with chokepoint monitoring, traffic density analysis, dark ship detection, and WebSocket-based AIS data streaming."
---
The Ships layer provides real-time vessel tracking and maritime domain awareness through AIS (Automatic Identification System) data, monitoring critical chokepoints, detecting anomalous vessel behavior, and streaming position updates over WebSocket connections.

## UKMTO incident reports

Enable **UKMTO Incidents** in the panel settings to read
reports from [UK Maritime Trade Operations](https://www.ukmto.org/recent-incidents).
Select an incident heading to center the map on its reported position. The Ships
layer in the full dashboard also shows UKMTO positions in the flat and globe maps.

The panel preserves the publisher's incident type, narrative and incident time.
These are attributed reports, which can remain under investigation. They do not
change AIS availability, NGA warnings or risk scores. WorldMonitor's DeckGL
markers distinguish fresh and stale snapshots; the globe markers do not use that
color distinction. The map status reports UKMTO availability separately from
AIS, including empty and unavailable results.

The collector polls every 30 minutes, matching the source's refresh interval. A
snapshot becomes stale after 75 minutes without a successful retrieval and is
unavailable after 24 hours. An empty successful response is shown separately
from unavailable data. The panel shows the retrieval time in UTC, independently
of the incident time.

API clients can read `GET /api/maritime/v1/list-ukmto-incidents`. The dashboard uses
the on-demand `ukmtoIncidents` bootstrap key. Both read the same validated cache. The RPC is not CDN-cached, so availability
and freshness are recomputed on each request. Its full contract is in the
MaritimeService OpenAPI spec and YAML bundle; it is omitted from the compact
scanner JSON to keep that artifact within its byte limit.
UKMTO's own website backend blocks automated clients, so the reports are
collected from the documented public API of
[hormuz.data-tracking.net](https://hormuz.data-tracking.net/api-docs), which
republishes them. That table has no publication time, so the panel shows only
the incident time. A report the republisher lists twice at the same time and
position is shown once, under its UKMTO number. The republished table is
licensed under CC BY 4.0. See [UKMTO's terms](https://www.ukmto.org/terms-and-conditions),
sections 20–23, for reuse provisions. Contains public sector information
licensed under the Open Government Licence v3.0.

## Route Explorer

Route Explorer is the keyboard-first workflow for planning a shipment between any two countries and seeing chokepoint exposure, bypass corridors, land alternatives, and per-country impact — all on top of this maritime layer. See the dedicated [Route Explorer](/route-explorer) page for the full workflow, tab contents, keyboard bindings, and tier gating.

## Chokepoint Monitoring

The system monitors the canonical strategic-waterway registry for disruptions that could affect global trade. It uses IMF PortWatch for weekly vessel transit counts, AISStream for the real-time crossing counter, and CorridorRisk for risk intelligence.

| Chokepoint | Strategic Importance |
|------------|---------------------|
| **Strait of Hormuz** | 20% of global oil transits; Iran control |
| **Suez Canal** | Europe-Asia shipping; single point of failure |
| **Strait of Malacca** | Primary Asia-Pacific oil route |
| **Bab el-Mandeb** | Red Sea access; Yemen/Houthi activity |
| **Panama Canal** | Americas east-west transit |
| **Taiwan Strait** | Semiconductor supply chain; PLA activity |
| **Cape of Good Hope** | Suez bypass route for VLCCs |
| **Strait of Gibraltar** | Atlantic-Mediterranean gateway; NATO chokepoint |
| **Bosporus Strait** | Black Sea access; includes Dardanelles corridor; Montreux Convention |
| **Korea Strait** | Japan-Korea trade; busiest East Asia corridor |
| **Dover Strait** | World's busiest shipping lane |
| **Kerch Strait** | Russia-controlled; Ukraine grain via Azov restricted |
| **Lombok Strait** | Malacca bypass for large tankers |

Each chokepoint card shows real-time transit counts (tanker vs cargo), week-over-week change, and an expandable 180-day time-series chart rendered with TradingView lightweight-charts.

## Density Analysis

Vessel positions are aggregated into a 2-degree grid to calculate traffic density. Each cell tracks:

- Current vessel count
- Historical baseline (30-minute rolling window)
- Change percentage from baseline

Density changes of +/-30% trigger alerts, indicating potential congestion, diversions, or blockades.

## Dark Ship Detection

The system monitors for AIS gaps, vessels that stop transmitting their position. An AIS gap exceeding 60 minutes in monitored regions may indicate:

- Sanctions evasion (ship-to-ship transfers)
- Illegal fishing
- Military activity
- Equipment failure

Vessels reappearing after gaps are flagged for the duration of the session.

### Backed by endpoints

| Surface | Endpoint | Notes |
|---|---|---|
| Vessel snapshot | `GET /api/maritime/v1/get-vessel-snapshot` | Civilian AIS point-in-time view for traffic and disruption context. |
| Navigational warnings | `GET /api/maritime/v1/list-navigational-warnings` | NGA maritime safety warnings used by chokepoint and undersea-cable awareness. |
| IMD sea / coastal | Bootstrap `imdCycloneMarine` (`weather:imd-cyclone-marine:v1`) | Official IMD sea-area and coastal bulletins from the public mausam.imd.gov.in pages, with issuing ACWC/CWC, valid times, storm warning, port signal, storm surge, wind, visibility, and sea state. Not merged into NWS weather alerts. Port warning and fishermen warning PDFs stay disabled. |

## WebSocket Architecture

AIS data flows through a WebSocket relay for real-time updates without polling:

```
AISStream -> WebSocket Relay -> Browser
              (ws://relay)
```

The connection automatically reconnects on disconnection with a 30-second backoff. When the Ships layer is disabled, the WebSocket disconnects to conserve resources.

## Railway Relay Architecture

Some APIs block requests from cloud providers (Vercel, AWS, Cloudflare Workers). A [Railway relay server](/relay-parameters) provides authenticated access:

```
Browser -> Railway Relay -> External APIs
           (Node.js)      (AIS, OpenSky, RSS)
```

**Relay Functions**:

| Endpoint | Purpose | Authentication |
|----------|---------|----------------|
| `/` (WebSocket) | AIS vessel stream | AISStream API key |
| `/opensky` | Military aircraft | OAuth2 Bearer token |
| `/rss` | Blocked RSS feeds | None (user-agent spoofing) |
| `/health` | Status check | None |

**Environment Variables** (Railway):

- `AISSTREAM_API_KEY` - AIS data access
- `OPENSKY_CLIENT_ID` - OAuth2 client ID
- `OPENSKY_CLIENT_SECRET` - OAuth2 client secret

**Why Railway?**

- Residential IP ranges (not blocked like cloud providers)
- WebSocket support for persistent connections
- Global edge deployment for low latency
- Free tier sufficient for moderate traffic

The relay is stateless; it simply authenticates and proxies requests. All caching and processing happens client-side or in Vercel Edge Functions.

See also [Finance Data - Chokepoints](/finance-data) for disruption scoring methodology.