🌊 Sea Route Finder

Production-ready maritime routing engine for realistic ocean navigation paths.

Realistic maritime routing for JavaScript. No API keys required.

Calculate accurate sea routes between any two points on Earth using predefined shipping lanes, major straits, and maritime chokepoints. No API keys required.

✨ Features

• 🛣️ 30+ Predefined Shipping Routes - Suez Run, Panama Route, Trans-Pacific, Cape Route, and more
• 🌍 130+ Strategic Waypoints - Major canals, straits, capes, and ocean waypoints
• 🎯 Smart Chokepoint Detection - Automatically identifies Suez Canal, Malacca Strait, Gibraltar, etc.
• 📏 Distance Calculation - Returns total route distance in kilometers
• 🔄 Bidirectional Routing - Works seamlessly in both directions
• 💯 TypeScript Support - Full type definitions included
• ⚡ Zero Dependencies - Only requires @turf/turf for geodesic calculations
• 🔌 Offline First - No external APIs or network calls

📦 Installation

npm install sea-route-finder

🚀 Quick Start

const { getSeaRoute } = require('sea-route-finder');

// Singapore to Rotterdam
const route = getSeaRoute(
  [1.3, 103.8],    // Singapore [lat, lng]
  [51.9, 4.5]      // Rotterdam [lat, lng]
);

console.log(route.distance);      // 15,420 km
console.log(route.keyLocations);  // ["Malacca Strait", "Suez Canal", "Gibraltar"]
console.log(route.path.length);   // 270 coordinate points

📖 API Reference

getSeaRoute(start, end, options?)

Calculate optimal sea route between two coordinates.

Parameters

| Parameter | Type | Description | |-----------|------|-------------| | start | [lat, lng] or {lat, lng} | Starting coordinate | | end | [lat, lng] or {lat, lng} | Ending coordinate | | options | object (optional) | Configuration options |

Options

{
  strict: false,    // Log warnings for undefined routes
  avoidSuez: false  // Reserved for future use
}

Returns

{
  path: [[lat, lng], ...],           // Array of coordinates for mapping
  keyLocations: [{                   // Major chokepoints crossed
    name: "Suez Canal",
    coordinates: [31.28, 32.29]
  }],
  distance: 15420,                   // Total distance in kilometers
  regions: ["ASIA_SE", "EUR_MED"],   // Start/end regions
  routeType: "highway",              // Route calculation method
  waypointCount: 8,                  // Number of waypoints used
  success: true                      // Calculation status
}

Route Types

• direct - Same region, straight great circle
• highway - Predefined shipping lane with waypoints
• fallback - Generated route with ocean hubs (Hawaii, Azores)
• emergency - Last-resort straight line (error case)

🗺️ Supported Routes

Major Shipping Lanes

| Route | Waypoints | |-------|-----------| | Asia → Europe | Malacca Strait → Suez Canal → Gibraltar | | Asia → US East | Hawaii → Panama Canal | | Asia → US West | North Pacific crossing | | Europe → Americas | Azores Hub → Atlantic crossing | | Africa Routes | Cape of Good Hope (alternative to Suez) |

Geographic Regions

The engine divides the world into 10 maritime regions:

• NAM_WEST - North America West Coast
• NAM_EAST - North America East Coast
• SAM - South America
• EUR_MED - Europe & Mediterranean
• AFRICA - Sub-Saharan Africa
• AFRICA_NORTH - North Africa
• MIDDLE_EAST - Persian Gulf region
• ASIA_SOUTH - India, Pakistan
• ASIA_EAST - China, Japan, Korea
• ASIA_SE - Singapore, Malaysia, Indonesia

🔧 Utility Functions

getRegion(coordinate)

Determine which maritime region a coordinate belongs to.

const { getRegion } = require('sea-route-finder');

const region = getRegion([1.3, 103.8]);  // "ASIA_SE"

getDistance(p1, p2)

Calculate great circle distance between two points.

const { getDistance } = require('sea-route-finder');

const dist = getDistance([1.3, 103.8], [51.5, -0.1]);  // 10,854 km

WAYPOINTS

Access the complete database of 130+ maritime waypoints.

const { WAYPOINTS } = require('sea-route-finder');

console.log(WAYPOINTS.SUEZ_ENTRANCE_NORTH);  // [31.28, 32.29]
console.log(WAYPOINTS.PANAMA_CANAL_EAST);    // [9.12, -79.75]
console.log(WAYPOINTS.MALACCA_STRAIT_MID);   // [2.8, 101.2]

💡 Usage Examples

React + Leaflet

import { MapContainer, TileLayer, Polyline, Marker } from 'react-leaflet';
import { getSeaRoute } from 'sea-route-finder';

function ShippingMap() {
  const route = getSeaRoute([31.2, 121.5], [51.5, -0.1]);
  
  return (
    <MapContainer center={[30, 50]} zoom={3}>
      <TileLayer url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png" />
      <Polyline positions={route.path} color="blue" />
      {route.keyLocations.map((loc, i) => (
        <Marker key={i} position={loc.coordinates} />
      ))}
    </MapContainer>
  );
}

Express API

const express = require('express');
const { getSeaRoute } = require('sea-route-finder');

const app = express();

app.get('/route', (req, res) => {
  const { startLat, startLng, endLat, endLng } = req.query;
  
  const route = getSeaRoute(
    [parseFloat(startLat), parseFloat(startLng)],
    [parseFloat(endLat), parseFloat(endLng)]
  );
  
  res.json(route);
});

app.listen(3000);

TypeScript

import { getSeaRoute, SeaRouteResult, KeyLocation } from 'sea-route-finder';

const route: SeaRouteResult = getSeaRoute([1.3, 103.8], [51.5, -0.1]);

route.keyLocations.forEach((location: KeyLocation) => {
  console.log(`${location.name}: ${location.coordinates}`);
});

🎯 How It Works

1. Region Detection - Identifies which maritime region each coordinate belongs to
2. Highway Selection - Looks up predefined route between regions (e.g., ASIA_EAST__EUR_MED)
3. Waypoint Assembly - Chains together strategic waypoints (straits, canals, ocean nodes)
4. Curve Generation - Uses Turf.js to create great circle paths between waypoints
5. Chokepoint Detection - Scans route for proximity to major maritime chokepoints

Why Not Just Draw a Straight Line?

A straight line from Singapore to Rotterdam would cut through:

• ❌ Malaysia
• ❌ Myanmar
• ❌ India
• ❌ Pakistan
• ❌ Iran
• ❌ Saudi Arabia
• ❌ Egypt

This library routes through:

• ✅ Malacca Strait
• ✅ Indian Ocean
• ✅ Suez Canal
• ✅ Mediterranean Sea
• ✅ Gibraltar
• ✅ Atlantic Ocean

📊 Performance

• Calculation Time: < 50ms for most routes
• Memory Usage: ~2MB (waypoint database)
• Route Points: 100-300 coordinates depending on distance
• Bundle Size: ~15KB minified (excluding Turf.js)

🛠️ Requirements

• Node.js 12+
• @turf/turf ^7.0.0 (peer dependency)

📄 License

MIT License - feel free to use in commercial projects.

🤝 Contributing

Contributions welcome! Areas for improvement:

• Additional maritime routes (Arctic, Red Sea alternatives)
• Weather-based routing
• Piracy risk zones
• Speed/fuel optimization
• Port approach waypoints

🐛 Issues

Found a bug or have a suggestion? Report on npm

🙏 Acknowledgments

Built with Turf.js for geodesic calculations.

Maritime waypoints based on standard international shipping routes.