Forem: VesselAPI

What an MMSI Lookup Actually Looks Up

VesselAPI — Fri, 22 May 2026 13:51:09 +0000

A ship has a name, and a name is a fragile thing. Maersk Detroit could be sold tomorrow and become Ocean Star. Ocean Star could be re-flagged, repainted, renamed again, and resurface six months later moving sanctioned crude in the South China Sea. Names lie. Flags lie. Even the hull, given a coat of paint and a torch to the bow numbers, can be made to lie.

What doesn't lie — or at least, lies less often — is a nine-digit number broadcast by the ship's radio at intervals ranging from every couple of seconds when underway to every few minutes at anchor. That number is the MMSI. And when you build an "MMSI lookup," what you are really doing is asking a deceptively hard question: given this number, who is this, right now, today?

The first time I queried an MMSI on a vessel I was actively tracking and got back a tanker that had been scrapped in 2019, I assumed the API was broken. It wasn't. The MMSI had been reassigned. That was a fun afternoon.

The number itself

MMSI stands for Maritime Mobile Service Identity. It is, on the surface, exactly what it sounds like: a unique radio identifier assigned to a vessel (or a coast station, or a navigational aid, or a life raft's distress beacon) so that other radios can address it. Nine digits. Broadcast in every AIS message the ship transmits. If you've ever seen a live map of ocean traffic — those flickering arrows crawling across the Mediterranean — every one of those arrows is, at the wire level, an MMSI.

The first three digits are called the MID, the Maritime Identification Digits, and they encode the country whose flag the vessel sails under. 232 through 235 are the United Kingdom. 338 and 366 through 369 are the United States. 477 is Hong Kong. The remaining six digits are assigned by that country's licensing authority, more or less however they like.

So already, before you've looked anything up, an MMSI tells you something. 538 at the front? That's the Marshall Islands — one of the world's largest open registries and a dominant flag of convenience for tanker operators, for reasons that have very little to do with the Marshall Islands. 412 at the front? Mainland China. The number is a passport, sort of.

But here is the first uncomfortable truth: MMSIs are not permanent. When a vessel changes flag, it gets a new MMSI. When it's sold to an operator in a different jurisdiction, new MMSI. When a transponder is replaced and the new one is misconfigured — which happens more often than the industry likes to admit — the MMSI can change with no paperwork at all. Sometimes two vessels broadcast the same MMSI by accident. Sometimes, less innocently, on purpose.

So a lookup isn't a dictionary read. It's a forensic question.

What a lookup is actually doing

When you call something like GET /vessel/{mmsi} on a vessel data API, here's what's happening behind that single line of HTTP.

First, the system has to find every record that has ever been associated with that MMSI. That sounds trivial; it isn't. The same nine digits, over the course of a decade, might point to two or three completely different ships. Good lookup services maintain a temporal index — in practice, an append-only event log keyed on (mmsi, valid_from, valid_to, vessel_id) that you can query at a point in time. Not just what is MMSI 477123456? but what was MMSI 477123456 on the afternoon of 14 March 2021?

Second, it has to resolve to the ship's more durable identifiers. The MMSI is the radio identity; the IMO number is the hull identity. The IMO ship identification scheme is mandated by the International Maritime Organization and administered by its authorized registrar (currently S&P Global, formerly IHS Markit, formerly Lloyd's Register Fairplay — the genealogy itself tells you something about how this industry works). The IMO number is intended to follow the steel of the ship from cradle to scrapyard, regardless of how many times it changes name or flag. In practice, vessels not engaged on international voyages — and most fishing boats and inland barges — don't have IMO numbers at all, and some operators of larger vessels have been known to broadcast incorrect ones. But when an MMSI and an IMO agree, and have agreed for years, you have something close to ground truth.

Third, it has to enrich. This is the layer most people don't think about until they need it. Beyond identity: dimensions, deadweight tonnage, year and place of build, class society, last known position, last known port call, whether the vessel appears on a sanctions list under any of its previous names. And ownership — which is its own swamp. Current operator, registered owner, and beneficial owner are three different entities, often deliberately so. AIS doesn't carry any of them. Knowing who actually owns a ship requires an entirely different lookup chain, and the answer is frequently a shell company in a jurisdiction that does not enjoy being asked.

A "lookup" that returns only the name and flag is barely a lookup. It's the cover of a book.

The dark inputs

Here's the part that makes this genuinely difficult. AIS — the Automatic Identification System that carries the MMSI — was developed through the 1990s as a vessel traffic management and collision-avoidance system, ratified under SOLAS in the early 2000s. It assumed everyone was honest, because the original users were port authorities and bridge officers, and in a collision scenario, dishonesty kills you first. The lack of any authentication layer was a deliberate architectural choice for low-cost receiver compatibility — but the upshot is the same: AIS is a network of unsigned messages from strangers, and that assumption no longer holds.

Vessels engaged in sanctions evasion routinely spoof their MMSI, broadcasting a number that belongs to a different ship — or to no ship at all. They go dark, switching off their transponder entirely for days or weeks. And in cases documented in OFAC advisories and UN Panel of Experts reports on Iran and North Korea sanctions, they meet other vessels in unmonitored waters and conduct ship-to-ship transfers: the dirty cargo physically moves to a clean ship, sometimes while one or both vessels broadcast another ship's identity entirely. The MMSI doesn't literally swap. The cargo does, and the electronic identity is manipulated to obscure who carried what.

A naive MMSI lookup — the kind that just returns whatever the latest AIS broadcast claims — will happily report back the spoofed identity as fact. A serious lookup cross-references the broadcast against fleet registries, historical position tracks, hull dimensions detected by satellite synthetic aperture radar, and port arrival records. When the AIS says "I am a 180-meter bulk carrier" and the satellite radar says "you are a 250-meter tanker," the lookup is supposed to notice.

Building one that doesn't lie to you

There are a lot of "vessel lookup" APIs in the world. Most of them are a thin wrapper around the most recent AIS broadcast, which is to say, most of them will cheerfully repeat whatever a transponder told them six minutes ago, with no provenance and no sense of history. That's fine for drawing dots on a map. It is not fine for any decision with consequences.

The two things I actually care about, when evaluating one of these services, are time and provenance.

Time, because an MMSI is a moving target. If the API can't tell you what an MMSI meant on a specific date, it cannot help you with a sanctions investigation, an insurance claim, or any question about the past. The phrase "this MMSI belonged to a different vessel last year" should be a normal sentence in its response, not a footnote.

Provenance, because "vessel name: ATLANTIC PIONEER" means very different things depending on where that string came from. A name pulled from the IHS/S&P registry against a confirmed IMO number is near-truth. The same name pulled from a single AIS broadcast forty minutes ago, with no IMO cross-check and no historical confirmation, is a rumour. A lookup that doesn't distinguish between these two cases is, frankly, lying to you politely.

And then there's the question of whether the API has actually thought about the long tail. Most fail there — because the small fishing boats with no IMO, the inland river barges with regional MMSI quirks, the AIS aids-to-navigation with the 111 prefix, the AIS-SART distress beacons in the 970 range — none of these things show up in the sales demo. They show up at three in the morning when your pipeline throws a null pointer and a container ship somewhere is unaccounted for.

The nine digits look like a phone number. They are not a phone number. They are a thread — and pulling on a thread is how you find out what's actually on the other end of the line. In this case: forty years of flag-state politics, satellite coverage gaps, and ships that, very specifically, do not want to be found.

How to Measure a Ship's CO Emissions From Land

VesselAPI — Wed, 20 May 2026 11:42:57 +0000

How to Measure a Ship's CO₂ Emissions From Land

Here's a question that sounds simple until you try to answer it: how much CO₂ did that container ship just emit on its way from Shanghai to Rotterdam?

You can see the ship. You know roughly where it went, and roughly how fast. You can look up its size. And yet the honest answer — the one a regulator or a carbon accountant would actually accept — requires you to know things about that vessel that aren't printed on the hull. What fuel was in its tanks. What its engines were designed to do at three-quarters load. Whether its propeller has been polished this year. Whether the paint on its hull is the slick anti-fouling kind or the kind that's currently hosting a small ecosystem of barnacles.

This tutorial is about closing that gap. We're going to walk through how to ask our /emissions endpoint for the CO₂ output of a single vessel, and — more interestingly — how to understand what the API is actually doing under the hood. Because if you're going to make a decision based on a number, you should know where the number came from.

The thing everyone gets wrong

Most people assume ship emissions are calculated the way car emissions are: you burn X litres of fuel, each litre contains Y grams of carbon, multiply, done.

That's roughly right for a car. It falls apart for ships almost immediately.

The IMO does publish carbon factors for each marine fuel type, and they're as clean as you could want. For heavy fuel oil (HFO), the number is 3.114 grams of CO₂ per gram of fuel burned. For VLSFO — the blended low-sulphur product most large vessels burn today — it's 3.151. For marine gas oil (MGO), 3.206. For LNG, the direct combustion factor is 2.750. These aren't interchangeable. Submitting an MRV report with the HFO factor against a tank of VLSFO will fail verification, which is exactly the kind of thing I got wrong the first time I tried to reconcile a vessel's annual fuel mix against its reported emissions. The numbers look close. They aren't.

If you knew exactly how much of each fuel a ship had burned, you'd be done. The problem is that almost nobody outside the ship does. Aggregate fuel consumption is reported annually under the IMO Data Collection System; per-voyage data is collected by the EU MRV regime for vessels calling at European ports, but it isn't publicly accessible. If you want per-voyage emissions from the outside, you have to estimate them — working backwards from what the ship was designed to burn, and adjusting for what it probably actually did.

The starting point for that estimate is a three-letter acronym you'll see everywhere in this domain.

What EEXI actually is

EEXI stands for Energy Efficiency Existing Ship Index. The name sounds like it was designed to deter questions, so let's ignore it.

What EEXI actually is: a fuel economy rating. It's the mpg sticker on the window, except the window is a 300-metre container ship and the sticker is buried in a classification society database in Hamburg.

For most existing vessels of 5,000 gross tonnes and above — broadly, the ships big enough to do international trade and already in service when the regulation took effect on 1 January 2023 — the IMO requires a calculation that answers a single question: if this ship sailed at the speed corresponding to 75% of its maximum continuous engine rating, in calm weather, in a defined reference state, how many grams of CO₂ would it emit per tonne of cargo per nautical mile?

That's it. Standardised conditions, one number, comparable across vessels. A modern, efficient large bulk carrier might come in around 3 g CO₂/tonne-nm. An older, smaller one might be roughly double that. Container ships sit higher again because their capacity is measured differently. Lower is better, the way fewer litres per 100km is better on a car.

EEXI on its own doesn't tell you what a ship emitted yesterday. But combined with a known route, a speed profile, and a load factor, it lets you build a credible estimate without ever needing the captain's fuel logs.

The request

Let's measure something. Here's a minimal call for a vessel by IMO number:

