Two Ports,
4.5 Nautical Miles Apart.

On the homepage we say we are not going to explain how the route engine works. That is true there. This is not there. Grab a coffee, because we are about to explain exactly how it works, including the parts we got wrong before we got them right.

Two ports, one very wrong route

Batu Ampar and Sekupang are two real ports in Batam. By straight line, they sit 4.5 nautical miles apart. A short hop. But a route on the water has to go around real land, not through it, so the system needs to trace an actual sea path between them, not just measure the distance on a map.

Here is what our engine used to do with that request. It drew a route through a waypoint 112 nautical miles away. A 227 nautical mile round trip for what should have been a short crossing. Worse, it came back marked as a successful route, with no problems flagged. Nothing in the result said "this looks wrong."

Zero nautical miles, one cell. That is what our routing map thought the distance was between two real ports, because they had collapsed onto the exact same patch of water on the map, even though a boat crosses the real gap between them in minutes.

Why sea routes are harder than they look

Routing at sea sounds like routing a car. Avoid land, the way a car avoids buildings. The difference is the map itself. The coastline data our engine leans on is not infinitely detailed, and at the resolution it uses, rivers, canals, narrow straits, and harbor approaches can simply disappear. A river that boats use every single day can read as solid ground to an algorithm that has never seen it any other way.

Two real, separate ports a few miles apart can end up registering as sitting on the same patch of land. Once that happens, everything downstream of it is guesswork wearing the costume of a calculation.

Building real water corridors

Our first fix was not to trust the coarse map everywhere. Instead, we built verified water corridors, real paths through the exact spots where the coastline data fails, and supplied them by hand. Eight corridors exist today, and every one of them is built from real, checked geography, not a guess at what "should" be there.

• Siak River, Perawang. A genuinely navigable river that read as solid land, rebuilt from real river data, stitched together from five connected segments.
• Musi River, Palembang. The same river-invisibility problem, solved the same honest way, from seven stitched segments and 668 real points.
• Mahakam River, Samarinda. Verified all the way through the river delta.
• Kapuas Kecil, Pontianak. The tricky one. Two rivers sit near each other here, and we had to make sure we traced the correct one, a channel 0.22 nautical miles away, rather than a much larger decoy river 14 nautical miles off.
• Port Klang North Channel. The old straight-line route cut directly across an island. We traced the real strait between Pulau Indah and the mainland instead.
• Batam Sekupang Approach. The fix for the exact problem that opened this post. We tested 72 directions radiating out from the port. Only 4 of them had any clear way out to open water at all.
• Kendari Bay, Sulawesi. The worst offender left on our list, taking a 300 nautical mile detour for a 6.2 nautical mile hop. We pulled fine-resolution coastline data for the bay to check whether the problem was bad data or real geography, and it turned out to be both: the port coordinate reads as inland by mistake, but a genuine peninsula really does separate it from its neighbour. So we traced a verified path around that peninsula, curving through the bay.
• Paniti, Halmahera. Built for a port that appears in two separate problem pairs. Honest footnote: this corridor is real and correct, but it did not move either of those two numbers, for reasons in the next section.

The corridor system follows a simple, strict pipeline. Leave the origin port, follow a corridor if one exists, route through open water, follow a corridor again if the destination needs one, arrive. The open water part of the engine never even knows a corridor exists. It only ever receives two ordinary points in the ocean. Before we layered any of this new logic in, we confirmed the underlying refactor was a true no-op, meaning it produced the exact same output, byte for byte, as before. We wanted to know nothing broke on the way in, before we started adding anything new.

A second system, built for what comes next

Alongside the corridors, we built something more ambitious. Instead of solving a route from scratch every time someone asks for one, the Ocean Graph Engine pre builds a single, persistent map of navigable water, using real seabed depth data, then answers route requests by searching that map directly.

The interesting part is how that map is built. Open ocean, far from any coastline, gets a coarse grid, because almost no real decisions happen out there. Coastal water gets a much finer grid, because that is where the real decisions live, which side of an island, which channel to take. Narrow straits get the finest grid of all, and we only classify a passage as a strait when a real check confirms coastline on two opposing sides, not just "somewhere near land."

For the full Indonesian archipelago, that comes out to just over 24,000 cells, more than 222,000 connections between them, and 266 of those cells genuinely classified as strait passages. Building the whole thing takes about 30 minutes, once, offline. Nobody waits on it while requesting a quote.

