VesselTrack API Documentation

Global Stats

High-level vessel counts for the public dashboard.

curl -L https://www.vesseltrack.net/api/stats

{ "total_vessels": 90000, "updated_last_1h": 12000, "updated_last_24h": 60000 }

Map Vessel Positions

Lightweight map payload. The web app paints a bounded initial payload for speed and exposes a manual full-fleet load when needed.

curl -L "https://www.vesseltrack.net/api/vessels/map?limit=1000"

{ "count": 88722, "freshness": { "mode": "fresh" }, "vessels": [{ "mmsi": 566000000, "lat": -37.6, "lon": 176.1, "heading": 511, "ship_type": 80, "sog": 0, "name": "HAFNIA FALCON" }] }

List Vessels

Full translated vessel records with normalized destination metadata and filtering.

curl -L -H "X-API-Key: vt_live_..." "https://www.vesseltrack.net/api/vessels?limit=100&ship_category=tanker&destination_country=NZ"

{ "count": 100, "total": 88722, "limit": 100, "offset": 0, "vessels": [{ "identity": {}, "navigation": {}, "destination_normalized": {} }] }

Search Vessels

Search by MMSI, IMO, vessel name, callsign, or destination.

curl -L -H "X-API-Key: vt_live_..." "https://www.vesseltrack.net/api/vessels/search?q=HAFNIA%20FALCON"

{ "count": 3, "query": "HAFNIA", "vessels": [{ "identity": { "mmsi": 566000000, "name": "HAFNIA FALCON" } }] }

Vessel Detail

Full translated detail for one vessel. Seven-digit identifiers resolve as IMO first; MMSI is the fallback.

curl -L -H "X-API-Key: vt_live_..." https://www.vesseltrack.net/api/vessels/9043940

{ "vessel": { "identity": {}, "navigation": {}, "timestamps": {} }, "lookup": { "canonicalType": "imo" } }

Vessel Track Points

Historical position points for a vessel. IMO is preferred when available; MMSI is the fallback. Paid access is enforced by API key or active site session.

{ "mmsi": 512345678, "imo": 9043940, "track": [{ "lat": -37.6, "lon": 176.1, "timestamp": "2026-05-27T00:00:00Z" }], "count": 1 }

Vessel Change History

Historical field changes for a single vessel, including admin and AIS-observed changes. IMO is preferred when available; MMSI is the fallback.

{ "history": [{ "field_name": "destination", "old_value": "NZMAP", "new_value": "NZTRG", "observed_at": "2026-05-27T00:00:00Z" }], "count": 1 }

Vessel Event Timeline

Derived event feed for a vessel, including future port-call and voyage events.

{ "events": [{ "event_type": "arrival", "title": "Arrived Tauranga", "observed_at": "2026-05-27T00:00:00Z" }], "count": 1 }

Vessel Port Calls

Port-call ledger for a vessel, keyed by IMO first and MMSI second.

{ "port_calls": [{ "port_locode": "NZTRG", "event_type": "arrival", "observed_at": "2026-05-27T00:00:00Z" }], "count": 1 }

Vessel Enrichment

Vessel photo from a licensed Wikimedia Commons lookup (cached 7 days) plus deep links to external maritime references. Keyed by MMSI.

{ "mmsi": 566000000, "imageUrl": "https://upload.wikimedia.org/...", "imageSource": "wikimedia", "wikiUrl": "https://commons.wikimedia.org/...", "cached": true, "externalLinks": [{ "name": "MarineTraffic", "url": "https://..." }] }

Fleet Change History

Fleet-wide vessel field-change feed.

{ "history": [], "count": 0 }

Destination Taxonomy

Supported countries, ports, and optional live vessel counts for normalized destination filters.

{ "countries": [{ "country": "New Zealand", "ports": [] }], "count": 1 }

List Ports

Canonical port search backed by the local ports table. Import UN/LOCODE using `scripts/import-ports.mjs`.

{ "ports": [{ "locode": "NZTRG", "name": "Tauranga", "inbound_vessels": 12 }], "count": 1 }

Port Detail

Canonical port detail with aliases and current activity counters.

{ "port": { "locode": "NZTRG", "name": "Tauranga", "alias_count": 4 }, "aliases": [] }

Port Destination Vessels

Current vessels reporting a normalized destination port.

{ "port": "NZTRG", "vessels": [{ "identity": {}, "destination": {} }], "count": 1 }

Port Call Ledger

Recent port-call events for a port. Public/site access is capped to 7 days; active plans can request up to 366 days.

{ "port_calls": [{ "mmsi": 512345678, "port_locode": "NZTRG", "event_type": "arrival" }], "count": 1 }

List Watchlist

Returns the current user watchlist. API-key requests are tied to the owning user.

{ "watchlist": [] }

Add Watchlist Entry

Adds a vessel to the current user watchlist. Alert notification settings require an active plan.

{ "item": { "id": 1, "mmsi": 566000000 } }

Update Watchlist Entry

Updates label and alert configuration for one watchlist entry.

{ "message": "Updated" }

Remove Watchlist Entry

Deletes one watchlist entry owned by the current user.

{ "message": "Removed" }

List Watchlist Alerts

Returns recent watchlist alerts for the current user.

{ "alerts": [] }

Acknowledge Alerts

Acknowledges selected alerts or all current alerts.

{ "message": "Acknowledged" }

Account Profile

Returns current user profile, subscription, and API-key preview.

{ "user": { "email": "user@example.com", "subscription_status": "active", "api_key_preview": "vt_live_..." } }

Regenerate API Key

Issues a new one-time API key for active-plan users.

{ "api_key": "vt_live_...", "api_key_preview": "vt_live_abc..." }

Update Account

Updates profile name fields or password.

{ "message": "Updated successfully" }

Email Alert Preferences

Gets email alert preferences.

{ "emailAlertsEnabled": true, "emailAlertTypes": [] }

Update Email Alert Preferences

Updates email alert preferences. Active plan required when enabling alert types.

{ "message": "Alert preferences updated" }

Subscription Status

Returns current user billing/access state.

{ "subscriptionStatus": "active", "hasApiAccess": true, "hasApiKey": true }

Create Checkout Session

Starts checkout for VesselTrack Pro at $17 USD/month.

{ "url": "https://checkout.stripe.com/..." }

Create Billing Portal Session

Returns a Stripe billing portal URL for existing customers.

{ "url": "https://billing.stripe.com/..." }

Invoices

Returns recent Stripe invoices for the current customer. Amounts are displayed as USD in the UI.

{ "invoices": [{ "amount_paid": 1700, "currency": "usd" }] }

Confirm Checkout

Synchronizes one completed Checkout session after redirect.

{ "subscriptionStatus": "active" }

Stripe Webhook

Stripe-signed webhook endpoint for subscription and invoice lifecycle events.

{ "received": true }

Register

Creates a user and sends an email verification link.

{ "message": "Account created. Please check your email to verify your address." }

Verify Email

Verifies a registration email token and sends a welcome email.

Redirects to /login?verify=success or an error state.

Resend Verification

Sends a fresh verification link for an unverified account without revealing whether the account exists.

{ "message": "If that email is unverified, a verification link has been sent." }

Request Password Reset

Creates a 1-hour password reset token and emails it through Resend without account enumeration.

{ "message": "If that email exists, a reset link has been sent." }

Confirm Password Reset

Sets a new password from a valid reset token.

{ "message": "Password reset successfully" }

NextAuth

NextAuth session, CSRF, and credentials callback routes.

Managed by NextAuth.

Admin Routes

Admin-only users, vessels, activity, and stats endpoints. These are not external API products.

Admin JSON responses.