Forem: VesselAPI

Every Ship Has a Secret Resume

VesselAPI — Sat, 04 Apr 2026 22:27:01 +0000

In 2011, a Japanese shipyard delivered a bulk carrier called 21 Glory. She was 37,000 deadweight tonnes — a handymax, built to carry grain, coal, and steel through the regional trade lanes of the Pacific.

Stamped into her classification record was this:

NS*(BCM-A, BC-XII, GRAB)(PS-DA&FA)(IWS) MNS*

That is not a random string. It is a professional credential — a coded statement, issued by a classification society, that specifies what this ship is built to do, what she has been inspected for, and what she is permitted to carry.

Lloyd's Register began recording ship conditions in a London coffee house in 1760. The core concept has not changed: independent examination, encoded into standardized formats. The notation string is the output.

Reading the Notation

Here is what 21 Glory's notation means, token by token:

Token	Meaning
`NS*`	Hull notation by ClassNK; asterisk indicates approved plans and surveyed construction
`BCM-A`	Bulk carrier strengthened for heavy cargo in all holds with alternate loading approval
`BC-XII`	SOLAS Chapter XII bulk carrier structural compliance
`GRAB`	Hull reinforced for grab (mechanical clamshell) discharge
`PS-DA&FA`	Structural strength program using Direct Analysis and Fatigue Assessment
`IWS`	In-Water Survey eligibility — divers instead of dry-dock
`MNS*`	Machinery notation with full-survey standard

A vessel without BCM-A would be unsuitable for iron ore with alternating empty holds.

The GRAB notation deserves special attention. Grab discharge means a crane lowers a massive clamshell bucket into the hold and scoops cargo out. The impact on the tank top — the hull interior — is enormous. Vessels rated for grab discharge have reinforced scantlings: thicker plating, stronger frames, additional stiffening. A vessel without this reinforcement risks structural damage during or after grab operations.

The Rosetta Stone Problem

There is no universal notation language. Each classification society invented its own.

There are approximately a dozen major societies worldwide (IACS members), and they encode identical capabilities differently:

Bulk carrier heavy cargo: BCM-A (ClassNK) vs BC-A (Bureau Veritas, CCS, Korean Register)
Unattended machinery: M0 (ClassNK), AUT-UMS (Bureau Veritas), AUT-0 (CCS), UMA (Korean Register)

Korean Register wraps notations in single quotes. CCS uses Unicode parentheses. One Bureau Veritas vessel had a notation string that was 847 characters long — with occasional full-width Unicode parentheses mixed in.

Our first attempt at a cross-society parser took about a day to write and about three weeks to debug.

Classification societies predate international standardization bodies by over a century. Lloyd's Register predated the first International Load Line Convention (1930) by 170 years. By the time anyone thought about harmonization, the notation formats were embedded in thousands of certificates, contracts, and insurance policies. Only Common Structural Rules (adopted 2006, harmonized 2015) achieved genuine cross-society alignment — which is why CSR appears nearly identically across societies.

What We Built

We built collectors for six classification societies, parsing notation strings without normalization. The rationale: the notation string is a legal document, and paraphrasing a legal document is how you get sued.

curl "https://api.vesselapi.com/v1/vessel/9468217/classification?filter.idType=imo" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "classification": {
    "identification": {
      "vesselName": "21 GLORY",
      "imoNumber": "9468217",
      "flagName": "Singapore",
      "classStatusString": "In Class"
    },
    "classification": {
      "mainClass": "NS*",
      "classNotationString": "NS*(BCM-A, BC-XII, GRAB)(PS-DA&FA)(IWS) MNS*"
    },
    "surveys": [
      { "survey": "Special Survey", "lastDate": "21 Jan 2026", "dueFrom": "14 Sep 2030", "dueTo": null },
      { "survey": "Intermediate Survey", "dueFrom": "14 Jun 2027", "dueTo": "14 Dec 2027" },
      { "survey": "Annual Survey", "dueFrom": "14 Jun 2026", "dueTo": "14 Dec 2026" }
    ],
    "yard": {
      "hullYardName": "SAIKI HEAVY INDUSTRIES CO., LTD.",
      "keelDate": "10 Dec 2010",
      "dateOfBuild": "22 Apr 2011"
    },
    "dimensions": {
      "dwt": 37202,
      "grossTon69": 22863
    }
  }
}