curl "https://api.vesselapi.com/v1/emissions?imo=9395044" \
  -H "Authorization: Bearer YOUR_API_KEY"

And here's the relevant chunk of the response, trimmed for clarity. The values are illustrative — they show the shape of the response, not certified figures for this vessel:

"emissions": {
  "eexi": {
    "attained": 6.82,
    "required": 7.84,
    "unit": "g_co2_per_tonne_nm",
    "compliant": true
  },
  "fuel": {
    "primary": "VLSFO",
    "eca": "MGO",
    "carbon_factor_primary": 3.151,
    "carbon_factor_eca": 3.206
  },
  "verifier": {
    "name": "DNV",
    "verified_at": "2023-04-12",
    "method": "approved_calculation"
  }
}

The most important field here is probably the one you'd skip past on first reading: verifier. We'll come back to it. First, the things this response is telling you about the ship itself.

EEXI arrives as a pair — attained and required. EEXI is an efficiency index, so lower is better, and required is a ceiling: the maximum value the IMO will accept for this ship type and size. The vessel is compliant if attained sits at or below that ceiling. If it doesn't, the primary remedy is an Engine Power Limitation: a technical and administrative measure that caps engine output and brings the attained index down. Switching fuels operationally doesn't change EEXI itself — EEXI is a design-condition index, fixed at certification. Fuel choices affect the operational metric (CII) instead. A ship that can't demonstrate EEXI compliance can't get its certificate endorsed, which means in practice it can't legally trade. It isn't really a menu.

The fuel block reports two carbon factors because most large vessels switch fuels at ECA boundaries — the North Sea, the Baltic, the US and Canadian coasts, and (from 1 May 2025) the Mediterranean. VLSFO on the open ocean, MGO or another compliant blend inside the zone. For a voyage that crosses an ECA boundary, you need to know which fuel was burning where.

Why the verifier matters more than the number

An emissions number without a verifier is a rumour.

I mean this practically. EEXI calculations are prepared by the ship's owner or technical manager and submitted to a classification society — DNV, ABS, Lloyd's Register, ClassNK, Bureau Veritas. These bodies do the actual checking: engine specs, hull form, propulsion train, sea margin assumptions, the lot. They either approve the calculation or send it back. The number that survives this process is the only one that means anything in a regulatory context.

When the API returns a verifier block, it's saying: this isn't our estimate. This is the number a recognised classification society signed off on, with their reputation attached. If the verifier field is missing, or shows "method": "estimated", you're looking at a calculated approximation. Most APIs don't surface this distinction at all, which is how an estimated figure ends up in someone's audited disclosure.

For the EU ETS, which began applying to shipping in 2024 (40% of verified emissions surrendered that year, 70% in 2025, 100% from 2026), or for CSRD disclosures, or for any scope 3 reporting that has to survive contact with an auditor — the verified number is the one that matters.

From EEXI to an actual voyage

EEXI gives you grams of CO₂ per tonne-nautical-mile under reference conditions. To get the emissions of an actual voyage, the back-of-envelope multiplication is:

voyage_emissions = EEXI × cargo_tonnes × distance_nm × correction_factor

This formula works, with friction. EEXI is calibrated to a defined reference state, which for bulk carriers and tankers is 70% of deadweight but for container ships is a TEU-based capacity figure — not a deadweight fraction at all. Check the IMO guidelines for the vessel class before applying a load correction. The cargo_tonnes you plug in should reflect actual cargo on board, because a container ship sailing 60% laden carries 60% of the cargo but burns considerably more than 60% of the fuel. And the formula degenerates on a ballast leg: zero cargo gives zero emissions, which is physically impossible. Ballast voyages need a displacement-based substitution or allocation back to the laden leg.

The correction factor is where the rest of the honesty lives. Real voyages aren't reference conditions. Heavy weather adds fuel. Slow steaming subtracts it — dramatically. For full-form displacement vessels, fuel consumption scales with speed at an exponent typically between 2.7 and 3.5, with the cube as the standard admiralty anchor. That non-linearity is why dropping container ship service speeds from around 21 knots toward 14 was, by most accounts, the single biggest operational lever the industry pulled in the last decade. Not technology. Just patience, and the willingness to leave port a day earlier.

For a rough estimate, a correction factor between 1.1 and 1.3 covers most container and bulk voyages in fair-to-moderate conditions. For anything precise, you want AIS-derived speed profiles for the actual voyage — which is the bridge between the /emissions endpoint and the /positions endpoint. Combine the two and the error band tightens, though the residual error depends heavily on voyage type and the quality of the load assumption.

What this still doesn't tell you

EEXI is a design-condition metric. It doesn't capture hull fouling — industry studies suggest six months of moderate fouling can add roughly 10% to fuel burn, and severely fouled hulls have been measured at 30% or worse. It doesn't capture weather routing decisions. It doesn't capture auxiliary engines running in port, which on a large container ship is not a rounding error. And it doesn't capture methane slip from LNG carriers, which deserves a paragraph of its own.

Methane slip is uncombusted natural gas escaping through the engine. It's a separate problem from the LNG carbon factor, and it doesn't show up in EEXI at all. Fossil methane carries a GWP₁₀₀ of roughly 30 per the most recent IPCC figures (the exact value depends on the assessment report and whether you include climate-carbon feedbacks), so a few percent of slip can erase the apparent climate advantage of switching from oil to gas. Two-stroke high-pressure LNG engines slip very little; some four-stroke low-pressure designs slip enough to matter. The API returns a CO₂-only figure and flags LNG vessels separately, because rolling slip into a single number requires picking a GWP horizon, and that choice is a political one as much as a scientific one.

So: where does that leave you? If you're filing EU ETS reports, the verified EEXI number is where you start and your auditor decides whether you need to go further. If you're building a product that surfaces emissions to end users, a well-bounded estimate is almost certainly fine and most users won't know the difference. If you're trying to prove in a contract dispute that a specific voyage exceeded a specific threshold — call a naval architect, not an API.

At sea, with no fuel pump to read and no tailpipe to sniff, the gap between what was burned and what we can prove was burned is wider — and stranger — than most people realise.

Why There's a Tanker in Central Madrid

VesselAPI — Tue, 19 May 2026 22:27:50 +0000

We ingest about a million raw AIS messages every hour. Roughly four out of ten never make it to our database.

That is not because they are all wrong. Most of those rejected messages aren't position reports at all — they are vessel name broadcasts, safety messages, channel management commands, or interrogation requests that arrive on the same feed. Once you strip those out, you are left with the actual position data. A 300-metre oil tanker reporting its position as central Madrid. A bulk carrier allegedly doing 90 knots — which would make it faster than most warships. A cargo vessel that teleports from the North Sea to the Sahara Desert between two consecutive reports, three seconds apart.

The genuinely bad position data — invalid coordinates, impossible jumps, sentinel values from transponders that lost GPS — is a smaller fraction, probably in the single-digit percentages based on what we see and what academic literature reports. But even a few percent, at the volumes AIS produces, means tens of thousands of phantom ships drifting across continents every day.

This is AIS — the Automatic Identification System — the backbone of global vessel tracking. Every ship over 300 gross tonnes on an international voyage is required by SOLAS to broadcast its identity and location over VHF radio, every few seconds, around the clock. Around 400,000 vessels do this simultaneously, generating over 300 million messages per day. It is one of the largest real-time geospatial data streams on the planet.

Nobody warns you about this part.

We are VesselAPI, a two-person company in Málaga, Spain. We built a REST API that takes this raw radio data and turns it into something you can actually use. What follows is the story of how we learned, the hard way, that maritime data wants to lie to you — and the filtering we built to catch it.

What “Not Available” Looks Like at 161.975 MHz

The AIS specification — ITU-R M.1371-5, if you want to look it up — was designed by people who understood that transponders would sometimes have no idea where they are. So they built in sentinel values: specific numbers that mean “I don’t know.”

Latitude 91° North. Longitude 181° East. Speed 102.3 knots. Heading 511°.

These are not real coordinates. They are the AIS equivalent of a shrug. A transponder that has lost its GPS fix, or has just been powered on and hasn’t acquired satellites yet, is supposed to transmit these values. The problem is that plenty of systems downstream — tracking platforms, analytics tools, map renderers — don’t check for them. They plot the point. And suddenly you have a vessel at 91° latitude, which is one degree past the North Pole, in mathematical space that doesn’t physically exist.

We filter these out. Latitude over 90, longitude over 180, SOG at 102.3, heading at 511 — gone before they touch the database. The same goes for (0, 0) — Null Island, a fictional place in the Gulf of Guinea that is the most popular port on Earth if you believe unfiltered GPS data.

The Pipeline

When a raw AIS message arrives, it passes through four stages before it becomes an API response. We did not plan four stages. We started with coordinate bounds checking and kept adding layers as new classes of garbage revealed themselves.

Message Type Filtering

AIS has 27 message types. Types 1, 2, and 3 are Class A position reports — the bread and butter, broadcast every 2 seconds to 3 minutes depending on speed and navigational status. A container ship doing 20 knots and changing course reports every 2 seconds. The same ship at anchor drops to every 3 minutes. Types 18 and 19 are Class B position reports from smaller vessels. The other 22 message types — binary data, safety broadcasts, channel management, interrogation requests — are not positions.

We were surprised how often non-position messages leaked into position processing. A Type 5 message (static and voyage data — ship name, dimensions, destination) has no coordinates but arrives on the same feed. Our first week in production, we had phantom entries with zeroed-out positions because we weren’t filtering on message type.

switch cache.MessageType {
case string(aisstream.POSITION_REPORT),
    string(aisstream.STANDARD_CLASS_B_POSITION_REPORT),
    string(aisstream.EXTENDED_CLASS_B_POSITION_REPORT):
    // valid position type
default:
    return nil
}

Three lines. They fixed a category of bad data that had cost us two days of debugging.

MMSI Validation

Every AIS transponder has a Maritime Mobile Service Identity — a 9-digit number that encodes what kind of entity is broadcasting. Ship stations use MMSIs in the range 100,000,000 to 799,999,999, where the first three digits (the MID — Maritime Identification Digits) roughly indicate the flag state’s region: 2xx for Europe, 3xx for the Americas, 4xx for Asia, and so on.

Outside that range, you get coast stations (prefixed 00), SAR aircraft (prefixed 111), man-overboard devices (972), and EPIRBs (974). All of these broadcast AIS, and none of them are ships. Then there are MMSIs that shouldn’t exist at all — misconfigured transponders with default factory values, test transmissions. We reject anything outside the vessel range:

if cache.MMSI < 100000000 || cache.MMSI > 799999999 {
    return nil
}

There is also a subtler problem: MMSI sharing. When multiple vessels use the same MMSI — whether through misconfiguration or deliberate sanctions evasion — a single identity appears to teleport across oceans. Your tracking system shows one ship doing 4,000 knots because it is actually two ships on opposite sides of the Indian Ocean, alternating transmissions. This is a documented tactic used by the dark fleet. Kpler identified 261 vessels that spoofed AIS before being sanctioned. An estimated 600 to 1,000 vessels — roughly 10% of the global large oil tanker fleet — operate this way.

