Vessels — Enrichment & Watchlist

Per-vessel identity/IUU-risk enrichment and the operator-curated bad-actor watchlist.

The vessels API attaches two operator-facing layers on top of live AIS:

Enrichment — persistent identity (flag, owner, vessel class), recent activity summary, and a derived IUU-risk score for any MMSI in the live snapshot.
Watchlist — an operator-curated list of bad-actor vessels with full event-history dossiers (anchor-drag CUI events, sanctions hits, AIS spoofing patterns).

Both are cached and conditional: enrichment is only served when the enrichment DB is configured (TRAILBASE_REFERENCE_DB / ENRICHMENT_DB_PATH); the watchlist is always available but may be empty.

Routes

Method	Path	Purpose
`GET`	`/vessels/{mmsi}/enrichment`	Identity + IUU-risk dossier for one vessel.
`GET`	`/vessels/{mmsi}/watchlist`	Full dossier for one watchlisted MMSI.
`GET`	`/watchlist`	Summary rows for every watchlisted vessel.

`/vessels/{mmsi}/enrichment`

Returns the persistent identity and recent activity for one MMSI, plus a derived IUU-risk score:

{
  "mmsi": "636019825",
  "name": "EXAMPLE",
  "flag": "LR",
  "vesselType": "tanker",
  "lengthM": 230,
  "owner": { "name": "…", "country": "…" },
  "recentActivity": {
    "portCalls7d": 0,
    "darkPeriods7d": 2,
    "transshipmentCandidates7d": 1
  },
  "iuuRisk": { "score": 0.72, "tier": "high", "drivers": ["dark-period", "flag-of-convenience"] }
}

Returns 404 when enrichment is disabled or the MMSI has no record.

/watchlist

Summary rows — what the operator watchlist panel renders:

[
  {
    "mmsi": "636019825",
    "name": "EXAMPLE",
    "categories": ["anchor-drag-CUI", "ais-spoofing"],
    "riskScore": 0.81,
    "lastSeen": { "ts": "2026-05-27T11:43:00Z", "lat": 36.1, "lon": 32.4 }
  }
]

Full dossier for one watchlisted MMSI: event history (each event timestamped, geolocated, and tagged with categories), current risk score, category tags, and any operator notes. Returns 404 when the MMSI is not on the watchlist.

CUI anchor-drag detection

The adapter runs a background detector over AIS track history that flags anchor-drag patterns near critical underwater infrastructure (CUI). Detected events are appended to the vessel's watchlist dossier and surfaced through /alerts?layers=ais&types=anomaly.

Status

All three routes live on the deployed system.