suaveplan/packages/geospatial/logistics/ports/README.md

@suaveplan/ports - Global port database with shipping-lane routing, ETA estimation, and UN/LOCODE port lookups for sea ports, airports, and rail terminals.

Global port database with shipping-lane routing, ETA estimation, and UN/LOCODE port lookups for sea ports, airports, and rail terminals.

Documentation tree

• airports — Curated dataset of major international air-cargo airports, exported as the readonly airports array. Each record confo…
  • airports — Curated dataset of major international air-cargo airports, exported as the readonly airports array. Each record confo…
• all-ports — Aggregates every curated dataset — sea ports, airports, and rail terminals — into a single readonly allPorts array an…
  • all-ports — Aggregates every curated dataset — sea ports, airports, and rail terminals — into a single readonly allPorts array an…
• rail-terminals — Curated dataset of major rail freight terminals — primarily the inland container hubs on the New Silk Road and Trans-Eu…
  • rail-terminals — Curated dataset of major rail freight terminals — primarily the inland container hubs on the New Silk Road and Trans-Eu…
• sea-ports — Aggregates every regional sea-port dataset (seaPortsAsia, seaPortsEurope, seaPortsAmericas, seaPortsAfricaMena,…
  • sea-ports — Aggregates every regional sea-port dataset (seaPortsAsia, seaPortsEurope, seaPortsAmericas, seaPortsAfricaMena,…
• sea-ports-africa-mena — Curated dataset of major sea ports across Africa and the Middle East / North Africa region, exported as the readonly `s…
  • sea-ports-africa-mena — Curated dataset of major sea ports across Africa and the Middle East / North Africa region, exported as the readonly `s…
• sea-ports-americas — Curated dataset of major sea ports across the Americas, exported as the readonly seaPortsAmericas array. Every record…
  • sea-ports-americas — Curated dataset of major sea ports across the Americas, exported as the readonly seaPortsAmericas array. Every record…
• sea-ports-asia — Curated dataset of major sea ports across Asia, exported as the readonly seaPortsAsia array. Every record conforms to…
  • sea-ports-asia — Curated dataset of major sea ports across Asia, exported as the readonly seaPortsAsia array. Every record conforms to…
• sea-ports-europe — Curated dataset of major sea ports across Europe, exported as the readonly seaPortsEurope array. Every record conform…
  • sea-ports-europe — Curated dataset of major sea ports across Europe, exported as the readonly seaPortsEurope array. Every record conform…
• sea-ports-oceania — Curated dataset of major sea ports across Oceania, exported as the readonly seaPortsOceania array. Every record confo…
  • sea-ports-oceania — Curated dataset of major sea ports across Oceania, exported as the readonly seaPortsOceania array. Every record confo…
• shipping-lanes — Curated registry of major global shipping lanes — Asia–Europe via Suez, Asia–Europe via Cape, Transpacific, Transatlant…
  • shipping-lanes — Curated registry of major global shipping lanes — Asia–Europe via Suez, Asia–Europe via Cape, Transpacific, Transatlant…
• distance — Wraps @suaveplan/geo's greatCircleDistance against a sphere whose radius matches the IUGG mean Earth radius (6 371…
  • distance — Wraps @suaveplan/geo's greatCircleDistance against a sphere whose radius matches the IUGG mean Earth radius (6 371…
• error-codes — Declares the eight stable error codes emitted by @suaveplan/ports and the matching typed PortsError subclasses. Eve…
  • error-codes — Declares the eight stable error codes emitted by @suaveplan/ports and the matching typed PortsError subclasses. Eve…
• eta — Estimates the time of arrival for a vessel travelling along a ShippingLane. Resolves an effective cruise speed from (…
  • eta — Estimates the time of arrival for a vessel travelling along a ShippingLane. Resolves an effective cruise speed from (…
• find-port — Provides the lookup surface for @suaveplan/ports. Every public function consumes the curated allPorts registry by d…
  • find-port — Provides the lookup surface for @suaveplan/ports. Every public function consumes the curated allPorts registry by d…
• lane-distance — Computes great-circle distance metrics for a ShippingLane's waypoint chain. estimateLaneDistance sums every segment…
  • lane-distance — Computes great-circle distance metrics for a ShippingLane's waypoint chain. estimateLaneDistance sums every segment…
• lane-lookup — Public lookup surface for the curated shippingLanes registry. Mirrors the port-lookup module in style: an O(1) Map…
  • lane-lookup — Public lookup surface for the curated shippingLanes registry. Mirrors the port-lookup module in style: an O(1) Map…
• lane-progress — Projects a vessel position onto a shipping lane and reports how much of the lane has been traversed, how much remains,…
  • lane-progress — Projects a vessel position onto a shipping lane and reports how much of the lane has been traversed, how much remains,…
• nearest-port — Public proximity-search API. findNearestPort returns the single closest port to a coordinate; findPortsInRadius ret…
  • nearest-port — Public proximity-search API. findNearestPort returns the single closest port to a coordinate; findPortsInRadius ret…
• otel — Wires @suaveplan/ports' OpenTelemetry instrumentation: three counters that track lookup volume per kind, lane lookup…
  • otel — Wires @suaveplan/ports' OpenTelemetry instrumentation: three counters that track lookup volume per kind, lane lookup…
• schemas — Defines Zod schemas for every public type emitted by @suaveplan/ports. API plugins, message-queue handlers, and any o…
  • schemas — Defines Zod schemas for every public type emitted by @suaveplan/ports. API plugins, message-queue handlers, and any o…
• spatial-index — PortSpatialIndex buckets a port set by 5-degree latitude/longitude cells at construction time so findNearest and `f…
  • spatial-index — PortSpatialIndex buckets a port set by 5-degree latitude/longitude cells at construction time so findNearest and `f…

Install

bun add @suaveplan/ports

What's in the box

• Curated Port registry: ~100 sea ports across five regions, ~30 international cargo airports, ~30 rail freight terminals.
• Lookups: by UN/LOCODE (findPort / findPortStrict), by ISO country (findPortsByCountry), by PortType (findPortsByType), by name substring (searchPorts).
• Proximity: findNearestPort and findPortsInRadius (5°-bucketed PortSpatialIndex under the hood).
• Curated shippingLanes waypoint graph for the major sea, rail, and air freight routes.
• Lane distance (estimateLaneDistance, cumulativeDistances), lane projection (findPositionOnLane), and ETA estimation (estimateETA).
• 8-code typed error registry under the PORTS.* namespace via @suaveplan/error.
• Zod schemas for every public type under ./schemas/schemas.
• OpenTelemetry instrumentation: three counters and three histograms via ./otel/otel.

Quickstart

import {
    findPort,
    findNearestPort,
    getShippingLaneStrict,
    estimateETA,
} from "@suaveplan/ports";

const shanghai = findPort("CNSHA");
const nearestSea = findNearestPort({ latitude: 1.26, longitude: 103.82 });
const suez = getShippingLaneStrict("asia-europe-suez");
const eta = estimateETA(
    { latitude: 12.5, longitude: 43.3 },
    suez,
    14,
    { departureTime: new Date() }
);
console.log(eta.etaDate, eta.confidence);

Capability spec

See the canonical capability specification (requirements + scenarios + **Verified by:** links).