Coordinate Validation

After message type and MMSI filtering, we validate the coordinates themselves:

if cache.Latitude == 0 && cache.Longitude == 0 {
    return nil
}
if cache.Latitude < -90 || cache.Latitude > 90 ||
    cache.Longitude < -180 || cache.Longitude > 180 {
    return nil
}

The (0, 0) check catches Null Island — what happens when a GPS chipset defaults to zero. The bounds check catches both corrupted data and the sentinel values from the spec (91° and 181° both fall outside the valid range). Simple, fast, eliminates a remarkable amount of junk.

But it has a fundamental limitation: it cannot tell you whether a position is plausible, only whether it is possible. A ship reporting its position as downtown Lagos passes every check — valid latitude, valid longitude, valid MMSI. It is also on land. We could add coastline polygon checks, but at ~235 messages per second on a single t3.medium instance, the spatial computation cost does not justify the catch rate. Instead, we handle plausibility in the next layer.

Jump Detection

The first three stages examine each message in isolation. This one looks at the sequence.

For every MMSI, we keep the last known good position in a sync.Map — Go’s concurrent map, which fits here because reads vastly outnumber writes and the key set (active vessel MMSIs) is relatively stable. When a new position arrives, we compute the implied speed: how fast would this ship have to be moving to get from the last known position to the new one?

const maxSpeedKnots = 500

func approxDistanceKm(lat1, lon1, lat2, lon2 float64) float64 {
    const kmPerDeg = 111.0
    dLat := (lat2 - lat1) * kmPerDeg
    midLat := (lat1 + lat2) / 2.0 * math.Pi / 180.0
    dLon := (lon2 - lon1) * kmPerDeg * math.Cos(midLat)
    return math.Sqrt(dLat*dLat + dLon*dLon)
}

// In the detection logic:
distKm := approxDistanceKm(last.Latitude, last.Longitude, lat, lon)
speedKnots := (distKm / elapsedSeconds) * 3600.0 / 1.852
if speedKnots > maxSpeedKnots {
    suspectedGlitch = true
}

The threshold is 500 knots — about 926 km/h, roughly 10 times the speed of the fastest commercial vessel on Earth. If the implied speed exceeds that, the position is flagged as a suspected glitch.

Why 500 and not something tighter, like 30 or 50? Because AIS messages arrive out of order, with gaps, from multiple sources with different latencies. A container ship at 20 knots that misses a few reports and then sends a batch can look like a jump. Setting the threshold at physical impossibility means we catch genuine GPS failures — the Madrid tanker, the Sahara cargo ship — without flagging normal transmission delays. We had an earlier version with the threshold at 50 knots, and it was flagging container ships rounding headlands in the English Channel. That lasted about a day.

The equirectangular distance approximation is deliberate. For consecutive AIS reports — typically seconds to minutes apart, so sub-10 km distances — the error is well under 1% at normal shipping latitudes. Even at 70°N, above most commercial routes, it stays under 5%. And against a 500-knot threshold, none of that matters. Haversine would be wasted precision.

The Cache Trick

The position cache has one design decision that makes the whole thing work: glitch positions do not update the cache.

if !suspectedGlitch {
    c.positionCache.Store(mmsi, &cachedPosition{
        Latitude:  lat,
        Longitude: lon,
        Timestamp: timestamp,
    })
}

If a ship sends a glitched position — say, it briefly appears in the Sahara — and we update the cache with that position, then the next real report from the English Channel would look like an impossible jump from the Sahara. One bad message poisons all future comparisons for that vessel.

By only caching clean positions, the system self-heals. A single GPS spike gets flagged. The next legitimate report compares against the last good position and passes normally. The glitch never propagates.

The cache grows unboundedly right now — one entry per active MMSI, so around 60-70K entries in steady state. At ~100 bytes per entry, that is under 10 MB. We should probably add a TTL to evict vessels that stop reporting, but in practice it has not been a problem yet.

Production

Here is our monitoring map from February 5, 2026 — the day we deployed the jump detection layer:

Green dots: valid vessel positions. Red triangles: suspected GPS glitches. Production data, February 5, 2026.

Green dots: valid vessel positions, tracing coastlines and shipping lanes. Red triangles: suspected glitches, scattered across sub-Saharan Africa, the Brazilian interior, the South Atlantic.

Cintia pulled up the map the morning after we deployed it and called me over — “come look at Africa.” We’d been dismissing those positions as weird data for weeks. They were not weird. They were systematic GPS failures that had been flowing through to our API consumers the entire time.

In a 24-hour window: 20.3 million positions, 64,412 unique vessels. 966 H3 cells — a hexagonal spatial index, each cell about 250 km² at resolution 5 — contain only glitch positions. The Sahara, the Congo, landlocked South America. We should have caught it sooner.

Why AIS Data Is This Bad

How does a system used by 400,000 vessels, mandated by international convention, produce this much junk?

Start with the radio layer. Each AIS VHF channel gets exactly 2,250 time slots per minute. Class A transponders use SOTDMA — self-organizing time division multiple access — which lets them reserve a slot through a negotiation protocol. Class B CS transponders (used on smaller vessels) use carrier-sense TDMA, which is less deterministic: they listen for an opening and try to grab one. Newer Class B+ units also use SOTDMA, but the older CS units are still everywhere. In congested waters like the Singapore Strait, there are so many ships that Class B units cannot find empty slots. They fail to transmit, or their messages collide.

Then there is GPS itself. Multipath reflection — signals bouncing off containers, crane structures, bridge superstructure — introduces positioning errors. And there is a configuration problem that nobody talks about enough: if a navigator sets a GPS offset correction on the bridge, the AIS transponder broadcasts the wrong position by exactly that offset for the entire voyage. Not spoofing. Just a button nobody remembered to reset.

And then there is actual spoofing. In June 2017, around 20 vessels in the Black Sea simultaneously reported positions miles inland on Russian territory — the first widely documented case of mass maritime GPS spoofing. In 2019, hundreds of ships near Shanghai saw their positions form strange rotating circles — up to 200 metres in radius — near oil terminals and government buildings. C4ADS documented the pattern. MIT Technology Review described it as a form of GPS spoofing that had never been seen before. And in March 2026, per Windward’s GPS monitoring data, over 1,100 vessels in the Persian Gulf were disrupted in a single day following military strikes on Iran. Ships appeared inside airports, near nuclear facilities, deep in the Iranian interior.

AIS was designed for collision avoidance, not adversarial security. There is no authentication in the protocol. SOLAS can require you to carry a transponder. It cannot require the transponder to be honest.

Flag, Don’t Discard

Our first instinct was to delete glitch positions. Don’t store them, don’t serve them, pretend they never happened. We had it built that way for about three weeks before a customer asked whether we could expose the glitch data — they were building a monitoring tool that specifically needed to detect GPS manipulation patterns.

So we changed it. We store every glitch-flagged position with suspected_glitch: true and return it in API responses. If you are building a map, you filter them out. If you are doing sanctions compliance work, those anomalies are exactly what you are looking for.

Our filter pipeline is maybe 250 lines of Go. It runs on a single EC2 t3.medium — 2 vCPUs, 8 GB RAM, the kind of instance you forget exists until the bill shows up. About a million raw messages come in per hour; roughly 600,000 clean positions come out the other end. Nothing about this is impressive infrastructure. We built it in a week and have not thought about it much since, except when it catches something bizarre and you go “huh, a ship in Chad.”

The ITU got the spec right. The problem is everything between the specification and the antenna — the part where the real world gets involved. If you are thinking about building on AIS data, budget more time for filtering than you think you need. We did not, and we spent a month serving phantom ships to paying customers before we noticed.

