Know what is on your shipping lane before your ship does.
Live maritime risk intelligence for shipping companies. Vantage watches the world's sea lanes on a 3D globe, detects threats to a shipment from free live data, ranks them by what they cost this voyage, and replans a feasible, safer route with a plain-English explanation.
Live demo · Product · Design · Model and backtest · Results · Data · Slides
The problem
A single closed chokepoint can add weeks and hundreds of thousands of dollars to a voyage. The signals that warn of it are scattered across the open web, and by the time a team has read them all, the ship has already sailed.
- The signals are scattered. Transit counts, security news, storm alerts and wave forecasts each live on a different site, in a different format.
- Most of them are noise. A headline about land fighting is not a threat to shipping. A human has to tell the difference, every time.
- Risk is not the same for every voyage. A hazard matters only if it sits near this route, on the day this ship gets there.
- A warning is not a plan. Knowing a zone is dangerous does not tell you which sailable route avoids it, or what the detour costs.
The data is free and public. What is missing is something that reads it, scores it against a specific voyage, and hands back a route.
What Vantage does
| Step | What it means |
|---|
| 01 Detect | Pulls live hazards from free feeds: chokepoint traffic, security news, cyclones, quakes, volcanoes, storms, icebergs and wave forecasts. |
| 02 Predict | A trained, calibrated model estimates the chance a chokepoint's traffic collapses in the next 14 days. |
| 03 Categorize | Gemini reads each zone's headlines and data and returns a category, severity, confidence and rationale. Land-only fighting is dismissed as a false alarm. |
| 04 Prioritize | Each hazard is scored by urgency, business impact in USD, risk and confidence, against the actual route. |
| 05 Decide | Proceed, sail to a checkpoint and reassess, or reroute. |
| 06 Explain | Plain-English reasoning: why the original route is risky, why a backup is needed, and how it averts the risk. |
How it works
flowchart LR
A["Live APIs<br/>PortWatch · News · GDACS<br/>EONET · Open-Meteo · AIS"] --> B["Detect<br/>hazard zones"]
B --> C["Gemini<br/>categorize and score"]
C --> D["Route exposure<br/>and cost"]
D --> E["Gemini<br/>what to avoid"]
E --> F["Sea-lane router<br/>build and validate"]
F --> G["Gemini<br/>explain the decision"]
M["Trained model<br/>14-day collapse risk"] --> C
- Detect (
lib/sources.ts, lib/signals.ts): IMF PortWatch chokepoint transits (7-day against a 90-day baseline), maritime-security news for 12 watch zones (Google News RSS, GDELT), GDACS cyclone, quake and volcano alerts, NASA EONET storms and icebergs, and Open-Meteo wave forecasts for the day the ship arrives.
- Categorize (
lib/signals.ts): Gemini reads each zone's headlines and traffic data and returns a category (armed conflict, piracy, military tension, congestion and so on), a severity, a confidence and a rationale. Commentary and land-only fighting are marked as not a threat to shipping, which keeps false alarms down.
- Prioritize (
lib/planner.ts): every hazard near the route gets an exposure (score × proximity, discounted for storms far ahead). Risk index, war-risk premium, voyage cost and expected disruption cost are computed per route.
- Replan (
lib/planner.ts, lib/seagraph.ts): Dijkstra on the Eurostat MARNET sea-lane network produces three routes: original (shortest), safest (blocks high-risk zones) and balanced (soft penalty). It also builds a checkpoint plan: sail the short route to a staging port before the first hazard, reassess with fresh data, then continue or divert. Gemini chooses the decision, the hazards to avoid and optional waypoints. The router builds that path and rejects it if it is not sailable or still crosses an avoided hazard.
- Explain: Gemini writes the decision, the trade-offs and the reasoning using only computed numbers. Without an API key, rule-based reasoning fills in.
The language model never gets the last word
flowchart TB
LLM["Gemini proposes<br/>decision · hazards to avoid · waypoints"] --> V{"Router validates"}
V -->|"sailable and avoids every hazard"| OK["Route accepted"]
V -->|"not sailable, or still crosses a hazard"| R["Rejected, rule-based fallback"]
Prioritization is computed, not generated: urgency × business impact in USD × risk × confidence. The model supplies reasoning text and route proposals, and the sea-lane router checks every proposal before it reaches the screen.
The product
A globe that shows the work
Vantage runs on a CesiumJS globe with selectable imagery (Esri Dark Gray, OpenStreetMap, Esri World Imagery). Watch zones, hazards, the original route and the backup route are drawn on it. The planner streams a visible Detect, Predict, Categorize, Prioritize, Decide, Explain pipeline so the reasoning is on screen as it happens.
Simulate a strike
Click anywhere on the globe to drop a missile strike on shipping and watch the plan change. It is the fastest way to see how the planner reacts to a new hazard.
Confidence on every hazard
Each hazard carries a confidence score (0 to 100%) built from source agreement, data freshness, model and AI certainty, and a missing-data penalty, with a one-line reason.
Honest about its data
The Data sources tab shows which feeds are live, which are running on a bundled last-good snapshot, and which are down. It also lists the signals that were dismissed as false alarms, and why.
Live ships (optional)
With a free AISSTREAM_API_KEY, the server samples AISStream for a few seconds around the watch zones, draws ships on the globe, and flags congestion, speed drops, scattered courses and AIS gaps as anomalies that raise the zone's hazard score. Vercel functions cannot hold a socket open, so this is a short sample per request, not a persistent stream.
Trained prediction model, with proof
Beyond live signals, Vantage runs a trained, calibrated model that estimates the chance a chokepoint's traffic collapses within the next 14 days, plus a 7-day forecast with a prediction interval.
- Trained and backtested on 7.7 years of IMF PortWatch transits plus weekly news volume.
- Walk-forward evaluation with no future leakage.
- Evaluated in TypeScript on Vercel. No Python at runtime.
- Compared against a naive rule and against the scoring the app shipped with before.
| 14-day horizon, 23 events | False-alarm rate | False alert episodes per chokepoint-year | Events warned before traffic fell | Median lead |
|---|
| Vantage | 2.9% | 0.95 | 11 / 23 | +10 d |
| Previous app scoring | 3.8% | 1.82 | 10 / 23 | +0.5 d |
| Naive drop > 15% | 6.4% | 2.83 | 10 / 23 | -1 d |
This is a modest, honestly measured gain on a rare-event problem, including where it did not help. In the Red Sea case the transit model alerted only as carriers reacted, while the news layer was four weeks earlier. That is why Vantage uses both.
Method, data, caveats and the Red Sea case study: ml/README.md, ml/RESULTS.md, data/README.md. Charts are in slides/.
Why this approach
- Free data only. Every signal comes from a public source, so anyone can run it without a data contract.
- Computed first, generated second. Risk, cost and priority are numbers. The language model explains them and proposes routes, and never invents them.
- Every route is validated. A proposed path must be sailable on the real sea-lane network and must avoid every hazard it claims to avoid, or it is rejected.
- It degrades gracefully. No Gemini key means rule-based reasoning. A feed goes down and the app uses its last-good snapshot and says so.
- It reports where it fails. The backtest includes the cases the model got wrong.
Architecture
flowchart TB
U["Browser<br/>CesiumJS globe"]
subgraph vercel ["Vercel"]
N["Next.js app<br/>app/ · components/"]
API["API routes<br/>lib/sources · signals · planner · seagraph · model"]
end
subgraph feeds ["Free live feeds"]
PW["IMF PortWatch"]
NW["Google News RSS · GDELT"]
GD["GDACS"]
EO["NASA EONET"]
OM["Open-Meteo Marine"]
AIS["AISStream.io (optional)"]
end
GM["Google Gemini"]
SG["Eurostat MARNET<br/>sea-lane graph"]
ML["ml/ and data/<br/>offline training and backtest"]
U --> N --> API
API --> PW & NW & GD & EO & OM & AIS
API --> GM
API --> SG
ML -.->|"trained weights"| API
| Path | What it is |
|---|
app/ | Next.js routes and API handlers. |
components/ | The globe, the planner panel and the data-sources tab. |
lib/ | Detection, categorization, route planning, the sea-lane graph and the model runtime. |
ml/ | Training and backtest code, written in Python. See ml/README.md. |
data/ | Training data and its documentation. |
scripts/ | Build scripts, including build-searoute-graph.mjs. |
slides/ | Charts and slides from the backtest. |
public/ | Static assets. |
Quick start
You need Node.js and npm. A free Gemini API key is recommended, and a free AISStream key is optional.
cp .env.example .env.local # add GEMINI_API_KEY and, optionally, AISSTREAM_API_KEY
npm install
npm run dev
Open http://localhost:3000.
Checks
npx eslint .
npx tsc --noEmit
npm run build
npx tsx lib/model.test.ts # Python and TypeScript parity
Retrain and re-run the backtest
pip install -r ml/requirements.txt
python ml/run_all.py --skip-news
Configuration
| Variable | Required | Where to get it |
|---|
GEMINI_API_KEY | Recommended. The app falls back to rule-based reasoning without it. | https://aistudio.google.com/apikey |
AISSTREAM_API_KEY | Optional. No live ships or AIS anomalies without it. | https://aisstream.io (free) |
GEMINI_MODEL | Optional. Overrides the default model order. | n/a |
Deploy
Push to GitHub and import the repo into Vercel. Set the variables above for Production and Preview (Project, Settings, Environment Variables).
Turn off Deployment Protection for Production so the public link opens logged out (Settings, Deployment Protection).
Data sources
All of them are free.
| Signal | Source |
|---|
| Chokepoint transits (live and training) | IMF PortWatch (ArcGIS REST) |
| Conflict, piracy, military news | Google News RSS, GDELT 2.0 DOC API |
| Cyclones, earthquakes, volcanoes | GDACS |
| Storms, icebergs | NASA EONET |
| Wave forecast | Open-Meteo Marine |
| Live ships (optional) | AISStream.io |
| Sea-lane network | Eurostat MARNET via searoute-js, built by scripts/build-searoute-graph.mjs |
| Globe imagery | Esri Dark Gray, OpenStreetMap, Esri World Imagery |
| Reasoning | Google Gemini (free tier) |
Docs
Limitations
- The prediction model is evaluated on 23 events. That is enough to show a direction, not to claim a guarantee.
- Live AIS is a short sample per request, not a continuous feed.
- Route planning is limited to the MARNET sea-lane network, so very local navigation is out of scope.
- News-based signals depend on what the free feeds publish and when.