One more fix rode along with this system. When connecting a port to the nearest usable cell on the map, the old logic simply grabbed the closest one, with no check that a straight line to it actually stayed on water. For a port tucked into a bay, that can mean drawing a line straight through an island. An early version of the search, before we bounded it properly, once returned a cell 1,222 nautical miles away. We caught that before it ever shipped.

Where this stands today: fully built, checked against real data, and running on its own internal diagnostic page. Route Engine 2.0 is coming soon. It is not yet the engine behind the route editor customers actually use, and we would rather say that plainly than round up.

Finding bugs by checking, not guessing

This is the part we think is worth telling in full, because it is the difference between a fix that looks done and one that is actually verified.

We swept every real close port pair already in our database, ports under 10 nautical miles apart with no clear straight line between them. 66 pairs. Of those, 26, close to 4 in 10, produced a detour between 3 and 24 times longer than the direct distance. Not broken exactly. Just quietly, badly wrong.

That sweep turned up three separate bugs, none of them found by guessing.

The detour distance was fixed, no matter the route. When looking for an alternate path, the system tried candidates a fixed distance away, somewhere between 90 and 270 nautical miles. Reasonable for a 600 nautical mile voyage. Absurd for a 4.5 nautical mile one.

Small bays got almost no attention. When the engine looks for a path that hugs a coastline, it samples points along that coastline. But it spread those samples evenly across the whole landmass, not by how much local detail actually mattered. Manokwari Bay, a real, useful bay on a coastline shape with 584 points total, ended up with exactly one sample point inside it. One point is not enough to find a way through a bay.

The safety margin was not always safe. Port coordinates in any real system sometimes register as sitting slightly on land, a normal, well understood data precision issue. In ours, it affects 21 of our 30 ports, and it is already expected and accounted for with a small tolerance margin. The trouble was that margin was a fixed 5 percent. Fine for a dock a few meters off. Not enough for a port whose coordinate was genuinely several nautical miles inland.

Fixing all three brought the 26 broken pairs down to 10, with every previously working route still working exactly as it had before. Here is the honest part. Fixing the third bug on its own actually broke a route that had been reliable the whole time. A margin that was technically more correct turned out to be too small for one specific real case. We only caught it because we reran our entire existing test suite after every single fix, not just the new ones, and corrected it with a floor value before it ever reached production.

Then two more, found the same way

Working down that remaining list turned up two further root causes, for five in total. We are keeping them here rather than quietly folding them into the three above, because how we found them is the same story.

A safety cap can be defeated by the very thing it protects against. The tolerance margin from the third bug is deliberately capped, so one imprecise port coordinate can never excuse enough of a route to hide a genuine land crossing somewhere else on it. At Kendari, the port's real distance inland was almost as large as the entire 6.2 nautical mile hop to its neighbour, so that cap could never cover enough of any nearby path to approve it. The cap is correct and we left it alone. The fix was the Kendari Bay corridor instead, because loosening the cap would have reintroduced exactly the bug it exists to prevent.

Sometimes neither port is the problem. At Paniti, the leg of open water between two ports was blocked by the coastline data itself, with neither port registering as inland and no tolerance margin involved anywhere. This one we have not fixed, and we are saying so. A corridor only patches a port's own approach to open water. The open water stretch in between is deliberately kept separate from all corridor logic, which is what makes the rest of the engine predictable. Giving that middle stretch better local detail is a design decision about the architecture, not a per-port fix, and we would rather leave it open and named than ship a rushed answer to it.

Where things stand

Marine Routing Engine v2, the corridor system, is live in production today. Route Engine 2.0, the Ocean Graph Engine described above, is coming soon. It is fully built and verified against real data, running on its own diagnostic page right now, with one job left before it reaches you: becoming the engine behind the route editor itself. Automated regression tests cover both systems, and every change to the existing engine gets checked against the same logic that actually runs in production, not a simplified stand in for it.

Nine close port pairs remain on a named, bounded list. Seven of them need the same close, one by one attention the Batam and Kendari corridors got. The other two are the Paniti case above, waiting on a real architectural decision rather than another corridor. That is a known backlog with a clear end, not an open ended risk, and we would rather publish the number that is true this week than the one that sounded tidier last week.

We still believe the system should suggest and the captain should decide, always. Getting that suggestion right, especially over a gap that used to quietly turn into 227 nautical miles, is the unglamorous work that makes the rest of that promise possible.