The MMSI Lookup Is Lying to You (And That's Not Its Fault)

VesselAPI — Mon, 18 May 2026 19:11:42 +0000

You type a nine-digit number into a search box. Out comes a ship: a name, a flag, a length, a cargo type, maybe a fuzzy photo taken from a pilot boat in Rotterdam three years ago. The number is the MMSI — Maritime Mobile Service Identity — and it feels like the most boring possible piece of maritime data. It's an ID. You look it up. You get a ship.

Except the MMSI is not, in any strict sense, the ship's identity. It's the identity of the radio on the ship. And once you understand the difference, a lot of strange things about vessel tracking start to make sense — including why our /vessel/{id} endpoint returns an array called former_names[], and why that array is sometimes longer than you'd believe.

What an MMSI actually is

The MMSI was never designed to be a permanent vessel identifier. It was designed by the ITU — the International Telecommunication Union, the same body that allocates radio spectrum and country calling codes — to route maritime radio traffic. For ship-station MMSIs, the first three digits, the Maritime Identification Digits, encode the country that issued the number. The rest is administrative.

When SOLAS mandated Class A AIS for international trading vessels, the rollout was phased over several years beginning in 2002, with smaller tiers and existing fleets not fully captured until the late 2000s. The MMSI was the natural identifier to broadcast — every SOLAS vessel equipped with a DSC-capable VHF radio under the GMDSS rules of the 1990s already had one — and reusing it required no new numbering authority. It was a pragmatic choice, not a design decision.

Here's what an MMSI actually is: a number associated with a transmitter, registered to a vessel, flagged to a country, at a particular moment in time. Change any of those and the relationship shifts. Sell a ship to an owner in another country and the MMSI changes — new flag, new MID, new number. Scrap a vessel and the MMSI may eventually be eligible for reissuance, though practices vary by flag state and most administrations have grown reluctant to reuse numbers because of the AIS contamination it causes. Far more common, in practice, is the ghost record problem: the hull is gone, but the MMSI keeps matching in aggregator databases because nobody told the aggregator.

And then there's the misconfigured transponder. A significant number of vessels — overwhelmingly small craft running cheap Class B units, not SOLAS-grade Class A installations — are out there broadcasting 123456789 or 000000000 because someone shipped a unit with factory defaults and nobody changed them. This should have been solved at the hardware certification level a decade ago. It wasn't. The result is the same: two ships, sometimes on opposite sides of the planet, broadcasting the same MMSI in the same minute.

The MMSI is more like a license plate than a VIN. The plate identifies the car on this road, under this jurisdiction, right now. The VIN identifies the car itself. AIS gives you the plate. You have to do real work to get to the VIN.

The thing that actually identifies a ship

The closest thing the maritime world has to a VIN is the IMO number — seven digits, issued by the International Maritime Organization, and (in principle) attached to a hull for life. Scrap the ship and the IMO retires with it. Rename it, reflag it, repaint it, sell it to a shell company: the IMO stays.

The analogy nearly works. The catch is the scope. Under IMO Resolution A.1078(28), IMO numbers are required for commercial cargo vessels of 300 GT and above on international voyages, passenger ships of 100 GT and above, and — progressively — fishing vessels of 100 GT and above. The exemptions matter more than the thresholds: pleasure yachts not in trade, domestic-only vessels, government vessels, and, critically, most of the global fishing fleet, which sits below the 100 GT cutoff and is therefore legitimately exempt. Among the fishing vessels that are eligible, flag-state compliance is inconsistent at best — a fact anyone who has tried to identify a vessel involved in IUU fishing will recognize immediately.

So a serious vessel lookup has to reason about identity using several keys at once — MMSI, IMO, call sign, name — and know which one to trust when they disagree. They disagree often.

My personal opinion, for what it's worth: the IMO number should be mandatory for every motorized seagoing vessel, full stop. The fact that it isn't costs the industry — and sanctions enforcement, and fisheries management, and casualty investigations — real money every year. But the politics of flag state sovereignty being what they are, we work with what we have.

Why `former_names[]` is an array

When you query /vessel/{id} and get back a vessel record, one of the fields is former_names. We didn't add it for novelty. We added it after a customer ran a sanctions screen against a current vessel name, got a clean result, and chartered a ship that — under a previous name two owners back — had been hauling sanctioned crude out of a port nobody wants to be associated with. The hull was sanctioned. The current name was not. Same ship. Different mask. The customer was, understandably, not delighted.

A bulk carrier built in 2008 might have been called Atlantic Pioneer under one owner, Star Pioneer under the next, MV Helena after a sale to a Greek operator, and Ocean Star III after a charter restructuring last spring. (Illustrative names; the pattern is real.) Same hull. Same IMO. Four names. Possibly three different MMSIs along the way, because each sale brought a reflag.

If your application caches "MMSI 538001234 → Ocean Star III" and a customer asks about a port call from 2019, you'll tell them no such ship visited, when in fact Atlantic Pioneer visited twice that month. The vessel didn't lie. Your model of vessel identity did.

This is why a good vessel lookup API doesn't just resolve the current state. It resolves the history — every alias the hull has worn, with date ranges where we can establish them. The same principle drives former_flags[], former_owners[], and former_mmsis[], populated where registry data and AIS static records let us reconstruct the chain. Coverage is uneven: former_names and former_mmsis are usually dense; former_owners is sparse for vessels flagged in states with limited public registry disclosure, and we'd rather return an empty array than a confident lie. The alternative — presenting a clean record where the data doesn't support one — is exactly how customers end up chartering the wrong ship.

Disambiguating the transmitter from the hull

Given all of this, "MMSI lookup" turns out to be a small phrase covering a fairly large pile of work. When an MMSI comes in, the system has to decide which hull it currently maps to, and flag uncertainty when two hulls are broadcasting the same number. Then the registries have to be reconciled: flag state databases, classification societies, port state control records, and AIS feeds all carry partial and often contradictory views of the same ship. Somewhere in the pipeline they get merged with a defensible source priority — IMO GISIS, flag state registry, AIS static, last-seen timestamp as tiebreaker — rather than a coin flip.

And then there's the matter of vessels that are actively lying about where they are. AIS messages are unauthenticated; there is no cryptographic integrity on the protocol and there never has been, despite twenty years of industry conversation about it. A vessel can broadcast a false MMSI, a false position, or both. The most documented case is the Black Sea, where mass GNSS interference around the Crimean peninsula has placed dozens of vessels at false locations simultaneously — the signature of deliberate infrastructure-level spoofing rather than individual misconfiguration. The Persian Gulf and Chinese coastal waters show different patterns, more consistent with individual vessels concealing dark activity than fleet-wide displacement. The Eastern Mediterranean and the Baltic have joined the list since 2022.

The defense against this is unglamorous. A serious lookup flags physically impossible position transitions: a ship logged in Singapore on Tuesday cannot appear in the Black Sea on Wednesday, because the implied speed would be impossible for any displacement hull. Detection isn't a single threshold — it's a combination of implied speed (commonly set somewhere in the 30–60 knot range, depending on vessel class and operator), acceleration envelopes, and cross-checks against legitimate fast traffic like ferries and patrol craft. It's probabilistic. It catches most cases, occasionally flags a perfectly innocent fast ferry, and never gives you the satisfying yes-or-no answer you'd like.

The honest framing

The reason "MMSI lookup API" is a useful search query but a slightly misleading product description is that nobody actually wants an MMSI lookup. They want to know what ship they're looking at. They want to enrich a port call record. They want to check if the vessel showing up in their charter quote is the same one that ran aground off Suez last year under a different name.

The MMSI is the way in. It's the doorknob, not the room.

What sits behind it — if the API is doing its job — is a model of vessel identity that knows the difference between a transmitter and a hull, between a current name and a historical one, between an authoritative source and a noisy one. That model is the actual product. The nine-digit number is just the most convenient way for you to ask the question.

The ships out there, slowly tracing wakes across the North Atlantic, don't care what we call them. They wear names the way people wear coats — putting one on for a season, hanging another in the back of the closet, occasionally forgetting which one they showed up in. The MMSI is the label sewn into the collar of the coat the ship is wearing today. If you want to know who's inside, you have to look further in.

Hexagons, Hypertables, and 240 Dead Tags: Migrating a Maritime Data Platform to TimescaleDB

VesselAPI — Thu, 14 May 2026 23:39:44 +0000

Every ship in the world is constantly shouting its name into the void. Its position, its heading, its speed, its destination — broadcast every few seconds via radio, picked up by satellites and shore stations, and funneled into databases that try to make sense of it all. At VesselAPI, we run one of those databases. And for the first year of our existence, we ran it on MongoDB. This is the story of why we stopped.

It's also a story about hexagons and a single mismatched struct tag that quietly broke an entire data pipeline.

The Shape of the Problem

AIS — the Automatic Identification System — is the backbone of maritime surveillance. Most commercial vessels are legally required to carry a transponder that broadcasts their identity and position — SOLAS mandates it for ships of 300 gross tonnage and upwards on international voyages, and many flag states extend the requirement further. The result is a firehose: at peak hours, we ingest roughly 700,000 position reports every sixty minutes. Each one is a point in space and time — latitude, longitude, timestamp, vessel identifier, plus speed, heading, and a handful of other fields. Position-in-time is the core of it.

If you squint at this data, it looks like a document. A position report has fields. You can serialize it as JSON. MongoDB will happily store it. And for the first few months, that was fine. We were building fast, the schema was changing daily, and MongoDB's flexibility was genuinely useful. Hard to have migration problems when there's nothing to migrate.

But here's the thing about vessel positions: they aren't documents. They're measurements. They have a timestamp and a location, and those two properties aren't just metadata — they're the entire point. The questions you ask of this data are fundamentally about time and space: Where was this ship two hours ago? What vessels are within 50 kilometers of Rotterdam right now? Show me everything that passed through the English Channel since Tuesday.

At the time, MongoDB had no native concept of any of this. (It has since added time-series collections, though they remain limited compared to purpose-built solutions.) It didn't understand that timestamps partition naturally into chunks, that old data expires, or that latitude and longitude define a point on a sphere where "within 50 kilometers" is a question with real mathematical structure. You can bolt on 2dsphere indexes and TTL policies, but you're fighting the grain of the database. And at 700,000 rows per hour, fighting the grain gets expensive fast.

What We Needed (and What Exists)

I wrote the requirements on a whiteboard one afternoon and stood back. Time-series ingestion at sustained throughput. Automatic partitioning by time. Compression of old data. Retention policies that don't involve cron. Spatial queries on a sphere. Full-text search. Relational joins. And ideally, something I could operate without a dedicated DBA. Looking at the list, I remember thinking: this is either one very specific database, or three separate ones duct-taped together.

I spent a week evaluating alternatives. InfluxDB handles time-series beautifully but its spatial support was experimental, living in Flux — which is now being deprecated in InfluxDB 3.0, taking the geo package with it. ClickHouse kept coming up in benchmarks but the operational overhead scared me, and PostGIS isn't an option there. MongoDB we already knew about.

TimescaleDB is PostgreSQL with a time-series engine bolted on at a level deep enough that it feels native. And because it is PostgreSQL, you get PostGIS for spatial queries, H3 for hexagonal indexing, GIN indexes for full-text search, and nearly thirty years of battle-tested relational database engineering. Turns out we didn't need three databases duct-taped together. We needed one.

We chose it. Then we had to figure out what "time-series thinking" actually means in practice.

Sounds interesting? Check out TimescaleDB →

Data With a Shelf Life

The central abstraction in TimescaleDB is the hypertable. From the outside, it looks like a regular PostgreSQL table. You INSERT into it, you SELECT from it, you index it. But underneath, the data is automatically partitioned into chunks — contiguous slices of time, each stored as a separate physical table.

I didn't appreciate how much this changes until I stopped thinking about storage and started thinking about expiry.

Our vessel_positions hypertable uses 1-hour chunks. That means every hour of AIS data lives in its own self-contained partition. When we set a 78-hour retention policy, TimescaleDB doesn't scan through millions of rows looking for old records to delete — it just drops the chunks that have aged out. The entire partition disappears. It takes milliseconds.

16.5 million vessel positions, 78-hour retention, 1-hour chunks. The table is always roughly the same size, no matter how long the system runs.

Compression works the same way. After a chunk is two hours old — meaning we're no longer actively writing to it — TimescaleDB compresses it automatically. We segment the compression by MMSI (the vessel's radio identifier, broadcast in every AIS message) and order by timestamp descending. This means "give me the latest position for vessel X" can be answered from the compressed data without decompressing the entire chunk. The storage savings are substantial; the performance improvement for time-range queries is even better, because the query planner knows which chunks to skip entirely.

ALTER TABLE vessel_positions SET (
    timescaledb.compress,
    timescaledb.compress_segmentby = 'mmsi',
    timescaledb.compress_orderby = 'timestamp DESC'
);
SELECT add_compression_policy('vessel_positions', INTERVAL '2 hours');

In MongoDB, I had a cron job that ran a cleanup script every few hours. It failed silently for a week once and nobody noticed until disk usage alerted. In TimescaleDB, we just declare the retention policy and the database handles expiry itself. One fewer thing running at 3 AM that I have to worry about.

The Hexagon Problem

Here's a question that sounds simple: find all vessels within 100 kilometers of a given point.

PostGIS can answer this. You create a GIST spatial index on your geometry column, and the function ST_DWithin will find every point within a given distance. Under the hood, it uses the spatial index to eliminate obvious non-candidates via bounding box checks, then computes exact distances for the rest. It works. It's well-engineered.

But when your table has 16 million rows and new ones arrive at 12,000 per minute, "it works" isn't quite enough. The GIST index is good, but it still has to traverse a tree structure built on geometry — bounding boxes nested inside bounding boxes. For high-volume tables with constant inserts, this gets heavy.

So we added a layer in front of it. And that layer is made of hexagons.

