vesselapi

TypeScript client for the Vessel Tracking API — maritime vessel tracking, port events, emissions, and navigation data. Zero runtime dependencies — uses native fetch only.

Resources: Documentation | API Explorer | Dashboard | Contact Support

Install

npm install vesselapi

Requires Node.js 18+.

Quick Start

import { VesselClient } from "vesselapi";

const client = new VesselClient("your-api-key");

// Search for a vessel by name.
const { vessels } = await client.search.vessels({ filterName: "Ever Given" });
for (const v of vessels ?? []) {
  console.log(`${v.name} (IMO ${v.imo})`);
}

// Get a port by UN/LOCODE.
const { port } = await client.ports.get("NLRTM");
console.log(port?.name);

// Auto-paginate through port events.
for await (const event of client.portEvents.listAll({ paginationLimit: 10 })) {
  console.log(`${event.event} at ${event.timestamp}`);
}

Available Services

| Service | Methods | Description | |---------|---------|-------------| | vessels | get, position, casualties, classification, emissions, eta, inspections, inspectionDetail, ownership, positions | Vessel details, positions, and records | | ports | get | Port lookup by UN/LOCODE | | portEvents | list, byPort, byPorts, byVessel, lastByVessel, byVessels | Vessel arrival/departure events | | emissions | list | EU MRV emissions data | | search | vessels, ports, dgps, lightAids, modus, radioBeacons | Full-text search across entity types | | location | vesselsBoundingBox, vesselsRadius, portsBoundingBox, portsRadius, dgpsBoundingBox, dgpsRadius, lightAidsBoundingBox, lightAidsRadius, modusBoundingBox, modusRadius, radioBeaconsBoundingBox, radioBeaconsRadius | Geo queries by bounding box or radius | | navtex | list | NAVTEX maritime safety messages |

37 methods total.

Vessel Lookup & Location

// Get vessel details by IMO number (defaults to IMO; pass filterIdType: "mmsi" for MMSI).
const { vessel } = await client.vessels.get("9811000");
console.log(`${vessel?.name} (${vessel?.vessel_type})`);

// Get the vessel's latest AIS position.
const { vesselPosition } = await client.vessels.position("9811000");
console.log(`Position: ${vesselPosition?.latitude}, ${vesselPosition?.longitude}`);

// Find all vessels within 10 km of Rotterdam.
const nearby = await client.location.vesselsRadius({
  latitude: 51.9225,
  longitude: 4.47917,
  radius: 10000,
});
for (const v of nearby.vessels ?? []) {
  console.log(`${v.vessel_name} at ${v.latitude}, ${v.longitude}`);
}

Error Handling

All methods throw specific error types on non-2xx responses:

import { VesselAPIError, VesselNotFoundError, VesselRateLimitError } from "vesselapi";

try {
  await client.ports.get("ZZZZZ");
} catch (err) {
  if (err instanceof VesselNotFoundError) {
    console.log("Port not found");
  } else if (err instanceof VesselRateLimitError) {
    console.log("Rate limited — back off");
  } else if (err instanceof VesselAPIError) {
    console.log(err.statusCode, err.message);
  }
}

Auto-Pagination

Every list endpoint has an all* / listAll variant returning an async iterator:

// Async iteration
for await (const vessel of client.search.allVessels({ filterVesselType: "Tanker" })) {
  console.log(vessel.name);
}

// Collect all pages into an array
const all = await client.search.allVessels({
  filterVesselType: "Tanker",
  paginationLimit: 50,
}).collect();

// Manual pagination
const page1 = await client.search.vessels({ filterName: "Ever Given" });
const page2 = await client.search.vessels({
  filterName: "Ever Given",
  paginationNextToken: page1.nextToken,
});

Configuration

const client = new VesselClient("your-api-key", {
  baseUrl: "https://api.vesselapi.com/v1", // default
  maxRetries: 3,    // default, retries on 429/5xx
  timeoutMs: 30000, // default, 30 seconds
  userAgent: "my-app/1.0",
});

The API key can also be provided via the VESSELAPI_API_KEY environment variable:

const client = new VesselClient(); // reads from VESSELAPI_API_KEY

Retry Logic

The SDK automatically retries failed requests with exponential backoff:

• 429 (Rate Limited): Retried for all HTTP methods
• 5xx (Server Error): Retried only for idempotent methods (GET, HEAD, PUT, DELETE, OPTIONS)
• Network errors: Retried only for idempotent methods
• Retry-After header: Respected (both integer seconds and HTTP-date formats)
• Backoff: Exponential with jitter, capped at 30 seconds

Documentation

• API Documentation — endpoint guides, request/response schemas, and usage examples
• API Explorer — interactive API reference
• Dashboard — manage API keys and monitor usage

Contributing & Support

Found a bug, have a feature request, or need help? You're welcome to open an issue. For API-level bugs and feature requests, please use the main VesselAPI repository.

For security vulnerabilities, do not open a public issue — email [email protected] instead.

License

MIT