Searoute

searoute-ts

Shortest sea route between any two points on Earth. A TypeScript / JavaScript

library for maritime route planning, port-to-port distance, ETA estimation, and

shipping-lane visualisation — powered by the 2025 Eurostat maritime network.

npm install searoute-ts

import { seaRoute } from 'searoute-ts';

const route = seaRoute([121.5, 31.0], [4.4, 51.9]); // Shanghai → Rotterdam → GeoJSON LineString, ~10,664 nm via Suez Canal

🗺️ [Try the interactive demo](https://mayurrawte.github.io/searoute-ts/) — click two points on a map and see the route, with all options live. (source)

📏 [Port-to-port sea distances](https://mayurrawte.is-a.dev/searoute-ts/routes/) — distance, sailing time and canal passages for common routes between major ports.

Works from plain JavaScript too — the package ships compiled .js plus

.d.ts declarations. The -ts in the name is for searchability, not a

language requirement.

---

Why searoute-ts

• 🚢 Realistic shipping routes, not great-circle lines through Eurasia.
• 🗺️ Returns GeoJSON — drop straight into Leaflet, Mapbox, deck.gl, MapLibre.
• 🌊 2025 Eurostat marnet with explicit Suez, Panama, Bab-el-Mandeb, Malacca, Gibraltar, Dover, Kiel, Corinth, Bering, Magellan, NW/NE Passage labels.
• 🚫 Canal & strait restrictions — force Cape of Good Hope during a Red Sea disruption with one option.
• 📦 Vessel-draft gating — auto-block Panama (15.2 m), Suez (20.1 m), Kiel (7 m), Corinth (7.3 m) when the vessel exceeds the canal limit.
• 🛤️ K-shortest alternatives — seaRouteAlternatives returns the baseline plus up to N realistic alternatives.
• 🧭 Multi-leg waypoints — seaRouteMulti for port rotations and itineraries.
• ⏱️ ETA from speed — speedKnots → durationHours.
• 🛠️ Modern toolchain — TypeScript 5, ESM + CJS dual build, types included, Node 18+, zero peer deps.

Quick examples

Basic — shortest route

import { seaRoute } from 'searoute-ts';

const route = seaRoute([-74.04, 40.69], [-0.13, 51.5]); // NYC → London // route.properties.length // ≈ 3 362 nm // route.properties.units // 'nauticalmiles'

With ETA and units

seaRoute(shanghai, rotterdam, {

units: 'kilometers', speedKnots: 22, }); // → 19 753 km, properties.durationHours ≈ 485 h (≈ 20 days)

Red Sea / Suez disruption — force Cape of Good Hope

seaRoute(shanghai, rotterdam, {

restrictions: ['suez', 'babelmandeb'], }); // → routes via Cape of Good Hope, ~25 800 km

Vessel-aware — Ultra Large Container Ship

seaRoute(shanghai, newYork, {

vesselDraftMeters: 16, // exceeds Panama's 15.2 m TFW }); // → Panama auto-blocked, route goes via Suez

Port codes (UN/LOCODE)

import 'searoute-ts/ports'; // enables UN/LOCODE strings on the core API

import { seaRoute } from 'searoute-ts';

seaRoute('CNSHA', 'NLRTM'); // Shanghai → Rotterdam seaRoute('CNSHA', [4.4, 51.9]); // mixing a code and coordinates is fine too

The ~1 600-port dataset lives behind the searoute-ts/ports subpath so the core stays lean — importing it registers the resolver. You can also resolve codes yourself:

import { lookupPort, resolvePort } from 'searoute-ts/ports';

lookupPort('SGSIN'); // → { code, name: 'Singapore', country, coordinates: [lon, lat] } resolvePort('SGSIN'); // → [103.85, 1.28]

Unknown codes throw UnknownPortError. See Port codes below for provenance.

Load the port dataset from a CDN instead of bundling it

Don't want to bundle the ~135 KB dataset? Fetch it at runtime with loadPorts — the analog of loadNetwork. The dataset also ships as a raw dist/ports.json, so jsDelivr/unpkg serve it versioned for free:

import { seaRoute, loadPorts } from 'searoute-ts';

// Pin a version for reproducibility, or use @latest to always get the newest. await loadPorts('https://cdn.jsdelivr.net/npm/searoute-ts@latest/dist/ports.json');

seaRoute('CNSHA', 'NLRTM'); // works — the fetched dataset is now registered

https://cdn.jsdelivr.net/npm/searoute-ts@latest/dist/ports.json # newest https://cdn.jsdelivr.net/npm/searoute-ts@ /dist/ports.json # frozen/immutable

(dist/ports.json ships from the release that adds port codes onward — pin any version at or after it for reproducibility.)

loadPorts registers the fetched dataset (so code strings resolve) and returns it. It uses the global fetch (Node ≥18 / browsers); pass { fetch } to override.

Multi-leg / port rotation

import { seaRouteMulti } from 'searoute-ts';

seaRouteMulti( [shanghai, singapore, mumbai, rotterdam], { units: 'kilometers', returnPassages: true }, ); // → one concatenated LineString, total length, union of passages

Alternative routes (Yen-style canal permutation)

import { seaRouteAlternatives } from 'searoute-ts';

const alts = seaRouteAlternatives(shanghai, rotterdam, { k: 4 }); // baseline 19 753 km via Suez // no-malacca 20 759 km // no-suez 25 315 km (via Panama) // no-suez-no-panama 25 845 km (via Cape of Good Hope)

Fetch the network from a URL instead of bundling it (optional)

The network is bundled by default, so seaRoute works offline with zero setup. If you'd rather not ship the ~1 MB network (e.g. to trim a browser bundle, or to use an updated network without upgrading the package), fetch it at runtime and pass it via the existing network option:

import { seaRoute, loadNetwork } from 'searoute-ts';

// CORS-enabled, served from GitHub Pages (or point at your own host / a CDN). const network = await loadNetwork('https://mayurrawte.github.io/searoute-ts/marnet.json');

const route = seaRoute(shanghai, rotterdam, { network });

Only the fetch is async — seaRoute itself stays synchronous. loadNetwork uses the global fetch (Node ≥18 and all browsers); pass { fetch } to supply your own. This is purely opt-in; nothing changes if you don't use it.

Which option should I use?

Versioning the hosted network

You choose the version by choosing the URL:

• `@latest` / rolling — the GitHub Pages URL above always serves the current network. Convenient, but it can change under you.
• Pinned & immutable — because the package is on npm, jsDelivr and unpkg serve every published version automatically, with immutable per-version URLs:

  https://cdn.jsdelivr.net/npm/searoute-ts@latest/dist/marnet.json   # newest

https://cdn.jsdelivr.net/npm/searoute-ts@2/dist/marnet.json # newest 2.x https://cdn.jsdelivr.net/npm/searoute-ts@2.0.1/dist/marnet.json # frozen

A pinned URL never changes, so your routes stay reproducible. (These standalone-JSON CDN paths land with the package once the network ships as a separate asset — see issue #10; until then, use the GitHub Pages URL.)

For production, prefer a pinned URL (or just the bundled default) so your distances don't shift when the network is updated.

Higher-resolution networks (optional)

The bundled network is Eurostat's 100 km marnet_plus. Eurostat also publishes finer resolutions, which give more accurate coastal routing and shorter-hop fidelity at the cost of a larger download and slightly slower first-route graph construction. Two moderate resolutions ship as subpath exports so you only pay for them if you import them:

import { DEFAULT_MARNET } from 'searoute-ts/marnet-20km'; // or 'searoute-ts/marnet-50km'

import { seaRoute } from 'searoute-ts';

seaRoute(origin, destination, { network: DEFAULT_MARNET });

Like the bundled default, each variant ships once as a shared dist/data/marnet- .cjs asset that both the CJS and ESM builds load at runtime, so importing a variant doesn't duplicate the network across builds.

The 10 km and 5 km networks are large enough that bundling them would dominate the install, so they are not shipped in the package. Generate them from the Eurostat source with scripts/build-marnet.cjs (the script header documents the GDAL conversion), host the resulting JSON, and load it with loadNetwork — or pass any FeatureCollection to the network option directly.

Output shape

{

type: 'Feature', geometry: { type: 'LineString', coordinates: [[lon, lat], ...] }, properties: { length: number, // in units, in-water only units: 'nauticalmiles' | 'kilometers' | 'miles' | ..., bbox: [minLon, minLat, maxLon, maxLat], greatCircleLength: number, // haversine between inputs, same units detourRatio: number, // routeKm / greatCircleKm originSnapKm: number, // input → network distance destinationSnapKm: number, durationHours?: number, // if speedKnots set passages?: ('suez' | 'panama' | ...)[], // if returnPassages: true ecaKm?: number, // if emissions + searoute-ts/eca imported ecaFraction?: number, // ecaKm / length (0–1) co2eTonnes?: number, // if emissions + vesselClass/factor } }

length runs between the two snapped network vertices. It does not include the legs from your inputs to the network (originSnapKm, destinationSnapKm, always in km), even with appendOriginDestination: true, which only adds the raw points to the line. For a door-to-door figure, add them yourself:

const { length, originSnapKm, destinationSnapKm } = seaRoute(a, b, { units: 'kilometers' }).properties;

const doorToDoorKm = originSnapKm + length + destinationSnapKm;

On hops shorter than the network resolution (~100 km by default, ~20 km with searoute-ts/marnet-20km), the snapped vertices can sit closer together than the inputs, so length can come out below greatCircleLength (detourRatio < 1). If both inputs snap to the same vertex, `NoRouteErro