H3 is a spatial indexing system originally developed at Uber for matching riders to drivers. It tiles the entire surface of the Earth with hexagons at multiple resolutions — coarser at low resolutions, finer at high ones. Every point on the planet falls inside exactly one hexagon at each resolution level, and each hexagon has a unique integer identifier.

We use resolution 5, where each hexagon has an edge length of roughly 9 kilometers and an area of roughly 253 square kilometers. The entire Earth is covered by about 2 million of these cells. Every vessel position, when it's inserted, gets a computed H3 cell stored alongside it:

h3_cell_res5 H3INDEX GENERATED ALWAYS AS (
    h3_lat_lng_to_cell(location::point, 5)
) STORED

That STORED keyword matters. The H3 cell is computed once, at insert time, and written to disk as an integer. No recalculation needed at query time. And because it's an integer, we can slap a plain B-tree index on it — the simplest, fastest index PostgreSQL knows how to build.

Now, when someone asks for vessels within 100 kilometers of a point, the query doesn't go straight to the spatial index. First, we compute which H3 cells overlap the search area — a quick geometric calculation that returns a handful of integer IDs. Then we filter the table to only rows matching those cell IDs, using the B-tree index. Integer equality. Blazing fast. This turns 16 million candidate rows into a few thousand.

Then PostGIS takes over, running ST_DWithin on the survivors for exact distance calculations. A few thousand rows through a precise spatial filter is trivial.

-- Stage 1: H3 pre-filter (integer comparison, B-tree)
h3_cell_res5 = ANY(ARRAY(
    SELECT h3_grid_disk(h3_lat_lng_to_cell(ST_MakePoint($1,$2)::point, 5), $6)
))
-- Stage 2: PostGIS exact filter (geometry, GIST)
AND ST_DWithin(location, ST_SetSRID(ST_MakePoint($1,$2), 4326)::geography, $3)
-- Stage 3: TimescaleDB chunk pruning (time range)
AND timestamp BETWEEN $4 AND $5

Three layers of filtering, each narrowing the candidate set for the next: H3 knocks it down from millions to thousands, PostGIS from thousands to hundreds, and chunk exclusion keeps you from scanning data outside the time window entirely.

Why hexagons, specifically? Because hexagons are the only regular polygon that tiles a plane with uniform adjacency — every neighbor shares an edge, and the distance from center to center is the same in every direction. Squares have diagonal neighbors that sit further away than edge neighbors, which distorts distance calculations. For spatial proximity queries, hexagons give you the least distortion. Uber didn't invent this insight — anyone who's looked at a honeycomb has seen it — but they did build a production-grade library around it.

We tried resolution 4 first. The cells were too big — a single cell covered so much ocean that the pre-filter wasn't filtering much. Resolution 6 was better spatially but generated too many cells per query, and the B-tree had to check them all. Resolution 5 was the one where a 100-kilometer radius query overlapped a manageable number of cells while still meaningfully shrinking the candidate set. We benchmarked it and moved on.

Feeding the Beast

700,000 position reports per hour means roughly 194 inserts per second, sustained. That's not a terrifying number for PostgreSQL — a well-tuned instance can handle far more — but the naive approach still hurts. Individual INSERT statements, each sent as a separate network round trip, spend more time in protocol overhead than actual writing. The database is fast; the network between your application and the database is not.

The obvious answer is PostgreSQL's COPY protocol, which streams raw row data in binary, bypassing the SQL parser entirely. We use it for vessel_eta and cache_ais_messages. But for vessel_positions, we can't. The reason is our own schema: the h3_cell_res5 generated column uses the H3INDEX type, and H3INDEX doesn't implement PostgreSQL's binary I/O functions. The COPY protocol requires binary serialization for every column type in the target table. No binary I/O, no COPY.

So we use pgx.Batch with SendBatch instead — the extended query protocol. It packs hundreds of parameterized INSERT statements into a single network round trip, and PostgreSQL executes them server-side without per-statement overhead. Not as fast as COPY, but an order of magnitude better than individual round trips:

batch := &pgx.Batch{}
for _, p := range positions {
    batch.Queue(
        `INSERT INTO vessel_positions
         (mmsi, imo, vessel_name, latitude, longitude, location,
          timestamp, processed_timestamp, suspected_glitch, ...)
         VALUES ($1, $2, $3, $4, $5,
                 ST_SetSRID(ST_MakePoint($5, $4), 4326),
                 $6, $7, $8, ...)`,
        p.MMSI, imo, p.VesselName,
        p.Latitude, p.Longitude,
        p.Timestamp, p.ProcessedTimestamp,
        p.SuspectedGlitch, /* ... */
    )
}
results := pool.SendBatch(ctx, batch)

Notice that the geometry is computed server-side with ST_SetSRID(ST_MakePoint(...)). I briefly considered pre-computing EWKB in the application to avoid calling a function 700,000 times per hour. But since we were already on SendBatch rather than COPY, and ST_MakePoint is cheap server-side, the optimization wasn't worth the added complexity. Sometimes the schema you designed to make reads fast makes writes slightly harder. I'd make that trade-off again.

The Character That Broke the Ports

When your database speaks JSON but your structs still think in BSON.

Here is a bug that could only exist in a migration.

Our port data comes from two external sources. One is a scraper that crawls MyShipTracking's sitemap and extracts basic port info — name, country, coordinates, UN/LOCODE. The other is the World Port Index, maintained by the US National Geospatial-Intelligence Agency, which provides detailed harbor characteristics: depths, pilotage requirements, tug availability, dozens of operational fields.

Neither source writes directly to the production ports table. Instead, they dump raw JSON documents into staging tables — cache_port_mst and cache_port_wpi — and a consolidation step merges them. MST provides breadth (6,488 ports), WPI provides depth (~3,700 ports with rich metadata). The consolidator joins them on UN/LOCODE and writes the merged result to production. Clean separation of concerns.

After the migration went live, the MST scraper worked perfectly. 6,488 ports in the staging table. But the WPI staging table was empty. Zero rows. The consolidator, finding nothing to merge, produced nothing. The production ports table: empty. And because port events rely on the ports table for UN/LOCODE enrichment, 156,000 port events were created with no geographic identifier. Everything looked healthy from the outside. The data was garbage.

The root cause was one word.

The WPI port struct, a holdover from the MongoDB era, still carried dual serialization tags — something like:

type WpiPort struct {
    UnloCode string `bson:"unlo_code" json:"unloCode"`
    // ...
}

The staging table upsert function works by marshaling each struct to JSON, then extracting a key field by name. The key parameter was "unlo_code" — the BSON tag name, used by MongoDB's driver. But json.Marshal uses the JSON tag: "unloCode". The function looked for a field called unlo_code in the JSON document, found nothing, and returned an error. Not a silent error, technically — the function threw a clear "key field not found" message. But without alerting on the nightly WPI sync job, a returned error that nobody checks is as good as silent. It ran, it failed, it failed again, every night at 1 AM, for days.

The fix was changing one string: "unlo_code" to "unloCode".

But the real fix was broader. I searched the codebase and found nearly 240 leftover bson:"..." tags scattered across the data contract structs. The MongoDB driver wasn't even imported anymore — these tags were pure vestigial code, left over from the old world. Every one of them was a potential version of the same bug: a name from a system that no longer existed, waiting to be confused with a name from the system that did.

I spent two days on this. Two days staring at logs, convinced the WPI API had changed its response format, before I thought to check the struct tags. It's a naming collision between two eras of the same system, and Go is happy to let it happen — struct tags are opaque strings the compiler ignores completely. No linter will save you. You have to notice it yourself, or wait for production to notice it for you.

What the Numbers Look Like

Table	Type	Rows	Notes
vessel_positions	Hypertable	16.5M	~700K/hour, H3 + GIST + B-tree indexes
vessel_eta	Hypertable	—	78h retention, compressed
port_events	Hypertable	156K	Dedup index, UN/LOCODEs empty (pre-fix)
cache_ais_messages	Hypertable	—	Raw AIS buffer, 12h retention
vessels	Regular	~50K	Consolidated from multiple sources
ports	Regular	~6,500	After WPI fix; 0 before
light_aids	Regular	35,237	Navigation infrastructure
dgps_stations	Regular	163	DGPS reference stations
navtex_messages	Regular	~93/day	Deduplicated by content hash

Production table statistics after migration

All of this runs on a single EC2 r7i.large — 2 vCPUs, 16 GB of RAM. I keep expecting to need to upgrade and I keep not needing to. PostgreSQL with the right extensions, doing the work that previously required MongoDB plus a constellation of application-level workarounds for everything MongoDB couldn't do natively.

A bulk carrier transiting a Norwegian fjord — one of roughly 700,000 position reports we process every hour.

What I'd Tell You at a Bar

Look, MongoDB was the right call when we started. I'd choose it again for that stage. The mistake was staying six months too long — past the point where the data had obviously hardened into a shape and we were just too busy to deal with it.

Honestly, moving the data was the easy part. The hard part — the part that's still ongoing — is finding all the places where the old system's assumptions are embedded in the code. A struct tag referencing a serialization format you don't use anymore. A key parameter someone copied from a different struct's bson tag. Those things survive the migration and sit there until they don't.

We're still finding bson tags. Probably will be for a while.

The 946-Millisecond Tax: Migrating API Key Auth from Bcrypt to HMAC-SHA256

VesselAPI — Sun, 10 May 2026 11:56:03 +0000

I never profiled our authentication middleware. Why would I? It's a key check. The request comes in, you verify the key, you move on. It's plumbing. Then one afternoon I stuck a timer on it and watched it print 946 milliseconds. I re-ran it. Same. Every authenticated request to our API was spending nearly a full second deciding whether the caller was allowed in, before it did a single useful thing.

We were hashing API keys with bcrypt. It felt like the right thing to do. It wasn't.

The 100-Millisecond-Per-Key Tax

When VesselAPI's authentication was first built, someone — by someone I mean me, it was me — did the reasonable thing. User creates an API key, we hash it with bcrypt at cost factor 10 and store the hash. On each incoming request, extract the Bearer token, load the stored hashes from PostgreSQL, and run bcrypt.CompareHashAndPassword against each one until a match is found or the list runs out.

Bcrypt is a password hashing function. It was engineered, on purpose, to be slow. That deliberate slowness is its entire value proposition for passwords: if an attacker steals your database full of password hashes, the CPU cost of bcrypt makes brute-force recovery so expensive it's impractical. At cost factor 10, each comparison takes roughly 65–100 milliseconds depending on hardware. For a user logging into a web app once a day, that's invisible. For every single API call, it's a wall.

Here's what compounded it: bcrypt hashes aren't indexable. The function incorporates a random salt, so the same input produces a different hash each time. You can't compute the hash of an incoming key and look it up in the database — you have to load all the stored hashes and compare them one by one. With 11 active keys in production at the time of our migration, the worst case was 11 bcrypt comparisons. Just under 1.1 seconds of pure CPU work before we even said hello to the request.

11 active keys × ~100ms bcrypt = up to 1.1 seconds of authentication.

