@arcnautical/maritime-routing

Production-grade maritime routing engine for JavaScript/TypeScript. Zero dependencies.

Compute realistic ocean routes between any two ports worldwide, with guaranteed land avoidance, weather-aware ETA, and EEZ transit analysis.

Why this exists

Every shipping tech startup reinvents maritime routing. The existing open-source options (searoute-js — unmaintained since 2020, uses year-2000 data) are inadequate for production use. Commercial APIs charge EUR 600-6,900/year.

This library is extracted from ArcNautical, a maritime risk intelligence platform. It has been tested against 1,790 real-world routes with 0% land crossing.

Features

| Feature | Description | |---------|-------------| | A* Ocean Pathfinding | Routes on a 0.05° ocean bitmap (7200x3600 cells) derived from OpenStreetMap. Routes are guaranteed to never cross land. | | Dijkstra Waypoint Routing | 48 strategic chokepoints (Suez, Panama, Malacca, Gibraltar, etc.) with distance-weighted graph routing. | | 510+ Port Database | UN/LOCODE standard. Search by name, country, or code. Includes coordinates, port type, and ocean region. | | Weather Speed Model | Beaufort-based speed reduction (Kwon 2008, Lu et al. 2015). Per vessel type and load condition. Direction-aware with Cbeta factors. | | EEZ Transit Analysis | Detect which Exclusive Economic Zones a route transits. Sanctions flagging included. | | Avoid Zones | Route around user-specified polygons (e.g., piracy areas, conflict zones). | | Via Waypoints | Force routes through specific coordinates. | | GeoJSON Output | All routes returned as GeoJSON LineString, ready for map rendering. |

Install

npm install @arcnautical/maritime-routing

Requires Node.js >= 18.

Quick Start

import { computeRoute } from '@arcnautical/maritime-routing';

// Compute a route from Singapore to Rotterdam
const route = computeRoute('SGSIN', 'NLRTM');

console.log(route.distance_nm);        // ~8,440 nm
console.log(route.duration_hours);      // ~603 hours at 14 knots
console.log(route.waypoints.length);    // waypoints transited
console.log(route.hazard_zones_crossed); // chokepoints on route

// GeoJSON for map rendering
const geojson = route.route_geojson;
// -> FeatureCollection with LineString geometry

API Reference

Route Computation

import {
  computeRoute,
  computeRouteInternal,
} from '@arcnautical/maritime-routing';

// Simple route (returns handler-compatible format)
const route = computeRoute('SGSIN', 'NLRTM');

// Route with options
const route = computeRoute('SGSIN', 'NLRTM', {
  avoid_zones: [[[30, 12], [50, 12], [50, 32], [30, 32], [30, 12]]], // avoid Red Sea
  via_waypoints: [{ lat: -34.4, lon: 18.5 }], // force via Cape of Good Hope
});

// Internal format (with segment breakdown)
const internal = computeRouteInternal('SGSIN', 'NLRTM');
console.log(internal.segments);       // per-leg distance + bearing
console.log(internal.totalDistanceNm);
console.log(internal.geojson);        // GeoJSON Feature

Ocean Pathfinding

import { findOceanPath } from '@arcnautical/maritime-routing';

// Find a path between two coordinates
// Returns [lon, lat][] (GeoJSON convention)
const path = findOceanPath(1.26, 103.84, 51.90, 4.50);
// -> ~500 coordinate pairs, guaranteed to never cross land

// Performance: 8-50ms for typical segments
// Automatically subdivides routes > 5,000nm

Port Database

import {
  searchPorts,
  getPortByLocode,
  getPortsByRegion,
  resolveAisDestination,
  findNearestPort,
  PORTS,
} from '@arcnautical/maritime-routing';

// Search by name, country, or LOCODE
const ports = searchPorts('Singapore');    // [{ locode: 'SGSIN', ... }]
const ports = searchPorts('Japan', 50);   // up to 50 results

// Exact lookup
const sg = getPortByLocode('SGSIN');      // { name: 'Singapore', lat: 1.26, ... }

// By region
const medPorts = getPortsByRegion('mediterranean'); // 30+ ports

// Parse messy AIS destination strings
const port = resolveAisDestination('NL RTM');   // -> Rotterdam
const port = resolveAisDestination('>>SGSIN<<'); // -> Singapore

// Find nearest port to coordinates
const port = findNearestPort(51.9, 4.5);  // -> Rotterdam

// All 510+ ports
console.log(PORTS.length);

Weather Speed Model

import {
  computeSeaStateFactor,
  computeRouteEta,
  windToBeaufort,
  waveToBeaufort,
} from '@arcnautical/maritime-routing';

// Compute speed reduction from weather
const result = computeSeaStateFactor({
  baseSpeedKnots: 14,
  waveHeightM: 3.0,
  windSpeedKt: 25,
  swellHeightM: 1.5,
  vesselType: 'bulk',     // container | bulk | tanker | lng | general
  loadCondition: 'laden', // laden | ballast
  // Optional direction-aware inputs:
  waveDirectionDeg: 270,
  vesselHeadingDeg: 90,   // heading into waves = worst case
});