Coverage

Classification Society	Vessels with Notation Data
Nippon Kaiji Kyokai (ClassNK)	~8,900
Det Norske Veritas (DNV)	~8,300
Bureau Veritas (BV)	~7,500
China Classification Society (CCS)	~4,000
Registro Italiano Navale (RINA)	~2,800
Korean Register (KR)	~1,900
Total	~33,400

Not all vessels carry additional notations; some older or simpler ships have only base class symbols.

What the Notation String Decides

Cargo Suitability. The notation determines cargo compatibility. For iron ore shipments, charterers verify for BC-A (or equivalent) and GRAB. A BC-B vessel has restrictions on hold usage and draught, affecting loading patterns and structural safety. Getting this wrong is not a paperwork problem. It is a the-ship-might-break problem.

Survey Cycles. 21 Glory's record shows a Special Survey completed January 21, 2026, with the next due by September 2030. The Special Survey is the big one — a comprehensive inspection every five years, often requiring dry-docking, costing hundreds of thousands of dollars. Vessels near their deadline face potential delays, detention risk, or class loss if certification lapses.

Compliance Signals. Notations like PSPC-WBT (ballast tank protective coatings) and IHM (Inventory of Hazardous Materials) signal IMO convention compliance. In some ports, missing an expected notation is functionally an invitation to be boarded and detained by port state control.

Operational Quality Proxy. Notations including ESP (Enhanced Survey Programme), IWS, and CMS (Continuous Machinery Survey) correlate with better maintenance. They are a useful filter when screening numerous vessel candidates — not definitive proof of quality, but a signal.

Try It

The endpoint is at /vessel/{id}/classification?filter.idType=imo. Lloyd's Register and ABS are on the roadmap.

Somewhere right now, a surveyor is climbing into a ballast tank with a flashlight and an ultrasonic thickness gauge, measuring the steel plate by plate, writing down what she finds. The notation string is the output. We just make it queryable.

Crude Oil on the Water: Tracking Tanker Flows with Claude and a Maritime API

VesselAPI — Sun, 22 Mar 2026 22:25:03 +0000

Just after midnight UTC today, a 274-metre crude oil tanker called ALTURA slipped out of Novorossiysk, Russia's largest Black Sea crude export terminal. She's flagged to Sierra Leone at the time of this query, which tells you nothing about where she was built and almost nothing about who owns her. (Shadow fleet vessels re-flag frequently. ALTURA has had at least three names and flags since 2023.) At 163,750 deadweight tonnes, she's a Suezmax, designed to transit the Suez Canal fully loaded, carrying up to around a million barrels of crude. Right now she's somewhere south of Novorossiysk, heading for the Turkish Straits.

You probably don't care about any of that. Unless you trade oil.

If you do, that departure is a data point -- one of nine tankers that left Novorossiysk today alone, ranging from Suezmax crude carriers down to small coastal chemical tankers. Multiply by Primorsk, Ust-Luga, Al Jubail, and the rest of the world's export terminals, and you get the global crude supply picture: not a number in a spreadsheet, but a fleet of ships you can actually watch move.

The firms that turn this into a product -- Kpler, Vortexa, Windward -- charge serious money for it. They should; their platforms layer satellite imagery, cargo manifests, and proprietary models on top of the raw vessel data. But the raw vessel data itself? That part is more accessible than you might think.

The Oil Is on the Water

Here's the thing about seaborne crude: unlike a pipeline, it's visible.