The health endpoint with no auth ran in 581ms. Authenticated endpoints ran in 1,466ms. We were paying nearly a second for permission to serve the response.

At the traffic volumes we had, this wasn't causing visible degradation. The load test user was doing 94,315 requests in a month but spread across time. The problem wasn't that the system was falling over — it was that it was architecturally incapable of scaling. With 11 keys to check, bcrypt at cost factor 10 limits you to under one authenticated request per second per core. That's not a "tune this later" ceiling. It's a physics ceiling.

Why bcrypt Is the Wrong Tool for API Keys

We grabbed bcrypt because that's what you use for credentials. We never stopped to ask whether API keys are credentials in the same sense passwords are.

Bcrypt's whole thing is being slow on purpose. If someone steals your password database, the cost of each hash attempt is what stands between them and everyone's plaintext passwords. That makes sense for passwords — people pick terrible ones, reuse them, and there are massive precomputed tables for cracking common choices.

API keys are not that. Ours are 256 bits of cryptographically random noise. You'd need something like 2²⁵⁵ guesses to brute-force one. At a billion attempts per second, that's — let me check — longer than the Sun will exist. So what was bcrypt's cost factor actually buying us? Nothing. The keys were already uncrackable. We were paying 100 milliseconds per request for protection against a threat that doesn't apply.

The real risk with API keys is leakage: someone commits one to a public repo, or it shows up in a log file, or a compromised client exfiltrates it. Bcrypt doesn't help with any of those. What helps is a fast, deterministic hash — something you can index — plus a server-side secret protecting the stored hashes.

So we use a pepper — a server-side secret. We compute HMAC-SHA256 over the API key using a 64-character random secret stored in AWS Secrets Manager. The stored value is the HMAC output, not the key. An attacker with the database still needs the pepper from Secrets Manager to do anything with those hashes — a completely separate security boundary. And HMAC-SHA256 takes about a microsecond to compute, not a hundred milliseconds.

// Before: bcrypt load-and-compare-all (O(n) * 100ms per key)
for _, stored := range allKeyHashes {
    if err := bcrypt.CompareHashAndPassword([]byte(stored), []byte(apiKey)); err == nil {
        return stored, nil
    }
}

// After: HMAC + indexed lookup (O(1), ~1μs + one DB round trip)
mac := hmac.New(sha256.New, []byte(pepper))
mac.Write([]byte(apiKey))
keyHMAC := hex.EncodeToString(mac.Sum(nil))
return db.VerifyApiKeyHMAC(keyHMAC) // indexed lookup, <1ms

Replacing bcrypt with HMAC alone got auth overhead from ~946ms to ~811ms. Better, but not the kind of better you write a blog post about. Most of that remaining time was network round trips to PostgreSQL — the hash was fast, the wire wasn't. So we kept going.

Zero Database Queries on the Hot Path

I'll spare you the detour where I briefly considered Redis before realizing I was optimizing a 17-key lookup and needed to calm down. The cache design we landed on is simple. Two sync.Map instances live in the auth service: keyCache maps HMAC hashes to key metadata, and userCache maps user IDs to subscription and quota information. When both are populated, an authenticated request never touches the database.

Before: Every Request

Extract Bearer token
DB: load all key hashes
bcrypt.CompareHashAndPassword (each key, ~100ms)
DB: check per-key quota
DB: increment per-key usage counter
3–4 round trips, up to 1.1s of CPU

After: Steady State (cache warm)

Extract Bearer token
HMAC-SHA256 with pepper (~1µs)
sync.Map lookup: keyCache (tens to hundreds of ns)
atomic.AddInt64: local counter (~25ns)
Memory check: usage < limit? (nanoseconds)
Zero database queries

The usage tracking is worth a closer look, because it's where the real database write elimination happens. In the old system, every authenticated request incremented a per-key counter in PostgreSQL. That's a write on the hot path, with all the associated row contention and WAL traffic. Now, we increment a local int64 via atomic.AddInt64 and a background goroutine wakes up every 30 seconds, atomically swaps all the counters to zero, and flushes the totals to the database in a single batch call.

// Simplified — the real flush iterates userCache, where the counter
// lives alongside quota metadata in each cached entry.
func (r *cachedAuthRepository) flush() {
    r.userCache.Range(func(k, v any) bool {
        entry := v.(*userEntry)
        count := atomic.SwapInt64(&entry.localUsageCount, 0)
        if count > 0 {
            // accumulate for batch DB write
        }
        return true
    })
    // single batch call to update all user usage counts
}

Usage numbers can be up to 30 seconds stale, which is fine for monthly quota enforcement but worth understanding. We added one safeguard: when the in-memory counter says a user has exceeded their quota, we do a fresh database lookup before returning 429. This handles plan upgrades — if someone bumps from Starter to Growth mid-session, the cache still thinks their limit is 2,500 until the next DB refresh, so they'd incorrectly hit a wall. The fallback catches it. It adds one DB round trip at the moment that matters most, which is the right trade-off.

We also fixed something embarrassing while we were in there. The old quota model tracked usage per-key, not per-user. Each key had its own counter and its own limit. Which meant that a user who created three keys got three times the quota. Nobody exploited this, as far as I know, but only because nobody thought to try. We were one curious developer away from an unlimited plan at the price of a free tier and some creativity. Seventeen keys across seven users — early days — so nobody noticed. Per-user counters now. Should have been from day one.

The Lazy Migration

We had 17 API keys in production on migration day. A one-off script to backfill HMAC hashes for all of them would have taken about ten minutes to write and thirty seconds to run. We did the lazy migration instead, and I think it was worth the extra complexity.

Why not just run a backfill script? We could have. It would have taken thirty seconds. But then the bcrypt fallback path — which we wrote, and which we'd need if anything went wrong — would never get exercised in production until the one time it actually matters. With lazy migration, every old key that gets used proves the fallback works. It's testing in prod, but the honest kind.

The flow goes like this. Compute the HMAC of the incoming key. Check the cache — miss. Check the database for a matching key_hmac value — miss, because old keys don't have one yet. Fall through to bcrypt, verify against the old hash, succeed. Now kick off an async HMAC backfill, populate the cache, serve the request. Next time that key shows up, it hits the HMAC path directly and never touches bcrypt again.

// Simplified — real signatures differ slightly
hmacHex := computeHMAC(pepper, apiKey)

// 1. Cache (warm path)
if cached, ok := keyCache.Load(hmacHex); ok {
    return cached.(*keyEntry), nil
}

// 2. HMAC indexed lookup (migrated keys)
if key, err := db.VerifyApiKeyHMAC(hmacHex); err == nil {
    keyCache.Store(hmacHex, key)
    return key, nil
}

// 3. Bcrypt fallback (un-migrated keys, once per key)
keyID, err := db.VerifyApiKey(apiKey)
if err != nil {
    return nil, ErrUnauthorized
}

entry := loadKeyEntry(keyID)
go func() {
    if err := db.BackfillHMAC(keyID, hmacHex); err != nil {
        log.Error("hmac backfill failed", "key_id", keyID, "error", err)
    }
}()
keyCache.Store(hmacHex, entry)
return entry, nil

New keys created through the API key manager get their HMAC computed at creation time and never touch the bcrypt path at all. The lazy path is there for the legacy keys, and once they've each been used once, it's never exercised again.

Need vessel data? Check out VesselAPI →

The Rollout

It took three deployment attempts on February 7th. Wrong Secrets Manager config format, then a fix baked into an AMI that hadn't propagated yet, then a missing IAM permission in a different repo. Standard infrastructure bingo. On the third try the server started, we hit /v1/health with a Bearer token, got 200 OK, and briefly celebrated — before realizing the health endpoint doesn't use auth. We'd validated our new authentication system against the one endpoint that skips it. Hit /v1/vessel/{id} instead, watched the bcrypt fallback fire, watched the HMAC backfill, hit it again — sub-10ms. That one counted.

What the Numbers Actually Look Like

Production measurements from February 7th, network overhead stripped out:

Scenario	DB Queries	Auth Overhead
Bcrypt fallback, cold cache	4	~946ms
HMAC lookup, cold cache	2	~811ms
Cache hit	0	<10ms

Under 10 milliseconds with a warm cache. Zero database queries. The auth overhead went from being the dominant cost of every request to being lost in the measurement noise.

Throughput ceiling with bcrypt and 11 keys: under 1 authenticated request per second per core. With HMAC and a cache, authentication is no longer the bottleneck for anything.

The Trade-offs Worth Naming

What changed beyond "it got faster":

The security model is different. With bcrypt, even if you have the database, you can't reverse the hashes. With HMAC, if you get both the database and the pepper, you can verify candidate keys. Our keys have enough entropy that this doesn't matter in practice, but it's a weaker property and I'd rather be upfront about it.

Usage numbers can be stale by up to 30 seconds. A user could overshoot their quota slightly before the flush catches it. At monthly limits measured in thousands, I genuinely don't care. If we ever need per-second rate limiting, we'd use Redis, not this.

There's also a concurrency wrinkle I should own up to: the usage counter itself is atomic, but the dbUsageCount and monthlyLimit fields on the same struct are plain int values read and written without synchronization. Multiple goroutines can read stale values, and worse, the quota-refresh path writes those fields directly on the shared struct without a lock — two concurrent refreshes could clobber each other. I think this is fine at our scale. I'm not entirely sure it's fine. It probably needs a mutex, and I'll probably add one the next time I'm in that file and feeling responsible.

The cache entries do have a TTL — both key and user entries expire after a configured duration, and the lookup re-fetches from the database when they go stale. But there's no active invalidation push. If you revoke a key, it stays valid in memory until that TTL window elapses. At current scale — 17 keys, 7 active users — this is the trade-off that actually kept me up at night, more than the others. We'll add a revocation broadcast before we onboard any enterprise customers. For now, the TTL window is short enough that I can live with it.

Two weeks after migration day, all 17 pre-existing keys have been lazily migrated. New keys get HMAC on creation. The bcrypt fallback path exists in the code and will presumably never run again, but I'm not ready to remove it yet. It's not hurting anyone, and the fallback existing is a different kind of insurance than the fallback being needed.

The performance improvement worked like the math said it would. What I didn't expect was how many other things the migration shook loose — the per-key quota bug, the stale schema assumptions in other services, the concurrency shortcuts we'd been getting away with. You open up one table and suddenly you're looking at every decision you made in the first six months and wondering which ones are still load-bearing. Some of them weren't. Some of them still are.

Self-Hosted Vessel Email Alerts with AWS Lambda and SES

VesselAPI — Wed, 06 May 2026 12:29:45 +0000

The thing you actually want is an email.

Not a dashboard you have to remember to open. Not a webhook you have to write a server for. An email — the kind your bank sends when a charge clears, the kind your airline sends when the gate changes — that quietly arrives in your inbox and tells you the Ever Given just entered Suez, or that one of your chartered tankers' ETA has shifted by six hours.