console.log(result.effectiveSpeedKnots); // reduced speed
console.log(result.beaufortNumber);      // 6
console.log(result.speedReductionPct);   // % reduction
console.log(result.seaStateFactor);      // 0-1 retention

// Compute ETA for a full route
const eta = computeRouteEta(
  segments,          // [{ distanceNm, bearing }]
  segmentWeather,    // per-segment weather data
  14,                // base speed (knots)
  'container',       // vessel type
  'laden',           // load condition
);
console.log(eta.totalTransitHours);
console.log(eta.worstSegmentIndex);

EEZ Transit Analysis

import { analyzeRouteEezTransit } from '@arcnautical/maritime-routing';

const result = analyzeRouteEezTransit(segments, totalDistanceNm);

for (const eez of result.transitEezs) {
  console.log(`${eez.countryName}: ${(eez.routeFraction * 100).toFixed(1)}%`);
  if (eez.isSanctioned) console.log('  ⚠ SANCTIONED');
}

console.log(result.sanctionedEezFraction); // 0-1
console.log(result.summary);              // human-readable

Geodesic Utilities

import {
  haversineDistance,
  haversineDistanceNm,
  bearing,
  interpolateGreatCircle,
  pointInPolygon,
} from '@arcnautical/maritime-routing';

// Distance in nautical miles
const nm = haversineDistanceNm(1.26, 103.84, 51.90, 4.50); // ~5,700

// Initial bearing (degrees)
const brg = bearing(1.26, 103.84, 51.90, 4.50); // ~315°

// Great circle arc interpolation
const points = interpolateGreatCircle(0, 0, 45, 90, 100);
// -> 101 [lat, lon] pairs along the arc

// Point-in-polygon test
const inside = pointInPolygon(5, 5, [[0,0], [10,0], [10,10], [0,10]]);

Data Sources

| Data | Source | License | |------|--------|---------| | Ocean grid | OpenStreetMap water polygons | ODbL | | Port database | UN/LOCODE + public maritime data | Public domain | | Speed model | Kwon 2008, Lu et al. 2015 | Academic literature | | EEZ boundaries | UN CLCS / Flanders Marine Institute | Public domain | | Waypoint graph | Public maritime knowledge | N/A |

Performance

| Operation | Time | |-----------|------| | Port lookup (by LOCODE) | < 0.1ms | | Port search (by name) | < 1ms | | Ocean pathfinding (single segment) | 8-50ms | | Full route computation (Singapore → Rotterdam) | ~250ms | | Speed model computation | < 0.1ms | | Grid loading (first call only) | ~900ms |

Package size: ~200KB (compiled JS) + 106KB (ocean grid) + 90KB (EEZ data).

Comparison with searoute-js

| Feature | @arcnautical/maritime-routing | searoute-js | |---------|-------------------------------|-------------| | Last updated | 2026 | 2020 | | TypeScript | Native | No | | Dependencies | Zero | Multiple | | Land avoidance | Guaranteed (bitmap) | No (graph only) | | Port database | 510+ ports | None | | Weather model | Beaufort + Cbeta | None | | EEZ analysis | Yes | None | | Avoid zones | Yes | No | | Via waypoints | Yes | No | | Narrow passages | Suez, Panama, Bosphorus, etc. | Limited | | Resolution | 0.05° (~5.5km) | Variable | | Data source | OSM (2024) | ORNL (2000) |

Advanced Usage

Custom Ocean Grid

import { setGridPath, loadGridFromBuffer } from '@arcnautical/maritime-routing';

// Use a custom grid file
setGridPath('/path/to/my-ocean-grid.bin.gz');

// Or load from a buffer (e.g., fetched from CDN)
const buffer = await fetch('https://cdn.example.com/ocean-grid.bin.gz')
  .then(r => r.arrayBuffer());
loadGridFromBuffer(new Uint8Array(buffer));

Generate Your Own Ocean Grid

The ocean grid is generated from OSM water polygon shapefiles:

# Download water polygons from osmdata.openstreetmap.de
# Then run the generator:
npx tsx scripts/generate-ocean-grid.ts /path/to/water_polygons.shp

Ocean Regions

Ports are classified into 16 ocean regions used for routing:

pacific, south_china_sea, southeast_asia, indian_ocean, persian_gulf, red_sea, mediterranean, atlantic_north, atlantic_south, caribbean, north_sea, baltic, black_sea, arctic, oceania, east_pacific

Vessel Types

The speed model supports 5 vessel types with distinct sea-keeping characteristics:

| Type | Reference Speed | Typical DWT | |------|----------------|-------------| | container | 20 kt | 50,000-200,000 | | bulk | 14 kt | 30,000-400,000 | | tanker | 14 kt | 50,000-320,000 | | lng | 19 kt | 70,000-180,000 | | general | 14 kt | 5,000-40,000 |

License

MIT - see LICENSE.

About

Built by ArcNautical — maritime risk intelligence for fleet managers, underwriters, and compliance teams.

ArcNautical provides voyage risk scoring, sanctions screening, piracy/conflict threat intelligence, and automated compliance reports. The routing engine you're using here powers our commercial platform.

If you need maritime risk intelligence beyond routing, get in touch.