Every tanker over 300 gross tonnes carries an AIS transponder -- a radio beacon that broadcasts position and speed every few seconds when underway, along with identity and destination data at longer intervals. Originally designed to prevent collisions, AIS has become the accidental backbone of commodity intelligence. If a VLCC loads crude at Ras Tanura and sets course for Ningbo, you can see it happen.

The signals that matter to a commodity desk are straightforward:

Departures from export terminals -- Novorossiysk, Ust-Luga, Primorsk (Russia), Al Jubail, Ras Tanura (Saudi Arabia), Basra (Iraq). Each departure is supply entering the water.

Arrivals at refinery ports -- Rotterdam, Singapore, Ningbo, Houston. Each arrival is supply being consumed.

Vessels in transit -- who's heading where, when they'll arrive, how deep they're sitting in the water. A tanker's draught is a rough proxy for how much cargo she's carrying.

The vessel herself -- flag state, owner, classification society, inspection record. These details separate the compliant fleet from the "shadow fleet" that moves sanctioned barrels.

None of this is secret. It's just scattered across different systems and formats. The trick is querying it conversationally instead of writing integration code.

The Setup

MCP (Model Context Protocol) lets an AI model call external APIs during a conversation -- so it retrieves live data rather than guessing from training data. VesselAPI provides the maritime data: AIS positions, port events, EU MRV emissions, port state inspections, and vessel registry information, wrapped in an MCP server.

Add this to your project root as .mcp.json (requires Node.js 18+):

