OFFICIAL SDK

VesselAPI TypeScript SDK

vesselapi is the official TypeScript client for the VesselAPI REST API: vessel particulars and positions, port events, ports, emissions and casualty records. It has zero runtime dependencies, uses native fetch, and ships types for every request and response.

Get a free API key vesselapi on npm

Methods, one per endpoint

Auto-paginating iterators

Node 18+

Zero dependencies

MIT

Source on GitHub

Installation and authentication

npm install vesselapi

Node.js 18 and later are supported. The package is ESM and CommonJS, with type definitions included.

The constructor takes the API key, or reads VESSELAPI_API_KEY from the environment when called without one. Keys are created in the dashboard and sent as a bearer token on every request.

import { VesselClient } from "vesselapi";

const client = new VesselClient(process.env.VESSELAPI_API_KEY);

// Optional settings and their defaults
const configured = new VesselClient("your-api-key", {
  baseUrl: "https://api.vesselapi.com/v1",
  maxRetries: 3,
  timeoutMs: 30000, // per attempt
  userAgent: "my-app/1.0",
});

3 examples

1. Look up a vessel and its latest position

Vessel endpoints take an IMO number by default; pass the MMSI id type to look up by MMSI. A vessel that exists may have no stored position, and the API answers that with 404.

// Particulars by IMO number (the default id type)
const { vessel } = await client.vessels.get("9811000");
console.log(vessel?.name, vessel?.vessel_type, vessel?.country);

// Latest stored position by MMSI
const { vesselPosition } = await client.vessels.position("232003239", { filterIdType: "mmsi" });
console.log(vesselPosition?.latitude, vesselPosition?.longitude, vesselPosition?.sog, vesselPosition?.timestamp);

2. Vessels within 10 km of a point

Area queries return vessels with a position in the last 2 hours by default, and at most 4 hours. The radius is in metres, up to 100 km.

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, v.latitude, v.longitude, v.nav_status);
}

3. Page through port events

Every list method has an iterator variant that follows nextToken for you. Each page is one API call against your quota, so the page size sets how many calls a full walk costs.

// Every port event in the last 24 hours, 50 per page
const since = new Date(Date.now() - 24 * 3600 * 1000).toISOString();
for await (const event of client.portEvents.listAll({ filterTimeFrom: since, paginationLimit: 50 })) {
  console.log(event.event, event.port_name, event.vessel_name, event.timestamp);
}

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

Errors and retries

Non-2xx responses throw a typed error class per status, all extending VesselAPIError, which carries statusCode, the API's error code and the message. 429 responses are retried for every method and 5xx responses for idempotent ones, with exponential backoff; the Retry-After header is honoured.

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

try {
  await client.ports.get("ZZZZZ");
} catch (err) {
  if (err instanceof VesselNotFoundError) {
    console.log("no such port");
  } else if (err instanceof VesselRateLimitError) {
    console.log("quota or rate limit reached");
  } else if (err instanceof VesselAPIError) {
    console.log(err.statusCode, err.code, err.message);
  }
}

Services

Service	Covers	Guide
vessels	Vessel particulars, latest and batch positions, ETA, emissions and casualty records	Vessel tracking
ports	Port lookup by UN/LOCODE and inbound vessels	Ports and navigation
portEvents	Arrivals and departures by port, by vessel or across all covered ports	Port events
emissions	EU MRV emissions reports by reporting year	Emissions and casualty records
search	Search across vessels, ports, lights, radio beacons, DGPS stations and MODUs	Vessel tracking
location	Bounding-box and radius queries for every entity type	Ports and navigation

The Notifications API (webhooks and WebSocket) is not part of the SDK; the notifications guide shows the plain HTTP calls. Request and response schemas for every endpoint are in the API reference, and the package is on npm with its source on GitHub. For an AI assistant, the MCP server exposes the same endpoints as tools.

Start with the free tier

150 calls a month, every endpoint, no card. Paid tiers raise the quota.

Get a free API key View pricing