VesselAPI sends notifications as webhooks and WebSocket messages. That's the right contract for software, the wrong contract for humans. Webhooks are how systems talk. Email is how systems talk to people. The translation layer between them — the thing that turns a webhook stream into vessel port arrival departure email notifications, the sort of thing your inbox already knows how to thread, sort, and search — is small enough to read in one sitting, which is what this post is.

You'll want these installed before starting:

AWS CLI — for SES identity verification and CloudWatch log reads.
AWS SAM CLI — builds and deploys the stack.
Python 3.12 — matches the Lambda runtime; needed if you want to run the example repo's test suite locally.
AWS credentials configured for your target region (aws configure or env vars).
A VesselAPI key on a plan that includes notifications (see the pricing CTA below).

🤖 Setup with Claude Code

Or paste this into a Claude Code session and let it sort the local toolchain out:
check whether the AWS CLI, AWS SAM CLI, and Python 3.12 are installed, and that my AWS credentials are configured for us-east-1 — install or fix anything that's missing

Full source for this post: vessel-api/vessel-email-alerts-aws-sam on GitHub →

The Architecture in One Diagram

vesselapi notification
   |  POST  (HMAC-signed JSON)
   v
API Gateway (HTTP API)
   v
Lambda
   |-- verify HMAC signature
   |-- DynamoDB: have we seen this delivery_id before?
   |-- render email (per event type)
   `-- SES: SendEmail
   v
Your inbox

Five components:

API Gateway HTTP API is the public URL VesselAPI POSTs to. The HTTP API flavor (not REST API) is roughly a third of the price and supports everything we need for one route.
Lambda does the work: verify, deduplicate, render, send.
DynamoDB stores delivery IDs we've already processed so retries from VesselAPI don't double-send. One row per event, 24-hour TTL.
SES sends the mail.
IAM glues the function's permissions together.

The function only runs when a webhook arrives, and at idle the whole thing costs zero.

A note before we start: the events VesselAPI emits — port arrival, port departure, ETA changed, geofence enter/exit — are derived from AIS, not ground truth. AIS-reported destinations and ETAs are entered by the bridge and are sometimes stale, abbreviated ("FOR ORDERS"), or misspelled. Geofence events apply hysteresis to avoid edge-flapping, but you'll still see the occasional false positive — a vessel drifting past a polygon edge in a busy anchorage, a duplicate broadcast from two coastal stations, an ETA tweak that flips back two minutes later. Worth knowing if you're tuning thresholds for an operational workflow; for "tell me when this ship enters that port," the defaults are fine.

Need a VesselAPI key? See the pricing & plans →

Step 1: Verify an Email Address in SES

🤖 Doing it with Claude Code

Skip the console. Ask:
verify the SES identity me@example.com in us-east-1, then poll until it's confirmed
Claude runs aws ses verify-email-identity, then loops on aws ses get-identity-verification-attributes until the status flips to Success.

In the SES console, pick your region (we'll use us-east-1 throughout — change to taste), open Verified identities, click Create identity, and create an Email address identity. AWS sends a confirmation email; click the link.

That's it. We're using a verified email identity rather than a domain because it's instant — no DNS to wait on. For production you'll want a domain identity with DKIM, but for alerts to your own inbox an email identity is fine.

Step 2: Scaffold the Project

The project layout:

vessel-email-alerts/
├── template.yaml
└── src/
    ├── handler.py
    ├── render.py
    └── requirements.txt

requirements.txt is empty — boto3 ships with the Lambda Python runtime, and we're not pulling in a templating library. Plain f-strings handle this.

Here's handler.py in full:

import os
import json
import hmac
import hashlib
import base64
import logging
import boto3
from datetime import datetime, timezone, timedelta
from botocore.exceptions import ClientError

from render import render_email

logger = logging.getLogger()
logger.setLevel(logging.INFO)

# Module-scope clients are reused across warm invocations -- one TLS
# handshake per container, not one per request.
ses = boto3.client("ses")
ddb = boto3.client("dynamodb")

WEBHOOK_SECRET = os.environ["WEBHOOK_SECRET"].encode()
TO_ADDRESS = os.environ["TO_ADDRESS"]
FROM_ADDRESS = os.environ["FROM_ADDRESS"]
IDEMPOTENCY_TABLE = os.environ["IDEMPOTENCY_TABLE"]


def lambda_handler(event, _context):
    headers = {k.lower(): v for k, v in (event.get("headers") or {}).items()}
    raw = event.get("body") or ""
    body: bytes = (
        base64.b64decode(raw) if event.get("isBase64Encoded") else raw.encode("utf-8")
    )

    if not _verify_signature(body, headers.get("x-signature-256", "")):
        return _resp(401, "invalid signature")

    delivery_id = headers.get("x-delivery-id")
    if not delivery_id:
        return _resp(400, "missing X-Delivery-ID")

    if not _claim_delivery(delivery_id):
        # Already processed -- ack so vesselapi stops retrying.
        return _resp(200, "duplicate")

    payload = json.loads(body)
    evt = payload["event"]
    subject, html, text = render_email(evt)

    try:
        ses.send_email(
            Source=FROM_ADDRESS,
            Destination={"ToAddresses": [TO_ADDRESS]},
            Message={
                "Subject": {"Data": subject},
                "Body": {
                    "Html": {"Data": html},
                    "Text": {"Data": text},
                },
            },
        )
    except Exception:
        # Release the claim so the next retry can try again. Without this,
        # any SES failure would silently lose the email.
        _release_delivery(delivery_id)
        raise

    return _resp(200, "sent")


def _verify_signature(body: bytes, sig_header: str) -> bool:
    if not sig_header.startswith("sha256="):
        return False
    expected = sig_header[len("sha256="):]
    mac = hmac.new(WEBHOOK_SECRET, body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, expected)


def _claim_delivery(delivery_id: str) -> bool:
    ttl = int((datetime.now(timezone.utc) + timedelta(hours=24)).timestamp())
    try:
        ddb.put_item(
            TableName=IDEMPOTENCY_TABLE,
            Item={
                "delivery_id": {"S": delivery_id},
                "expires_at": {"N": str(ttl)},
            },
            ConditionExpression="attribute_not_exists(delivery_id)",
        )
        return True
    except ClientError as e:
        if e.response["Error"]["Code"] == "ConditionalCheckFailedException":
            return False
        raise


def _release_delivery(delivery_id: str) -> None:
    try:
        ddb.delete_item(
            TableName=IDEMPOTENCY_TABLE,
            Key={"delivery_id": {"S": delivery_id}},
        )
    except ClientError as e:
        logger.error("failed to release claim (delivery_id=%s): %s", delivery_id, e)


def _resp(status: int, body: str):
    return {"statusCode": status, "body": body}

About a hundred lines, abridged a little for the post — the version in the example repo also has structured logging on every branch and a try/except around the JSON parse that returns 400 for malformed bodies. Two lines above are the load-bearing ones: the compare_digest call and the _release_delivery call. They're the difference between a pipeline that's fine on the happy path and one that survives the unhappy paths. We'll come back to both.

And render.py. There's one renderer per event type and a small dispatcher. Three of the seven for shape — port arrival, ETA change, and the generic fallback:

from datetime import datetime


def render_email(evt: dict):
    handler = _RENDERERS.get(evt["type"], _render_generic)
    return handler(evt)


def _vessel_label(v: dict) -> str:
    name = v.get("vesselName") or "Unknown vessel"
    imo = v.get("imo")
    return f"{name} (IMO {imo})" if imo else name


def _fmt_time(iso: str) -> str:
    try:
        return datetime.fromisoformat(iso.replace("Z", "+00:00")).strftime("%Y-%m-%d %H:%M UTC")
    except Exception:
        return iso


def _render_port_arrival(evt):
    v = _vessel_label(evt["vessel"])
    port = evt["data"]["portEvent"]["port"]
    when = _fmt_time(evt["timestamp"])
    subject = f"{v} arrived at {port['name']}"
    text = f"{v} arrived at {port['name']}, {port.get('country', '')} on {when}."
    html = f"<p><strong>{v}</strong> arrived at <strong>{port['name']}</strong>.</p><p>Reported {when}.</p>"
    return subject, html, text


def _render_eta_changed(evt):
    v = _vessel_label(evt["vessel"])
    change = evt["data"]["etaChange"]
    prev = _fmt_time(change["previousEta"])
    cur = _fmt_time(change["currentEta"])
    shift = change["shiftMinutes"]
    subject = f"{v} ETA shifted by {shift} min"
    text = f"{v} ETA changed: {prev} -> {cur} (shift: {shift} minutes)."
    html = f"<p><strong>{v}</strong> ETA shifted by {shift} minutes.</p><p>Previous: {prev}<br>Current: {cur}</p>"
    return subject, html, text


def _render_generic(evt):
    v = _vessel_label(evt["vessel"])
    subject = f"{v}: {evt['type']}"
    body = f"{evt['type']} event for {v} at {_fmt_time(evt['timestamp'])}."
    return subject, f"<p>{body}</p>", body


_RENDERERS = {
    "port.arrival": _render_port_arrival,
    "port.departure": _render_port_departure,        # same shape as arrival
    "eta.eta_changed": _render_eta_changed,
    "eta.destination_changed": _render_destination_changed,
    "position.geofence_enter": _render_geofence,
    "position.geofence_exit": _render_geofence,
}

The other four renderers (departure, destination changed, draught changed, geofence) follow the same shape — pull the relevant fields from evt["data"], format them, return a (subject, html, text) triple. The structure that scales is the dispatcher dict; adding a Slack or Teams channel later is the same pattern with a different output format.

The Two Non-Obvious Parts

It would be tempting to skim past two of those lines. They're the lines that decide whether this thing works or quietly turns into a problem in three months.

HMAC Verification, and Why `hmac.compare_digest`

Every VesselAPI webhook arrives with an X-Signature-256 header: sha256= followed by the hex of HMAC-SHA256(webhook_secret, raw_request_body).

The instinct is to skip this. The Lambda is on HTTPS. The URL is unguessable. Why bother? Because the URL leaks. It ends up in CloudWatch logs, in someone's terminal scrollback, in screenshots, in an AWS console somebody screen-shared on a call. Anyone who knows the URL can POST a fake event to it. Without verification, your inbox is now a free email-sending service for whoever finds it.

The verification is two lines:

mac = hmac.new(WEBHOOK_SECRET, body, hashlib.sha256).hexdigest()
return hmac.compare_digest(mac, expected)

The reason it's hmac.compare_digest and not == is the load-bearing detail of this whole post. A naive == short-circuits at the first byte mismatch — meaning the comparison is faster when the strings differ early, slower when they differ late. That timing difference is enough for an attacker to recover the signature one byte at a time, given enough requests. compare_digest always takes the same amount of time regardless of where the strings diverge. Use it.

One byte-handling note: keep body as bytes end-to-end. hmac.new wants bytes, json.loads accepts bytes, and skipping the decode()/encode() round-trip saves you from a class of bugs that only show up when the webhook source ever sends non-UTF-8 content.

Idempotency, and What Happens When SES Fails

VesselAPI retries failed webhook deliveries with exponential backoff. That's a feature: a transient Lambda timeout doesn't lose the event. It's also a problem: the same event can arrive at your Lambda more than once, and without protection you'll send the same email twice. Or three times. Or thirteen.

Every webhook arrives with a unique X-Delivery-ID. We use it as the primary key in a small DynamoDB table with a conditional put: if the row already exists, the put fails atomically, we return 200, and no email goes out. The 24-hour TTL means the table never grows.

We return 200 for duplicates rather than an error. If we returned an error, VesselAPI would retry, the put would fail again, we'd return another error, and we'd loop forever. Returning 200 says "I've handled this," and the chain stops.

The trap, which is easy to fall into and tempting to call "good enough": claim the delivery ID and then call SES. If SES throws — throttle, transient 5xx, suppression-list hit — the claim is now sitting in DynamoDB with no email behind it. The next retry from VesselAPI looks up the delivery ID, finds the row, returns 200 duplicate, and the email is silently lost forever. That's the failure mode _release_delivery exists for: on any SES exception, delete the claim row and re-raise so the retry reaches a fresh slate.

The release itself can also fail (DynamoDB throttling, tiny window, very unlucky). When that happens we log loudly and let the original SES error propagate — the retry will be ack'd as a duplicate this once, but the failure is visible in CloudWatch instead of vanishing into the gap between two AWS services. The unit test for the whole sequence lives in test_handler.py in the example repo — it's the case that catches the bug if you ever refactor the order of those two calls.

Step 3: Deploy with SAM

🤖 Doing it with Claude Code

In the example repo, ask:
deploy this stack with my SES identity me@example.com and a fresh webhook secret
Claude generates the secret with openssl rand -hex 32, runs sam build and sam deploy --guided, and reads the WebhookUrl back to you.

Drop template.yaml next to src/:

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: Self-hosted vessel email alerts (vesselapi -> Lambda -> SES)

Parameters:
  WebhookSecret:
    Type: String
    NoEcho: true
    Description: The secret you'll configure on the vesselapi notification.
  ToAddress:
    Type: String
    Description: Verified SES recipient (the inbox the alerts go to).
  FromAddress:
    Type: String
    Description: Verified SES sender identity.

Resources:
  IdempotencyTable:
    Type: AWS::DynamoDB::Table
    Properties:
      BillingMode: PAY_PER_REQUEST
      AttributeDefinitions:
        - AttributeName: delivery_id
          AttributeType: S
      KeySchema:
        - AttributeName: delivery_id
          KeyType: HASH
      TimeToLiveSpecification:
        AttributeName: expires_at
        Enabled: true

  EmailSenderFunction:
    Type: AWS::Serverless::Function
    Properties:
      Runtime: python3.12
      Handler: handler.lambda_handler
      CodeUri: ./src
      Timeout: 10
      MemorySize: 256
      Environment:
        Variables:
          WEBHOOK_SECRET: !Ref WebhookSecret
          TO_ADDRESS: !Ref ToAddress
          FROM_ADDRESS: !Ref FromAddress
          IDEMPOTENCY_TABLE: !Ref IdempotencyTable
      Policies:
        - DynamoDBCrudPolicy:
            TableName: !Ref IdempotencyTable
        - Statement:
            - Effect: Allow
              Action: ses:SendEmail
              Resource: !Sub 'arn:aws:ses:${AWS::Region}:${AWS::AccountId}:identity/${FromAddress}'
      Events:
        Webhook:
          Type: HttpApi
          Properties:
            Path: /webhook
            Method: post

Outputs:
  WebhookUrl:
    Description: Paste this into your vesselapi notification's webhook_url.
    Value: !Sub 'https://${ServerlessHttpApi}.execute-api.${AWS::Region}.amazonaws.com/webhook'

Function, API, table, IAM role, log group — about fifty lines of YAML. The equivalent Terraform is noticeably more verbose because it has to express each resource individually instead of leaning on AWS::Serverless::Function's built-in defaults. NoEcho: true keeps the secret out of CloudFormation outputs and the AWS console; the env-var value is still readable to anyone with lambda:GetFunctionConfiguration, which is the usual tradeoff and the reason the production checklist below moves it to Secrets Manager. The ses:SendEmail policy is scoped to the verified FromAddress identity ARN — a compromised function role can't be used to send mail from other identities in the account.

Build and deploy:

sam build
sam deploy --guided \
  --parameter-overrides \
    WebhookSecret=<some-long-random-string> \
    ToAddress=you@example.com \
    FromAddress=you@example.com

--guided walks you through stack name, region, and the IAM confirmation. Pick us-east-1, accept the IAM prompt, and let it run. About 90 seconds later:

Outputs
-----------------------------------------
Key           WebhookUrl
Value         https://abc123xyz.execute-api.us-east-1.amazonaws.com/webhook

Save the URL. For the secret, openssl rand -hex 32 is a sensible default — use the same value for both the SAM parameter and the VesselAPI notification config below.

Step 4: Register the Webhook with VesselAPI

🤖 Doing it with Claude Code
register a vesselapi webhook for IMO 9811000 pointing at the WebhookUrl from the last deploy, use the same secret
Claude pulls the URL out of the SAM stack output, reuses the secret, and POSTs the notification config.

curl -X POST https://api.vesselapi.com/v1/notifications \
  -H "Authorization: Bearer $VESSELAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "lambda-email-alerts",
    "imos": [9811000],
    "event_types": ["port.arrival", "port.departure", "eta.eta_changed"],
    "webhook_url": "https://abc123xyz.execute-api.us-east-1.amazonaws.com/webhook",
    "webhook_secret": "<the same secret you passed to SAM>"
  }'

9811000 is the IMO of the Ever Given itself — handy if you want a vessel that moves often and is easy to recognise in your inbox while you verify the pipeline. Swap in the IMOs you actually want to watch. The event_types filter is optional; omit it to get every event type for the watched vessels.

Step 5: Send a Test Event

🤖 Doing it with Claude Code
fire a test event at the lambda-email-alerts notification and tail the CloudWatch logs until it reports sent
Claude hits the test endpoint, follows the log stream, and stops when it sees the success line — or the error line, with a translation of what's actually wrong.

VesselAPI exposes a test endpoint that fires a synthetic event through your full delivery path:

curl -X POST https://api.vesselapi.com/v1/notifications/<id>/test \
  -H "Authorization: Bearer $VESSELAPI_KEY"

A few seconds later, the email should be in your inbox.

When It Doesn't Work the First Time

🤖 Doing it with Claude Code
read the last 5 minutes of CloudWatch logs for the EmailSenderFunction and tell me what's failing
Claude pulls the log stream and surfaces the relevant error — usually one of the two below, before you've finished asking.

It usually doesn't. Two things go wrong on first deploy, in roughly this order:

MessageRejected: Email address is not verified — SES is in sandbox and either the FromAddress or ToAddress isn't a verified identity. Verify both, retry. If you used the same email for both, you only need to verify it once.
invalid signature in the Lambda logs — the secret in the SAM parameter doesn't match the one in the VesselAPI notification. They have to be byte-for-byte identical, including no trailing newlines.

Check the CloudWatch log group at /aws/lambda/<stack-name>-EmailSenderFunction-<hash>.

What This Costs

For a single user with ten watched vessels and a few events a day, in us-east-1 as of April 2026:

Service	Volume	Cost
API Gateway HTTP API	~100 req/mo	$0.0001
Lambda	well inside free tier	$0
DynamoDB pay-per-request	~100 writes/mo	$0.0001
SES	100 emails/mo	$0.01
CloudWatch logs	small	pennies

Total: a few cents to a dollar a month, dominated by SES if you send a lot. Idle cost is zero. AWS prices drift; check the current rates if you scale this beyond personal use.

Going to Production

The deploy above is the right shape for "alerts to my own inbox." For anything wider, four changes — each incremental, none of which break the pipeline above:

Move out of SES sandbox. Request production access in the SES console; AWS Support's initial response usually arrives within 24 hours, full approval can take longer.
Verify a domain identity with DKIM. Send From: alerts@yourdomain.com and have it display as authenticated rather than as a generic AWS noreply.
Wire up bounce and complaint handling. Attach an SES Configuration Set and route Bounce and Complaint events to an SNS topic. A single typo'd ToAddress can otherwise quietly land you on the SES suppression list.
Move the webhook secret to Secrets Manager. A small SAM change; the function reads it on cold start and caches it.

A future post will go deep on each of these. For now, the pipeline you have is sufficient.

Common Questions

How can I receive automatic email alerts when a vessel enters or leaves a port?

Subscribe to VesselAPI's port-event webhook, point it at an AWS Lambda function, and have Lambda format the event and send it via Amazon SES. The result is an email in your inbox each time a tracked vessel arrives at or departs from a port — no dashboard polling and no extra server.

What's the difference between maritime email alerts and API-based vessel monitoring?

API-based monitoring gives your software a stream of events to process programmatically — useful for dashboards, fleet analytics, or automated triggers. Email alerts translate that same stream into something a human reads in their inbox, and are best when one or two people need passive awareness of specific vessels rather than a full dashboard. The two are layers, not alternatives: the API is what your systems react to, the email is what a human reads at 2am.

How much does it cost to run vessel email alerts on AWS Lambda?

For a typical fleet of a few dozen vessels generating tens of port events per day, the cost is essentially zero — well within the AWS Lambda and SES free tiers. Even at 1,000 alerts per month, the total monthly cost is well under one US dollar. See the cost breakdown above for the line items.

Do I need a server to receive vessel email alerts?

No. The pipeline runs entirely on AWS Lambda (serverless) with SES for email delivery and DynamoDB for idempotency. There is no long-running server to provision or maintain.

How do I prevent duplicate emails when AWS retries a webhook?

Use DynamoDB with the webhook event ID as the partition key and a conditional PutItem to deduplicate. If the conditional put fails because the row already exists, return success to the webhook caller without sending the email.

Can I set up alerts for multiple vessels at once?

Yes. Register each vessel as a separate watcher through the VesselAPI dashboard or pass a list of MMSIs to the bulk-subscription endpoint. The same Lambda and SES pipeline serves all of them — the per-vessel cost is negligible.

What Comes Next

This is part 1 of a series on building your own notification consumers on top of VesselAPI webhooks. Part 2 keeps the same Lambda, the same HMAC verify, the same DynamoDB idempotency — and swaps the email renderer for Slack Block Kit, Microsoft Teams Adaptive Cards, or Discord embeds. The dispatcher pattern in render.py is the seam to plug those in: one function per channel, one config flag to pick which one runs.

People often treat maritime email alerts vs API-based vessel monitoring as a choice. They aren't — they're layers. The API integration is the thing your services react to. The email pipeline above it is what a human reads at 2am. Now your inbox knows when your ships move.

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.