{
  "mcpServers": {
    "vesselapi": {
      "command": "npx",
      "args": ["-y", "vesselapi-mcp"],
      "env": {
        "VESSELAPI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Sign up at vesselapi.com for a free API key. The JSON structure is the same across MCP clients -- file location varies (Cursor reads .mcp.json from the project root; Claude Desktop uses its own settings path). That's the entire setup.

Watching the Black Sea

I asked Claude: "What tankers departed Novorossiysk today?"

The model called list_port_events with the port's UN/LOCODE (RUNVS) and a departure filter. The raw results included everything: tankers, bulk carriers loading grain, tugs, service vessels. Novorossiysk isn't just an oil port. I had to call get_vessel on each result to check the type, then filtered to tankers:

Vessel	IMO	Type	Flag	Size
ALTURA	9292199	Crude Oil Tanker	Sierra Leone	274m, 163,750 DWT
ANTARCTICA	9910492	Oil Tanker	Liberia	274m x 50m
NISSOS SIKINOS	9884033	Tanker	Marshall Islands	274m x 48m
TATIANA	9340128	Oil/Chemical Tanker	Liberia	183m, 38,396 DWT
ENERGY DIONE	9995973	Tanker	United Kingdom	274m x 48m

Three Suezmax-class vessels in a single day from one port. Look at the flags: Sierra Leone, Liberia, Marshall Islands, Liberia, United Kingdom. Four of five are registered to open registries -- countries with no meaningful connection to the cargo, the crew, or the route. That pattern has a name in the industry: flag of convenience. And when you see it concentrated at an oil terminal under sanctions pressure, it gets more specific: shadow fleet. Only ENERGY DIONE flies a flag you'd expect from a vessel operating in compliant trade.

I picked ANTARCTICA and asked: "Tell me everything about this vessel."

The model pulled get_vessel:

Type: Oil tanker
Flag: Liberia
Length: 274m, Beam: 50m
Home port: Monrovia

Those are Suezmax dimensions. She's big enough to matter.

Then: "What are her emissions?"

The model called get_vessel_emissions and returned her EU MRV data:

2024: 3,382 tonnes CO2, 1,084 tonnes fuel consumed, 993 hours at sea
2023: 7,616 tonnes CO2, 2,431 tonnes fuel consumed, 1,686 hours at sea
Technical efficiency: 2.57 gCO2/t.nm

Her 2024 emissions dropped by more than half. Not because she got cleaner -- because she spent half as much time at sea. That's consistent with a vessel that spent part of the year in floating storage or waiting for cargo. My guess is sanctions-related delays, but oversupply looks the same from the outside. Either way, a tanker that suddenly halves its sea time is a signal worth flagging.

"Where is she right now?"

get_vessel_position returned:

Position: 44.71 degreesN, 37.85 degreesE
Speed: 6.6 knots, course 200.6 degrees

She's in the Black Sea, heading south-southwest for the Bosphorus. If she's carrying Urals crude, she'll transit the Turkish Straits and enter the Mediterranean. Then the question becomes whether she heads west toward Europe or east toward the Suez and Asia. That routing decision, visible in real-time via AIS, tells you something about where Russian crude is finding buyers.

The Other Side

I flipped to the import side: "What tankers are heading to Rotterdam in the next few days?"

The model constructed an ETA window and called get_port_inbound. Among the results: HAIGUI -- an Oil Products Tanker, Liberian-flagged, 114,900 DWT, built by Samsung Heavy Industries. She's sitting at a draught of 13.2 metres. For a vessel that size, that draught means she's carrying serious weight.

"Check her inspection record."

17 inspections across five regimes -- Paris MoU, Tokyo MoU, Indian Ocean MoU, Black Sea MoU, US Coast Guard. Zero detentions. Only 4 deficiencies across over a decade of inspections. Ports visited include Rotterdam, Houston, Philadelphia, Amsterdam, Sydney, Ulsan, Dalian, Mombasa. That's a vessel with a global trading pattern and a clean compliance record -- the kind of ship a European refiner accepts without questions.

Her former name was GULF VALOUR until 2019. Name changes and ownership transfers are routine in commercial shipping, but they're also the bread crumbs that sanctions investigators follow. When a vessel changes name and flag within a short window, it's worth checking why.

Building the Signal

If I were building this into something real, the first thing I'd automate is departure counts from Novorossiysk and Primorsk. Week-over-week changes in Suezmax departures from Russian Black Sea ports are the crude signal -- more departures means more supply on the water, and you can estimate rough volumes by vessel class.

The import side is harder and more interesting. Counting arrivals at Rotterdam, Ningbo, and Jamnagar tells you where the oil is going. If European arrivals drop while Indian arrivals spike, that's a sanctions-driven rerouting -- exactly the kind of structural shift that moves Brent-Dubai spreads before the commentary catches up.

I tried to see if departure counts from Novorossiysk correlated with anything in the Brent forward curve. With only a week of port event data, the answer is: not enough signal, just noise. You'd need months. But the data is accumulating daily, and it's the same data that professional cargo-tracking firms start from before layering on satellite imagery and bill-of-lading records.

The compliance angle is arguably the most interesting for a smaller operation. Cross-reference departing vessels against classification records and inspection histories. A Suezmax with no classification society, no inspection record, and a Sierra Leone flag departing Novorossiysk is a different kind of data point than a Lloyd's-classed, Paris MoU-inspected vessel doing the same run. That distinction is worth money to compliance teams and underwriters.

You could set up a daily cron job with the Claude API to pull departures from ten export terminals. Pipe it into DuckDB. Track week-over-week. Build alerts for when a port goes quiet, or when shadow fleet tonnage surges at a terminal that normally services compliant trade.

Everything in this post came from live API calls on March 22, 2026. The results will be different tomorrow. That's the point. Sign up at vesselapi.com for a free key, drop the .mcp.json from the Setup section into your project root, and start asking. Try "What crude oil tankers departed Primorsk in the last 12 hours?" or "Find all tankers heading to Singapore -- which ones have the deepest draught?"

This was crude oil. The same approach works for LNG carriers at Sabine Pass, iron ore bulkers at Port Hedland, container ships stacking up outside Shanghai. The data is the same. The questions change.

The oil is on the water. Now you can see it.

Data queried from VesselAPI on March 22, 2026 via vesselapi-mcp. Port events return all vessel types; filtering to tankers requires a second vessel-detail lookup. EU MRV emissions are self-reported and independently verified. AIS identifiers can be spoofed. This is not financial advice.