Developers

VesselTrack API

A JSON REST API for vessel positions, tracks, port calls, fleet alerts and webhooks, from terrestrial AIS. 5 endpoints are public; the rest need an API key, which comes with Pro (US$17/month).

Get an API keyOpenAPI 3.1 (JSON)Base URL https://www.vesseltrack.net
On this page

Quickstart: five minutes

  1. Get a key. With a Pro account, open Account → API and generate an API key. It is shown once; put it in an environment variable.

    Shell
    export VESSELTRACK_API_KEY="vt_live_…"
  2. Check the feed is live. This endpoint is public. feed.mode is live or stale.

    Request
    curl -s "https://www.vesseltrack.net/api/stats"
  3. Find a vessel by name, IMO or MMSI. Also public.

    Request
    curl -s "https://www.vesseltrack.net/api/vessels/search?q=singap&limit=1"
  4. Read its position and its track with your key. Use the IMO number or the MMSI from the search result.

    Request
    curl -s "https://www.vesseltrack.net/api/vessels/9126003" \
      -H "X-API-Key: $VESSELTRACK_API_KEY"
    Request
    curl -s "https://www.vesseltrack.net/api/vessels/9126003/track?hours=48&limit=3" \
      -H "X-API-Key: $VESSELTRACK_API_KEY"
  5. Follow it. Add the vessel to your watchlist with alert rules, then read alerts from the alert inbox or have them posted to a webhook.

    Request
    curl -s -X POST "https://www.vesseltrack.net/api/watchlist" \
      -H "X-API-Key: $VESSELTRACK_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"identifier":"9169902","label":"Kestrel","group":"Charters","notifyOn":["arrival","departure","speed_threshold"],"speedThreshold":14}'

Prefer a generated client? The whole API is described in /api/openapi.json (OpenAPI 3.1), built from the same source as this page.

Authentication

Send your API key in the X-API-Key header, or as a bearer token. Both are equivalent.

Either header
X-API-Key: $VESSELTRACK_API_KEY
Authorization: Bearer $VESSELTRACK_API_KEY
  • Keys in the URL are not accepted. The old ?api_key= query parameter was removed because URLs end up in logs and browser history. A request that uses it gets a 401 that says so.
  • Keys start with vt_live_. Only a hash is stored, so a key cannot be shown again; generating a new one at Account → API replaces the old key immediately. Each account has one key.
  • A key works while its account has Pro access, including the grace period after a failed payment. After that it returns 401.
  • A key reads and writes your data (watchlist, alerts, areas, webhooks). It cannot change the password, manage billing or create another key; those need a signed-in browser session.
  • Responses carry CORS headers, so the public endpoints can be called from a browser. Do not put your key in code that runs in other people’s browsers.

Each endpoint below is marked with what it needs:

LabelMeaning
PublicNo credentials. Served to anyone and cached at the CDN. Not counted against your key’s hourly allowance, but limited per IP address: far more requests than a person using the map would send get 429 with Retry-After.
API keyAn API key. (The website reaches the same endpoint with the cookie it sets for its own pages; that cookie is rate limited per visitor and per IP address, and is not an API credential.)
API key or signed-in sessionActs on one account’s data. Send an API key, or call it from a signed-in browser session.
ProNeeds Pro access. An API key always qualifies, because keys only work while the account has Pro. A signed-in free account gets 403 upgrade_required.

Any endpoint that is not public can answer with these before your request reaches it:

StatusWhenBody
401The key is unknown, was rotated, or its account no longer has Pro access.{"error":"Invalid or expired API key. An active Pro subscription is required."}
401The key was sent as ?api_key= in the URL instead of in a header.{"error":"API keys in the URL are not accepted. Send the key in the X-API-Key header (or Authorization: Bearer)."}
403No API key and no site session.{"error":"Unauthorized. Access requires a valid API key or an active site session."}
429The key has used its hourly allowance. Retry-After says how many seconds until a slot frees.{"error":"API rate limit exceeded. Limit is 3600 requests per hour."}
429Many keys that are not valid were sent from this IP address in the last ten minutes. Until Retry-After has passed, keys that were not accepted recently are refused without being checked; a key in recent successful use keeps working.{"error":"Too many requests with API keys that are not valid. Check the key, then retry later."}

Rate limits

An account’s key may make 3,600 requests per rolling hour by default. Every response to a request made with a key says where you stand:

HeaderMeaning
X-RateLimit-LimitRequests allowed per rolling hour for this account.
X-RateLimit-RemainingRequests left in the current hour, after this one.
Retry-AfterOn a 429 only: seconds until the oldest request in the window is an hour old and a slot frees.
  • Over the limit you get 429. Rejected requests are not counted, so the window drains on its own.
  • Public endpoints are not counted against your key and return no rate-limit headers. They are cached at the CDN for up to a minute; polling faster than that returns the same response. They do have a per-IP-address limit, set well above what a person using the map sends, and answer 429 with Retry-After past it.
  • An IP address that sends many invalid keys in a short time gets 429 for further unknown keys until Retry-After has passed. Check the key before retrying in a loop.
  • See your usage at Account → API or with GET /api/account/usage.
  • The website’s own pages call some of these endpoints with a browser cookie instead of a key. That cookie is limited per visitor and per IP address for interactive use and answers 429 with Retry-After when exceeded. It is not an API credential; use a key for programmatic access.
  • Without a key, the two bulk listings (GET /api/vessels and GET /api/ports/{locode}/vessels) also count the rows they return: 1,000 an hour per browser, 2,000 an hour per IP address, with daily ceilings, then 429 with code preview_limit.
  • These per-visitor and per-address limits are counted on each server instance separately. They stop casual scraping; they are not a quota you can plan against. The per-key hourly allowance is counted in the database and holds across all of them.

Errors

Errors are JSON with an error sentence for a person. When a client can act on the error, a machine-readable code is included, along with upgrade_url or limit where they apply.

Error body
{
  "error": "Track export requires VesselTrack Pro.",
  "code": "upgrade_required",
  "upgrade_url": "/pricing"
}
StatusMeaning
400A parameter or body is malformed. The message names it. Unknown filter values are errors, not ignored.
401The API key is invalid, or the endpoint needs an account and none is identified.
403No credentials at all, or the feature needs Pro (code upgrade_required).
404No such vessel, port or resource, or it belongs to another account.
409A conflict: a plan limit is full (limit_reached), or the thing already exists (duplicate).
429Rate limited. Wait for Retry-After seconds.
500{"error":"Internal server error"}. Safe to retry with backoff.
codeStatusMeaning
upgrade_required403The feature needs Pro. The body includes upgrade_url.
limit_reached409A plan limit is full (watchlist, alert areas, webhook endpoints). The body includes limit and upgrade_url.
duplicate409The vessel is already on the watchlist.
test_rate_limited429A webhook test was sent to that endpoint moments ago.
rate_limited429Too many webhook create, update, test or rotate-secret calls from this account. The response has Retry-After.
preview_limit429A bulk listing (GET /api/vessels, GET /api/ports/{locode}/vessels) was called without an API key and its preview row allowance is used up. The body includes retry_after_seconds and upgrade_url.
not_redeliverable409That webhook delivery cannot be queued again.
endpoint_disabled409The webhook endpoint is switched off.

Pagination

  • Offset paging on vessel, port, event and port-call lists: limit and offset. Responses echo the values that were applied, with count (rows in this page) and, where it is cheap to compute, total.
  • Cursor paging on the alert inbox and webhook delivery log: pass before=<id of the last item you received> and stop when hasMore is false.
  • A limit, offset, hours or days beyond the maximum is clamped, not rejected. Read the applied value from the response rather than assuming yours was used.
  • Results that are cut off say so: truncated: true on the map and track endpoints. A truncated track holds the most recent points; a truncated JSON map response holds the most recently heard vessels, and the map’s compact format says sampled: true when it returns a spatially fair sample instead.
  • GET /api/vessels allows up to 10,000 rows per page with a key (without one, 500 rows and an offset of at most 500). Order is by last position time, which keeps changing, so a vessel can move between pages while you page; de-duplicate by MMSI.

Plans and limits

The API key is part of Pro. These are the limits the server enforces; see pricing for the plans themselves.

FreePro
Vessels on the watchlist10500
Alert rules on watched vessels—Yes
Alert areas—20
Webhook endpoints—5
Track history24 hours30 days
Track points per request2,00050,000
Exports (track CSV / GeoJSON / GPX / KML, fleet CSV / JSON)—Yes
Field-change history, event timeline, vessel port calls—Yes
API key—Yes
API requests per hour—3,600

Without Pro, port calls at a port go back 7 days. How long each kind of record exists at all, on any plan:

RecordKept for
Track positions (about one point every five minutes per vessel)30 days
Field-change history30 days
Vessel events90 days
Port calls90 days
Alerts90 days
API request records30 days

There is no archive beyond these periods, and no way to request older data.

About the data

  • Terrestrial AIS only. Positions come from shore-based receivers. Coverage is good near coasts, ports and busy lanes and absent mid-ocean. There is no satellite AIS. A vessel out of range keeps its last known position: always read last_position_update.
  • The feed can be offline. When the newest position anywhere is more than 30 minutes old, GET /api/stats and GET /api/vessels/map report mode: "stale". While it is offline no track points, events or alerts are produced, and they are not back-filled afterwards.
  • “Not available” is null. AIS encodes missing values as numbers (speed 102.3, course 360, heading 511, latitude 91). Decoded responses turn these into null; the decoded objects in a vessel record keep the original in raw. The map positions endpoint is the exception: in its JSON records heading stays 511 and sog is 0, and its compact format uses -1 for a missing direction or speed.
  • Track history is 30 days at about five-minute resolution. One point is stored per vessel roughly every five minutes while it is being received, so short manoeuvres between points are not recorded. Port calls and events are kept 90 days.
  • Ship-supplied text is unverified. Names, call signs and destinations are typed into a transponder and broadcast by radio. Treat them as untrusted input: escape them in HTML, and neutralise them before writing spreadsheet cells.
  • Identifiers. Vessel paths accept an IMO number (7 digits) or an MMSI (up to 9). MMSIs can be reused or mis-set; IMO numbers are broadcast by the ship and not checked against a register.
  • Port calls are inferred. An arrival is a vessel coming to a stop near a known port; a destination match is a best effort on free text. Each record carries a confidence.
  • Times are UTC, ISO 8601. ETA is inferred from the month, day, hour and minute the ship reports, which has no year.
  • Not for navigation. Do not use this data for collision avoidance or any safety-critical decision. See the terms.

Ship categories used by ship_category, alert areas and webhook filters:

SlugNameAIS ship-type codes
cargoCargo70–79
tankerTanker80–89
passengerPassenger60–69
fishingFishing30
tugTug52
towingTowing31–32
sailingSailing36
pleasurePleasure craft37
hscHigh-speed craft40–49
militaryMilitary35
pilotPilot vessel50
sarSearch & rescue51
dredgingDredging33
divingDiving ops34
otherOther / unknowneverything else, and vessels with no ship type

Alert types, used by watchlist rules, the alert inbox and alert.* webhook events:

KeyNameRaised when
arrivalArrivalThe vessel reports it has moored or anchored.
departureDepartureThe vessel gets under way after being moored or at anchor.
destinationDestination changeThe crew enters a new destination in the AIS transponder.
nav_statusNavigation status changeAny change of reported status, e.g. under way → restricted manoeuvrability.
sogSpeed changeSpeed over ground changes by 2 knots or more between reports.
speed_thresholdSpeed thresholdSpeed crosses the threshold you set, in either direction.
heading_changeCourse alterationHeading changes by at least the number of degrees you set.
ais_gapAIS signal lostNo position report has been received for the period you set.
nameName changeThe vessel starts broadcasting a different name.
ship_typeShip type changeThe broadcast ship-type code changes.
area_enterEntered areaA matching vessel crosses into one of your alert areas.
area_exitLeft areaA matching vessel leaves one of your alert areas.

Vessels

Current positions and static data for every vessel received, plus each vessel’s track, field-change history, events and port calls.

GET/api/vessels/mapPublic

Map positions

Lightweight position records for drawing vessels on a map, optionally limited to a bounding box: one object per vessel, or the compact columnar format the live map uses.

Two formats. format=json (the default) returns one object per vessel, the most recently heard first, cut off at limit. format=compact returns one integer array per field, allows larger limits, and when more vessels match than fit it returns a spatially fair sample instead of the most recent ones; it is what the live map downloads, and the better choice for drawing many vessels. Both formats select vessels with the same filters.

Without stale_minutes, only vessels heard in the last 24 hours are returned. Vessels with no ship type are left out unless you filter by ship type or pass show_unknown=1. Both rules apply to mmsi lookups too.

freshness tells you whether the feed is live. mode is "stale" when the newest position anywhere in the feed is more than 30 minutes old (the data collector is offline); the 24-hour window is then measured from that newest position, so you get the last known picture rather than an empty result.

JSON records are lightweight, not decoded: heading is 511 when the ship does not report one (use cog instead), and sog is 0 when speed is not available. Use the vessel detail endpoint for decoded values.

Responses are public and cached. A shared cache (the CDN) keeps each URL for 60 seconds and may serve it for up to 120 seconds longer while it fetches a fresh copy; browsers keep a JSON response for 15 seconds and a compact one for 20. A response can therefore be a few minutes old: freshness, and asOf in the compact format, tell you how old. Snap bbox to a grid so repeated requests share a cache entry.

Access: Public. No credentials. Served to anyone and cached at the CDN. Not counted against your key’s hourly allowance, but limited per IP address: far more requests than a person using the map would send get 429 with Retry-After.

Query parameters

NameTypeDefault / limitsDescription
formatstringdefault json · json | compactjson: one object per vessel (the first response below). compact: one array per field, with its own limits, names only for small boxes and lookups, and sampling when more vessels match than fit (the second response below).
bboxwest,south,east,north—Only vessels inside this box, in decimal degrees (rounded to 2 decimals). west greater than east means the box crosses the antimeridian.
ship_categorycomma-separated slugs≤ 20 valuesShip categories: cargo, tanker, passenger, fishing, tug, towing, sailing, pleasure, hsc, military, pilot, sar, dredging, diving, other. A category covers a range of AIS codes (cargo is 70–79). other also matches vessels with no ship type.
ship_typecomma-separated integers≤ 100 valuesExact AIS ship-type codes, 0–99. ship_type=70 matches code 70 only, not all cargo ships. Combined with ship_category, a vessel matching either is returned.
nav_statuscomma-separated integers≤ 16 valuesAIS navigational status codes, 0–15 (0 under way using engine, 1 at anchor, 5 moored, …).
fix_typecomma-separated integers≤ 16 valuesAIS position-fix device codes, 0–15 (1 GPS, 2 GLONASS, …).
flagcomma-separated≤ 20 valuesFlag states, each given as a 3-digit MID (512), an ISO 3166-1 alpha-2 code (NZ) or a country name (New Zealand). The flag is read from the first three digits of the MMSI. An unknown value is a 400, not an ignored filter.
sog_minnumber0–102.2Minimum speed over ground, knots. Vessels whose speed is “not available” never match a speed bound.
sog_maxnumber0–102.2Maximum speed over ground, knots.
has_namestring1 | trueOnly vessels that broadcast a name.
stale_minutesinteger1–527040Only vessels whose last position is newer than this many minutes.
updated_sinceISO 8601 timestamp—Only vessels whose last position is at or after this ISO 8601 instant.
updated_beforeISO 8601 timestamp—Only vessels whose last position is at or before this ISO 8601 instant.
destinationstring2–40 charsSubstring of the destination text the crew entered (case-insensitive).
destination_portcomma-separated UN/LOCODEs≤ 20 valuesVessels whose destination resolves to one of these ports, e.g. SGSIN,NLRTM. Alias: dest_ports.
destination_countrycomma-separated≤ 20 valuesVessels bound for one of these countries, as names or ISO alpha-2 codes. Alias: dest_countries. Ports and countries are OR-ed together.
destination_citycomma-separated≤ 20 valuesVessels bound for one of these cities. AND-ed with the port/country selection.
mmsicomma-separated MMSIs≤ 100 valuesOnly these vessels (up to 100 MMSIs of up to nine digits each). They must still match the other filters and the recency window: add stale_minutes and show_unknown=1 to find a vessel whatever its age or type. A vessel that does not match is simply absent. In the compact format a lookup always carries names and is never sampled.
show_unknownstring1Include vessels that have not reported a ship type.
limitinteger1–50000Maximum vessels. A larger value is clamped; the response reports the limit applied. JSON format: the ceiling depends on how much of the world you ask for: without bbox, default 2,000 and maximum 2,000; with a bbox wider than 90° of longitude or taller than 60° of latitude, default 5,000 and maximum 5,000; with a smaller bbox, default 5,000 and maximum 20,000. Compact format: the default is the maximum, which is 50,000 when the response carries no names (no bbox, or a bbox larger than 24° × 16°), 20,000 when it carries names, and 100 for an mmsi lookup.
Request
curl -s "https://www.vesseltrack.net/api/vessels/map?bbox=103,0.5,105,2&ship_category=cargo,tanker&limit=2"
Response · 200 · application/json · format=json (default)
{
  "count": 2,
  "limit": 2,
  "truncated": true,
  "freshness": {
    "mode": "live",
    "latestPositionUpdate": "2026-11-16T20:54:13.428Z",
    "feedAgeMinutes": 2,
    "windowMinutes": 1440
  },
  "vessels": [
    {
      "mmsi": 636642599,
      "lat": 1.271459,
      "lon": 103.954627,
      "heading": 83,
      "cog": 124.7,
      "ship_type": 89,
      "sog": 0.1,
      "name": "FRONT SPIRIT",
      "nav_status": 1,
      "last_position_update": "2026-11-16T20:54:09.428Z"
    },
    {
      "mmsi": 239894373,
      "lat": 1.245145,
      "lon": 103.934406,
      "heading": 167,
      "cog": 50,
      "ship_type": 70,
      "sog": 0.2,
      "name": "AEGEAN NAVIGATOR",
      "nav_status": 1,
      "last_position_update": "2026-11-16T20:53:58.428Z"
    }
  ]
}

Vessels inside the box that match the filters.

truncated
true when more vessels matched than limit; you have the most recently heard limit of them.
freshness.mode
"live" or "stale" for the whole feed, independent of your filters.
freshness.windowMinutes
The recency window applied to this response.
vessels[].heading
True heading in degrees; 511 = not available.
vessels[].cog
Course over ground in degrees, or null.

Response with format=compact

One array per field instead of one object per vessel, integers only. Every column holds count entries, and entry i of every column describes the same vessel. Rows are in MMSI order.

Names are included only where a map would draw them: for a bbox no wider than 24° of longitude and no taller than 16° of latitude, and for mmsi lookups. Without a bbox, or with a larger one, you get positions, ship types, speeds and ages but no names (names is false and there is no name column); look the names you need up with mmsi. A response with names that would exceed 4 MB is sent without them.

When more vessels match than fit (more than 97% of limit), the response is a spatially fair sample, not the most recent ones: the box (the whole world without bbox) is cut into a grid about 128 cells across, cells with few vessels keep all of them, and busier cells are thinned to a common level by a fixed hash of the MMSI. sampled is then true, total says how many matched, and count how many you got: at most limit, usually a little below it at the sizes the map asks for (thousands), but with a limit of a few dozen or less it can be well below, because the thinning works per cell. The choice is deterministic: repeated requests return the same vessels while the data is unchanged, a smaller limit returns very nearly a subset of a larger one, and a smaller box keeps nearly every vessel a larger one showed inside it and adds more. Zoom in (a smaller bbox) to get every vessel. mmsi lookups are never sampled.

Request
curl -s "https://www.vesseltrack.net/api/vessels/map?format=compact&bbox=103,0.5,105,2&ship_category=cargo,tanker&sog_min=8"
Response · 200 · application/json · format=compact
{
  "format": "compact-v1",
  "count": 4,
  "limit": 20000,
  "total": 4,
  "sampled": false,
  "truncated": false,
  "freshness": {
    "mode": "live",
    "latestPositionUpdate": "2026-11-17T01:11:04.531Z",
    "feedAgeMinutes": 1,
    "windowMinutes": 1440
  },
  "asOf": 1794877925,
  "scale": 10000,
  "names": true,
  "mmsi": [239361843, 111911365, 19190441, 266388212],
  "lat": [19705, 17760, 16241, 12295],
  "lon": [1048649, 1047544, 1047403, 1039055],
  "dir": [208, 210, 27, 258],
  "type": [79, 70, 70, 70],
  "sog": [196, 105, 138, 195],
  "age": [3, 4, 3, 2],
  "name": ["MSC ODYSSEY", "CRYSTAL LEGEND", "BALTIC GLORY", "APL UNITY"]
}
format
Always "compact-v1" for the layout described here.
count
Rows in this response: the length of every column.
limit
The row limit applied.
total
Vessels that matched the filters and window, before sampling. At least count.
sampled
true when the rows are a spatially fair sample of total (above); false when every match is included.
truncated
true when fewer rows were returned than matched (total > count).
freshness
As in the JSON format.
asOf
When the rows were read, in epoch seconds. age counts back from it; it also shows how long the response has been cached.
scale
lat and lon are integers in 1/scale degrees: divide by scale. 1,000 without bbox and for large boxes, finer for smaller boxes and for mmsi lookups, always finer than a screen pixel at the zoom such a box is drawn at. Read it from every response.
names
Whether the name column is present (see above).
mmsi
MMSIs in ascending order, delta-encoded: the first value is an MMSI, each later value is the difference from the previous MMSI. Rebuild them with a running sum.
lat, lon
Latitude and longitude as integers; divide by scale.
dir
Direction the marker points, whole degrees 0–359: the true heading, else the course over ground. -1 when there is none to show: moored or at anchor, slower than 0.5 knots, or neither heading nor course reported.
type
AIS ship-type code 0–99; 0 when unknown.
sog
Speed over ground in tenths of a knot (196 = 19.6 kn); -1 when not available.
age
Whole minutes from the position report to asOf: the report was made at about asOf − age × 60.
name
Only when names is true. The name as broadcast ("@" padding removed, at most 40 characters), or null when the vessel broadcasts none. Untrusted radio text: escape it before display.
Decoding (JavaScript)
// body: the parsed JSON of a format=compact response
const vessels = [];
let mmsi = 0;
for (let i = 0; i < body.count; i++) {
  mmsi += body.mmsi[i]; // the first value is an MMSI, then differences
  vessels.push({
    mmsi,
    lat: body.lat[i] / body.scale,
    lon: body.lon[i] / body.scale,
    direction: body.dir[i] === -1 ? null : body.dir[i],
    shipType: body.type[i],
    knots: body.sog[i] === -1 ? null : body.sog[i] / 10,
    reportedAt: new Date((body.asOf - body.age[i] * 60) * 1000),
    name: body.names ? body.name[i] : undefined, // undefined: not sent; null: none broadcast
  });
}

Errors

StatusWhenBody
400A filter is malformed, names something unknown, or has more than 20 values.{"error":"Unknown flag \"Atlantis\". Use a 3-digit MID, an ISO 3166 alpha-2 code, or a country name."}
400bbox is not four numbers, or has no area.{"error":"bbox must be west,south,east,north in decimal degrees"}
400format is not json or compact.{"error":"format must be json or compact"}
400mmsi is not a comma-separated list of up to 100 MMSIs of up to nine digits.{"error":"mmsi must be a comma-separated list of MMSIs (up to 9 digits)"}
GET/api/vessels/searchPublic

Search

Find vessels by name, call sign, IMO, MMSI or destination, and ports by name or UN/LOCODE.

Digits are treated as an identifier: exact MMSI, exact IMO, then MMSI/IMO prefixes. Text is matched against call sign and name (exact, then prefix, then contains) and finally destination. A leading “IMO” or “MMSI” label is ignored, so “IMO 9321483” works.

ports holds up to 5 ports for text queries, and is empty for numeric ones.

Access: Public. No credentials. Served to anyone and cached at the CDN. Not counted against your key’s hourly allowance, but limited per IP address: far more requests than a person using the map would send get 429 with Retry-After.

Query parameters

NameTypeDefault / limitsDescription
qrequiredstring2–40 charsSearch text, 2–40 characters after trimming. Punctuation other than . - ' & / ( ) is treated as a space.
limitintegerdefault 20 · 1–50Maximum vessels.
Request
curl -s "https://www.vesseltrack.net/api/vessels/search?q=singap&limit=1"
Response · 200 · application/json
{
  "count": 1,
  "query": "SINGAP",
  "vessels": [
    {
      "identity": {
        "mmsi": 215240179,
        "name": "ONE SINGAPORE",
        "call_sign": "9HQ7",
        "imo": 9447275,
        "flag_country": "Malta",
        "flag_emoji": "🇲🇹",
        "destination": "ROTERDAM",
        "reported_destination": "ROTERDAM",
        "matched_destination": null
      },
      "…": "the remaining vessel fields, as in vessel detail",
      "match": "name",
      "match_type": "contains"
    }
  ],
  "ports": [
    {
      "locode": "SGSIN",
      "name": "Singapore",
      "city": "Singapore",
      "country": "Singapore",
      "country_code": "SG",
      "lat": 1.26,
      "lon": 103.83,
      "match": "name"
    }
  ]
}

Matching vessels, best match first, and matching ports.

query
The query as normalised (upper-cased, trimmed).
vessels[]
A full vessel object (see vessel detail) plus match and match_type.
vessels[].match
Which field matched: mmsi, imo, call_sign, name or destination.
vessels[].match_type
exact, prefix or contains.
ports[].match
name or locode.

Errors

StatusWhenBody
400q is missing, shorter than 2 or longer than 40 characters.{"error":"Search query must be at least 2 characters"}
GET/api/vesselsAPI key

List vessels

Paginated, fully decoded vessel records, most recently heard first.

Takes the same filters as the map endpoint. Unlike the map, there is no default recency window: every vessel with a position is included unless you pass stale_minutes or updated_since, and stale_minutes is always measured from the present.

The response reports the limits that were applied (limit, offset, max_limit, and max_offset without a key) and access: "plan" for an API key, "public" otherwise. Responses are private and not cached.

Without an API key (the website’s cookie, signed in or not) every row served counts against a preview allowance shared by this endpoint and the other bulk listing: 1,000 rows an hour and 3,000 a day per browser, 2,000 an hour and 6,000 a day per IP address. limit is reduced to what is left, and once nothing is left the request is refused before any query runs. Those responses carry preview.rows_remaining.

Access: API key. Full paging (limit up to 10,000, any offset, raw=true) needs an API key. Without one — including a signed-in Pro user browsing the site — limit and offset are capped at 500 each, raw is ignored, and rows come out of a preview allowance (below).

Query parameters

NameTypeDefault / limitsDescription
bboxwest,south,east,north—Only vessels inside this box, in decimal degrees (rounded to 2 decimals). west greater than east means the box crosses the antimeridian.
ship_categorycomma-separated slugs≤ 20 valuesShip categories: cargo, tanker, passenger, fishing, tug, towing, sailing, pleasure, hsc, military, pilot, sar, dredging, diving, other. A category covers a range of AIS codes (cargo is 70–79). other also matches vessels with no ship type.
ship_typecomma-separated integers≤ 100 valuesExact AIS ship-type codes, 0–99. ship_type=70 matches code 70 only, not all cargo ships. Combined with ship_category, a vessel matching either is returned.
nav_statuscomma-separated integers≤ 16 valuesAIS navigational status codes, 0–15 (0 under way using engine, 1 at anchor, 5 moored, …).
fix_typecomma-separated integers≤ 16 valuesAIS position-fix device codes, 0–15 (1 GPS, 2 GLONASS, …).
flagcomma-separated≤ 20 valuesFlag states, each given as a 3-digit MID (512), an ISO 3166-1 alpha-2 code (NZ) or a country name (New Zealand). The flag is read from the first three digits of the MMSI. An unknown value is a 400, not an ignored filter.
sog_minnumber0–102.2Minimum speed over ground, knots. Vessels whose speed is “not available” never match a speed bound.
sog_maxnumber0–102.2Maximum speed over ground, knots.
has_namestring1 | trueOnly vessels that broadcast a name.
stale_minutesinteger1–527040Only vessels whose last position is newer than this many minutes.
updated_sinceISO 8601 timestamp—Only vessels whose last position is at or after this ISO 8601 instant.
updated_beforeISO 8601 timestamp—Only vessels whose last position is at or before this ISO 8601 instant.
destinationstring2–40 charsSubstring of the destination text the crew entered (case-insensitive).
destination_portcomma-separated UN/LOCODEs≤ 20 valuesVessels whose destination resolves to one of these ports, e.g. SGSIN,NLRTM. Alias: dest_ports.
destination_countrycomma-separated≤ 20 valuesVessels bound for one of these countries, as names or ISO alpha-2 codes. Alias: dest_countries. Ports and countries are OR-ed together.
destination_citycomma-separated≤ 20 valuesVessels bound for one of these cities. AND-ed with the port/country selection.
limitintegerdefault 500 · 1–10000Page size.
offsetintegerdefault 0 · 0–1000000Rows to skip.
rawstringtrue | 1Return flat database-style rows (snake_case columns, “not available” values as null) plus destination_normalized, instead of decoded objects.
Request
curl -s "https://www.vesseltrack.net/api/vessels?ship_category=tanker&limit=1" \
  -H "X-API-Key: $VESSELTRACK_API_KEY"
Response · 200 · application/json
{
  "count": 1,
  "total": 432,
  "limit": 1,
  "offset": 0,
  "access": "plan",
  "max_limit": 10000,
  "vessels": [
    {
      "identity": {
        "mmsi": 308738947,
        "name": "CAPE DREAM",
        "call_sign": "C6EE",
        "imo": 9126003,
        "flag_country": "Bahamas",
        "flag_emoji": "🇧🇸",
        "destination": "USLAX>USNYC",
        "reported_destination": "USLAX>USNYC",
        "matched_destination": "New York, USA"
      },
      "ship_type": {
        "code": 70,
        "label": "Cargo"
      },
      "cargo": {
        "category": null,
        "description": null,
        "detail": null
      },
      "dimensions": {
        "a": 206,
        "b": 43,
        "c": 20,
        "d": 20,
        "length_m": 249,
        "beam_m": 40
      },
      "draught_m": 9,
      "eta": {
        "month": 11,
        "day": 26,
        "hour": 20,
        "minute": 47,
        "timestamp": "2026-11-26T20:47:00.000Z",
        "precision": "minute"
      },
      "navigation": {
        "lat": 19.222241,
        "lon": -107.550136,
        "sog": {
          "raw": 11.8,
          "knots": 11.8,
          "label": "11.8 kn"
        },
        "cog": {
          "raw": 129,
          "degrees": 129,
          "arrow": "↘"
        },
        "heading": {
          "raw": 132,
          "degrees": 132,
          "label": "132°"
        },
        "rate_of_turn": {
          "raw": -1.1,
          "deg_per_min": -0.05,
          "label": "0.05°/min left"
        }
      },
      "status": {
        "nav_status": {
          "code": 0,
          "text": "Under way using engine"
        },
        "special_manoeuvre": {
          "code": 0,
          "text": "Not available (default)"
        }
      },
      "ais": {
        "version": {
          "code": 0,
          "text": "ITU-R M.1371-1 (2001)"
        },
        "fix_type": {
          "code": 1,
          "text": "GPS"
        }
      },
      "timestamps": {
        "first_seen": "2026-07-23T19:59:15.428Z",
        "last_position_update": "2026-11-16T20:51:58.428Z",
        "last_static_update": "2026-11-16T20:51:06.428Z"
      },
      "destination_normalized": {
        "raw": "USLAX>USNYC",
        "reported": "USLAX>USNYC",
        "matched_destination": "New York, USA",
        "port_code": "USNYC",
        "port_name": "New York/New Jersey",
        "city": "New York",
        "country": "USA",
        "country_code": "US",
        "confidence": "code",
        "matched_text": "USNYC"
      }
    }
  ]
}

One page of vessels.

total
Vessels matching the filters. Cached for up to a minute when no filter is set.
vessels[]
Vessel objects, as in vessel detail.
preview
Only without an API key: { rows_per_hour, rows_remaining }. rows_per_hour is the per-browser hourly allowance (1,000); rows_remaining is what is left, after this response, in whichever window (browser or address, hour or day) is closest to running out.

Errors

StatusWhenBody
400A filter is malformed, names something unknown, or has more than 20 values.{"error":"Unknown flag \"Atlantis\". Use a 3-digit MID, an ISO 3166 alpha-2 code, or a country name."}
429No API key, and the preview row allowance is used up. Retry-After and retry_after_seconds say when rows are available again.{"error":"Preview allowance used: without an API key these listings return a limited number of rows per hour. Bulk access is part of the Pro API.","code":"preview_limit","retry_after_seconds":1260,"upgrade_url":"/pricing"}
GET/api/vessels/{id}API key

Vessel detail

One vessel’s current position, voyage and static data, decoded.

Values the transponder reports as “not available” are null: speed, course, heading, rate of turn, draught, ETA, IMO, dimensions. Decoded objects such as navigation.sog keep the AIS sentinel in raw (102.3 for speed, 360 for course, 511 for heading) so you can tell “not available” from absent.

destination is free text typed by the crew. destination_normalized is our best match to a port; confidence says how it was matched. eta.timestamp is inferred from the month/day/hour/minute the ship reports, which carries no year.

Names, call signs and destinations are broadcast over radio by the ship and are not verified. Escape them before putting them in HTML, SQL or a spreadsheet.

Access: API key. An API key. (The website reaches the same endpoint with the cookie it sets for its own pages; that cookie is rate limited per visitor and per IP address, and is not an API credential.)

Path parameters

NameTypeDefault / limitsDescription
idrequiredIMO or MMSI1–9 charsA 7-digit IMO number or an MMSI (up to 9 digits). Seven digits are looked up as an IMO first, then as an MMSI.
Request
curl -s "https://www.vesseltrack.net/api/vessels/9126003" \
  -H "X-API-Key: $VESSELTRACK_API_KEY"
Response · 200 · application/json
{
  "vessel": {
    "identity": {
      "mmsi": 308738947,
      "name": "CAPE DREAM",
      "call_sign": "C6EE",
      "imo": 9126003,
      "flag_country": "Bahamas",
      "flag_emoji": "🇧🇸",
      "destination": "USLAX>USNYC",
      "reported_destination": "USLAX>USNYC",
      "matched_destination": "New York, USA"
    },
    "ship_type": {
      "code": 70,
      "label": "Cargo"
    },
    "cargo": {
      "category": null,
      "description": null,
      "detail": null
    },
    "dimensions": {
      "a": 206,
      "b": 43,
      "c": 20,
      "d": 20,
      "length_m": 249,
      "beam_m": 40
    },
    "draught_m": 9,
    "eta": {
      "month": 11,
      "day": 26,
      "hour": 20,
      "minute": 47,
      "timestamp": "2026-11-26T20:47:00.000Z",
      "precision": "minute"
    },
    "navigation": {
      "lat": 19.222241,
      "lon": -107.550136,
      "sog": {
        "raw": 11.8,
        "knots": 11.8,
        "label": "11.8 kn"
      },
      "cog": {
        "raw": 129,
        "degrees": 129,
        "arrow": "↘"
      },
      "heading": {
        "raw": 132,
        "degrees": 132,
        "label": "132°"
      },
      "rate_of_turn": {
        "raw": -1.1,
        "deg_per_min": -0.05,
        "label": "0.05°/min left"
      }
    },
    "status": {
      "nav_status": {
        "code": 0,
        "text": "Under way using engine"
      },
      "special_manoeuvre": {
        "code": 0,
        "text": "Not available (default)"
      }
    },
    "ais": {
      "version": {
        "code": 0,
        "text": "ITU-R M.1371-1 (2001)"
      },
      "fix_type": {
        "code": 1,
        "text": "GPS"
      }
    },
    "timestamps": {
      "first_seen": "2026-07-23T19:59:15.428Z",
      "last_position_update": "2026-11-16T20:51:58.428Z",
      "last_static_update": "2026-11-16T20:51:06.428Z"
    },
    "destination_normalized": {
      "raw": "USLAX>USNYC",
      "reported": "USLAX>USNYC",
      "matched_destination": "New York, USA",
      "port_code": "USNYC",
      "port_name": "New York/New Jersey",
      "city": "New York",
      "country": "USA",
      "country_code": "US",
      "confidence": "code",
      "matched_text": "USNYC"
    }
  },
  "lookup": {
    "requestedIdentifier": "9126003",
    "canonicalIdentifier": "9126003",
    "canonicalType": "imo"
  }
}

The vessel, and how the identifier was resolved.

lookup.canonicalIdentifier
The IMO number when the vessel has a valid one, otherwise the MMSI.
vessel.timestamps.last_position_update
When the position was received. Check it: a vessel out of range keeps its last position.

Errors

StatusWhenBody
400The identifier is not 1–9 digits.{"error":"Invalid vessel identifier"}
404No vessel with that IMO number or MMSI has been received.{"error":"Vessel not found"}
GET/api/vessels/{id}/trackAPI key

Track

A vessel’s recorded positions, as JSON or as a CSV, GeoJSON, GPX or KML file.

Track history is kept for 30 days at roughly five-minute resolution, then deleted. Points are ordered oldest to newest. When more points exist than limit, you get the most recent limit points and truncated is true.

hours above your plan’s depth is clamped, not rejected; the response reports the hours and limit that were applied and max_hours for your plan.

format=csv | geojson | gpx | kml returns a file download (Content-Disposition: attachment) named <vessel>-track-<range>-<YYYYMMDD>.<ext> (UTC date), with an X-Track-Truncated header. <range> is the look-back: 24h, 3d, 7d, 30d for the standard ranges, otherwise <N>d for whole days or <N>h. For exports limit defaults to the plan maximum. The CSV starts with a UTF-8 byte-order mark so spreadsheet programs read it as UTF-8. Text from the ship is escaped for each format, and CSV cells that would be read as a formula are neutralised.

Access: API key. With an API key: up to 30 days (720 hours) and 50,000 points per request, and file exports. Without Pro: the last 24 hours, 2,000 points, JSON only.

Path parameters

NameTypeDefault / limitsDescription
idrequiredIMO or MMSI1–9 charsA 7-digit IMO number or an MMSI (up to 9 digits). Seven digits are looked up as an IMO first, then as an MMSI.

Query parameters

NameTypeDefault / limitsDescription
hoursintegerdefault 24 · 1–720Look-back window in hours.
limitintegerdefault 500 · 1–50000Maximum points. Default 500 for JSON.
formatstringdefault json · json | csv | geojson | gpx | kmlResponse format. Anything but json is a Pro file export.
Request
curl -s "https://www.vesseltrack.net/api/vessels/9126003/track?hours=48&limit=3" \
  -H "X-API-Key: $VESSELTRACK_API_KEY"
Response · 200 · application/json
{
  "mmsi": 308738947,
  "imo": 9126003,
  "lookup": {
    "requestedIdentifier": "9126003",
    "canonicalIdentifier": "9126003",
    "canonicalType": "imo"
  },
  "count": 3,
  "truncated": true,
  "access": "plan",
  "max_hours": 720,
  "hours": 48,
  "limit": 3,
  "track": [
    {
      "lat": 19.263912,
      "lon": -107.604314,
      "sog": 11.9,
      "cog": 130.3,
      "heading": 131,
      "nav_status": 0,
      "timestamp": "2026-11-16T20:31:58.428Z"
    },
    {
      "lat": 19.243081,
      "lon": -107.577231,
      "sog": 11.8,
      "cog": 128.4,
      "heading": 128,
      "nav_status": 0,
      "timestamp": "2026-11-16T20:41:58.428Z"
    },
    {
      "lat": 19.222241,
      "lon": -107.550136,
      "sog": 11.8,
      "cog": 129,
      "heading": 132,
      "nav_status": 0,
      "timestamp": "2026-11-16T20:51:58.428Z"
    }
  ]
}

The track, oldest point first.

access
"plan" with Pro access, "public" otherwise.
max_hours
The deepest look-back your plan allows.
track[].sog / cog / heading
Knots / degrees; null when the ship did not report a value.

Errors

StatusWhenBody
400format is not one of the supported values.{"error":"format must be one of: json, csv, geojson, gpx, kml"}
403A file format was requested without Pro access.{"error":"Track export requires VesselTrack Pro.","code":"upgrade_required","upgrade_url":"/pricing"}
404No vessel with that IMO number or MMSI has been received.{"error":"Vessel not found"}
GET/api/vessels/{id}/historyPro

Field-change history

Every recorded change to a vessel’s static and voyage fields: name, destination, draught, ETA and so on.

Newest first. Kept for 30 days (max_days). Values are text, as broadcast. An ETA edit appears as separate rows for eta_month, eta_day, eta_hour and eta_minute.

Access: Pro. Needs Pro access. An API key always qualifies, because keys only work while the account has Pro. A signed-in free account gets 403 upgrade_required.

Path parameters

NameTypeDefault / limitsDescription
idrequiredIMO or MMSI1–9 charsA 7-digit IMO number or an MMSI (up to 9 digits). Seven digits are looked up as an IMO first, then as an MMSI.

Query parameters

NameTypeDefault / limitsDescription
fieldstring≤ 64 charsOnly changes to this field, e.g. destination, name, max_draught, ship_type.
sinceISO 8601 timestamp—Only changes observed at or after this instant.
untilISO 8601 timestamp—Only changes observed at or before this instant.
limitintegerdefault 500 · 1–10000Maximum rows.
Request
curl -s "https://www.vesseltrack.net/api/vessels/9126003/history?limit=1" \
  -H "X-API-Key: $VESSELTRACK_API_KEY"
Response · 200 · application/json
{
  "mmsi": 308738947,
  "imo": 9126003,
  "lookup": {
    "requestedIdentifier": "9126003",
    "canonicalIdentifier": "9126003",
    "canonicalType": "imo"
  },
  "count": 1,
  "limit": 1,
  "max_days": 30,
  "history": [
    {
      "id": 617,
      "mmsi": 308738947,
      "field_name": "eta_hour",
      "old_value": "1",
      "new_value": "20",
      "source": "ais",
      "observed_at": "2026-11-16T06:26:49.941Z",
      "created_at": "2026-11-16T20:54:18.472Z"
    }
  ]
}

Field changes, newest first.

Errors

StatusWhenBody
403The caller does not have Pro access.{"error":"Vessel history requires VesselTrack Pro.","code":"upgrade_required","upgrade_url":"/pricing"}
400since or until is not a timestamp.{"error":"since must be an ISO 8601 timestamp"}
404No vessel with that IMO number or MMSI has been received.{"error":"Vessel not found"}
GET/api/vessels/{id}/eventsPro

Event timeline

Port arrivals, port departures and expected arrivals detected for a vessel.

Newest first. Kept for 90 days (max_days). event_type / event_subtype is port_call / arrival, port_call / departure, or voyage / expected_arrival (the reported destination newly resolved to a known port).

An arrival is recorded when a vessel comes to a stop near a known port; a departure only when the vessel was seen leaving. confidence is a 0–1 estimate, lower when the port was inferred from position alone.

Access: Pro. Needs Pro access. An API key always qualifies, because keys only work while the account has Pro. A signed-in free account gets 403 upgrade_required.

Path parameters

NameTypeDefault / limitsDescription
idrequiredIMO or MMSI1–9 charsA 7-digit IMO number or an MMSI (up to 9 digits). Seven digits are looked up as an IMO first, then as an MMSI.

Query parameters

NameTypeDefault / limitsDescription
event_typestring≤ 48 charsport_call or voyage.
sinceISO 8601 timestamp—Only events observed at or after this instant.
untilISO 8601 timestamp—Only events observed at or before this instant.
limitintegerdefault 500 · 1–10000Page size.
offsetintegerdefault 0 · 0–1000000Rows to skip.
Request
curl -s "https://www.vesseltrack.net/api/vessels/9126003/events?limit=2" \
  -H "X-API-Key: $VESSELTRACK_API_KEY"
Response · 200 · application/json
{
  "mmsi": 308738947,
  "imo": 9126003,
  "lookup": {
    "requestedIdentifier": "9126003",
    "canonicalIdentifier": "9126003",
    "canonicalType": "imo"
  },
  "count": 2,
  "limit": 2,
  "offset": 0,
  "max_days": 90,
  "events": [
    {
      "id": 890,
      "mmsi": 308738947,
      "imo": 9126003,
      "event_type": "voyage",
      "event_subtype": "expected_arrival",
      "port_locode": "USNYC",
      "lat": 19.22224,
      "lon": -107.55014,
      "title": "Expected arrival New York",
      "description": "Reported destination matched to USNYC",
      "metadata": {
        "eta": {
          "day": 26,
          "hour": 20,
          "month": 11,
          "minute": 47
        },
        "reported_destination": "USLAX>USNYC"
      },
      "source": "ais",
      "confidence": 0.45,
      "observed_at": "2026-11-16T16:51:58.428Z",
      "created_at": "2026-11-16T20:54:18.472Z"
    },
    {
      "id": 892,
      "mmsi": 308738947,
      "imo": 9126003,
      "event_type": "port_call",
      "event_subtype": "departure",
      "port_locode": "CNBHY",
      "lat": 21.48,
      "lon": 109.08,
      "title": "Departed Beihai",
      "description": null,
      "metadata": {},
      "source": "ais",
      "confidence": 0.85,
      "observed_at": "2026-11-11T18:09:30.060Z",
      "created_at": "2026-11-16T20:54:18.472Z"
    }
  ]
}

Events, newest first.

Errors

StatusWhenBody
403The caller does not have Pro access.{"error":"Vessel event timeline requires VesselTrack Pro.","code":"upgrade_required","upgrade_url":"/pricing"}
404No vessel with that IMO number or MMSI has been received.{"error":"Vessel not found"}
GET/api/vessels/{id}/port-callsPro

Port calls

A vessel’s port-call records: arrivals, departures and expected arrivals.

Newest first. Port calls are kept for 90 days; days defaults to and cannot exceed that.

event_type is arrival, departure or expected_arrival. An arrival row gets departed_at filled in when the departure is seen; a departure row carries both times. expected_arrival rows have neither.

Access: Pro. Needs Pro access. An API key always qualifies, because keys only work while the account has Pro. A signed-in free account gets 403 upgrade_required.

Path parameters

NameTypeDefault / limitsDescription
idrequiredIMO or MMSI1–9 charsA 7-digit IMO number or an MMSI (up to 9 digits). Seven digits are looked up as an IMO first, then as an MMSI.

Query parameters

NameTypeDefault / limitsDescription
daysintegerdefault 90 · 1–90Look-back window in days.
event_typestring≤ 32 charsarrival, departure or expected_arrival.
limitintegerdefault 500 · 1–10000Page size.
offsetintegerdefault 0 · 0–1000000Rows to skip.
Request
curl -s "https://www.vesseltrack.net/api/vessels/9126003/port-calls?event_type=arrival&limit=1" \
  -H "X-API-Key: $VESSELTRACK_API_KEY"
Response · 200 · application/json
{
  "mmsi": 308738947,
  "imo": 9126003,
  "lookup": {
    "requestedIdentifier": "9126003",
    "canonicalIdentifier": "9126003",
    "canonicalType": "imo"
  },
  "count": 1,
  "limit": 1,
  "offset": 0,
  "days": 90,
  "max_days": 90,
  "port_calls": [
    {
      "id": 891,
      "mmsi": 308738947,
      "imo": 9126003,
      "port_locode": "CNBHY",
      "port_name": "Beihai",
      "country_code": "CN",
      "event_type": "arrival",
      "arrived_at": "2026-11-10T15:13:21.829Z",
      "departed_at": "2026-11-11T18:09:30.060Z",
      "observed_at": "2026-11-10T15:13:21.829Z",
      "lat": 21.48,
      "lon": 109.08,
      "source": "ais",
      "confidence": 0.85,
      "metadata": {},
      "created_at": "2026-11-16T20:54:18.472Z"
    }
  ]
}

Port calls, newest first.

Errors

StatusWhenBody
403The caller does not have Pro access.{"error":"Port-call history requires VesselTrack Pro.","code":"upgrade_required","upgrade_url":"/pricing"}
404No vessel with that IMO number or MMSI has been received.{"error":"Vessel not found"}
GET/api/vessels/{mmsi}/enrichAPI key

Photo and reference links

A photo of the vessel from Wikimedia Commons, when one can be found, and a link to its Equasis record.

Takes an MMSI only (not an IMO number). The photo lookup is cached for seven days and rate limited across all callers, so a response can come back without a photo and with pending: true (another request is looking it up) or deferred: true (the lookup budget for this minute is spent). Ask again later.

imageMatchedBy says whether the photo was found by IMO number ("imo") or only by vessel name ("name", which can be a different ship of the same name). Photos are served by Wikimedia under their own licences; wikiUrl is the file page carrying the attribution.

Access: API key. An API key. (The website reaches the same endpoint with the cookie it sets for its own pages; that cookie is rate limited per visitor and per IP address, and is not an API credential.)

Path parameters

NameTypeDefault / limitsDescription
mmsirequiredMMSI1–9 charsThe vessel’s MMSI.
Request
curl -s "https://www.vesseltrack.net/api/vessels/308738947/enrich" \
  -H "X-API-Key: $VESSELTRACK_API_KEY"
Response · 200 · application/json
{
  "mmsi": 308738947,
  "imageUrl": null,
  "imageSource": null,
  "imageMatchedBy": null,
  "wikiUrl": null,
  "extraData": {
    "lookup": "ok"
  },
  "externalLinks": [
    {
      "name": "Equasis",
      "url": "https://www.equasis.org/EquasisWeb/restricted/ShipInfo?fs=Search&P_IMO=9126003",
      "icon": "📋"
    }
  ],
  "cached": true
}

Photo (possibly null) and outbound links.

externalLinks
The Equasis ship-safety record, present only when the vessel has an IMO number.
cached
true when the answer came from the stored lookup.

Errors

StatusWhenBody
400The path is not 1–9 digits.{"error":"Invalid MMSI"}
404No vessel with that IMO number or MMSI has been received.{"error":"Vessel not found"}

Fleet replay

Every vessel in view as it was at a past moment: snapshots of the whole fleet every 15 minutes, thinned with age, with the gaps shown.

GET/api/replay/timelineAPI key

Replay timeline

What fleet history exists: its extent, cadence by age, the runs of snapshots and the gaps between them.

A snapshot of every vessel heard in the preceding hour is taken every 15 minutes. Age thins them: every snapshot for 30 days, then the earliest of each hour up to 730 days, then the earliest of each 6-hour block, kept indefinitely.

segments are runs of snapshots without a gap at the archive’s cadence for their age; gaps are the periods between them with nothing recorded (the collector was offline). A gap with to = null runs up to now: nothing has been recorded since latest. Gaps are shown, never filled in.

entitlements gives each plan’s window, so a client knows where its timeline starts. With from and to, range lists every snapshot time in between (epoch seconds) with its vessel count — at most 3,000.

The same for every caller; cached for a minute.

Access: API key. An API key. (The website reaches the same endpoint with the cookie it sets for its own pages; that cookie is rate limited per visitor and per IP address, and is not an API credential.)

Query parameters

NameTypeDefault / limitsDescription
fromISO 8601 time with a zone, or epoch seconds—Start of a range to list snapshot times for (with to).
toISO 8601 time with a zone, or epoch seconds—End of that range (with from).
Request
curl -s "https://www.vesseltrack.net/api/replay/timeline?from=2026-11-17T09:00:00Z&to=2026-11-17T12:00:00Z" \
  -H "X-API-Key: $VESSELTRACK_API_KEY"
Response · 200 · application/json
{
  "format": "replay-timeline-v1",
  "now": "2026-11-17T12:07:31.000Z",
  "snapshotMinutes": 15,
  "tiers": [
    {
      "tier": "full",
      "cadenceMinutes": 15,
      "fromDaysAgo": 0,
      "toDaysAgo": 30
    },
    {
      "tier": "hourly",
      "cadenceMinutes": 60,
      "fromDaysAgo": 30,
      "toDaysAgo": 730
    },
    {
      "tier": "six_hourly",
      "cadenceMinutes": 360,
      "fromDaysAgo": 730,
      "toDaysAgo": null
    }
  ],
  "earliest": "2026-11-13T12:15:00.000Z",
  "latest": "2026-11-17T12:00:00.000Z",
  "buckets": 368,
  "current": true,
  "segments": [
    {
      "from": "2026-11-13T12:15:00.000Z",
      "to": "2026-11-15T18:45:00.000Z",
      "tier": "full",
      "cadenceMinutes": 15,
      "buckets": 218,
      "vessels": {
        "min": 39102,
        "max": 42011
      }
    },
    {
      "from": "2026-11-15T23:00:00.000Z",
      "to": "2026-11-17T12:00:00.000Z",
      "tier": "full",
      "cadenceMinutes": 15,
      "buckets": 150,
      "vessels": {
        "min": 40118,
        "max": 41873
      }
    }
  ],
  "segmentsTruncated": false,
  "gaps": [
    {
      "from": "2026-11-15T19:00:00.000Z",
      "to": "2026-11-15T23:00:00.000Z",
      "minutes": 240
    }
  ],
  "entitlements": {
    "free": {
      "hours": 3,
      "earliest": "2026-11-17T09:07:31.000Z"
    },
    "pro": {
      "hours": null,
      "earliest": "2026-11-13T12:15:00.000Z"
    }
  },
  "range": null
}

The archive.

current
true when the newest snapshot is at most 30 minutes old.
segments[].cadenceMinutes
Spacing of the snapshots in that run.
gaps[]
from = the first missing moment, to = the next snapshot (null: none yet).

Errors

StatusWhenBody
400A time, box, limit or filter is malformed, or a filter a snapshot cannot answer (destination, name, speed) was given.{"error":"destination is not available in replay (snapshots do not store it)","code":"invalid_request"}
503The snapshot store does not exist yet on this deployment.{"error":"Fleet replay is not available yet.","code":"replay_unavailable"}
GET/api/replay/frameAPI key

Replay frame

Every vessel in view as it was at a past moment.

Shows the newest snapshot at or before t, as long as it still covers t (one cadence step); otherwise 404 no_frame names the snapshots on either side — an older frame is never passed off as the requested moment.

Vessel names are not stored in snapshots; resolve the ones you show with GET /api/vessels/map?format=compact&mmsi=… (add stale_minutes for vessels not heard lately) or GET /api/vessels/{id}. More than limit vessels in view are thinned spatially and deterministically (sampled: true).

Past snapshots never change, so frames are cached: those inside the last 3 hours publicly (for at most 60 minutes, and never past the moment they leave that window), older ones only in your own browser (24 hours). A response that the next snapshot would change is cached for 60 seconds. Ask for exact snapshot times from the timeline and snap bbox to a grid so repeated requests share cache entries.

Access: API key. Without Pro, the last 3 hours; with Pro (an API key always has it), the whole archive.

Query parameters

NameTypeDefault / limitsDescription
trequiredISO 8601 time with a zone, or epoch seconds—The moment to show.
bboxwest,south,east,north—Only vessels inside this box (decimal degrees, edges inclusive; west > east crosses the antimeridian). Omit for the whole world.
ship_categorycomma-separated slugs—As on /api/vessels/map: cargo, tanker, passenger, fishing, … ; other also matches vessels with no ship type.
ship_typecomma-separated integers—Exact AIS ship-type codes 0–99.
flagcomma-separated—Flag state: three-digit MIDs, ISO alpha-2 codes or country names.
nav_statuscomma-separated integers—AIS navigational status codes 0–15 (15 matches "not defined").
show_unknownstring1Include vessels that have not reported a ship type (left out by default, as on the live map).
limitinteger1–50000Most vessels in the frame (default and maximum 50,000).
Request
curl -s "https://www.vesseltrack.net/api/replay/frame?t=2026-11-17T12:00:00Z&bbox=3,51,5,52.5" \
  -H "X-API-Key: $VESSELTRACK_API_KEY"
Response · 200 · application/json
{
  "format": "compact-v1",
  "count": 2,
  "limit": 50000,
  "total": 2,
  "sampled": false,
  "truncated": false,
  "freshness": null,
  "asOf": 1794916800,
  "scale": 10000,
  "names": false,
  "replay": {
    "bucket": "2026-11-17T12:00:00.000Z",
    "cadenceMinutes": 15,
    "windowMinutes": 60,
    "fleetVessels": 41873,
    "source": "live",
    "previous": "2026-11-17T11:45:00.000Z",
    "next": "2026-11-17T12:15:00.000Z"
  },
  "mmsi": [244012345, 392005545],
  "lat": [519531, 520112],
  "lon": [41187, 39876],
  "dir": [-1, 271],
  "type": [70, 80],
  "sog": [0, 124],
  "age": [2, 0],
  "nav": [5, 0]
}

One frame.

format
"compact-v1": the same columnar format as GET /api/vessels/map?format=compact, decoded by the same code.
asOf
The snapshot time (epoch seconds) the frame shows.
mmsi
Ascending; the first value absolute, then differences.
lat, lon
Integers: divide by scale for degrees.
dir
Marker direction 0–359: the true heading, else the course; -1 when moored, at anchor, under 0.5 kn or unknown.
type
AIS ship type 0–99 (0 = unknown).
sog
Speed over ground in tenths of a knot; -1 = not available.
age
Whole minutes between the vessel’s newest position and asOf. Fade older ones as the live map does.
nav
Navigational status 0–14 per vessel; -1 = not available.
total, sampled, truncated
Vessels in the view before thinning; whether it was thinned to limit (deterministically, by MMSI: the same vessels stay in consecutive frames).
replay.cadenceMinutes
Archive resolution around this frame: 15, 60 or 360 minutes (older history is thinned).
replay.windowMinutes
A vessel is in the frame when it was heard within this many minutes before the snapshot.
replay.fleetVessels
Vessels in the whole snapshot (world), before the box, filters and thinning.

Errors

StatusWhenBody
400A time, box, limit or filter is malformed, or a filter a snapshot cannot answer (destination, name, speed) was given.{"error":"destination is not available in replay (snapshots do not store it)","code":"invalid_request"}
403The time is older than the caller’s window (the last 3 hours without Pro). The body also carries replay_hours and earliest_allowed.{"error":"Fleet replay requires VesselTrack Pro.","code":"upgrade_required","upgrade_url":"/pricing"}
404No snapshot covers the time: before the archive, after its newest snapshot, or in a gap (the collector was not recording). previous / next name the neighbouring snapshots.{"error":"No snapshot covers the requested time (the collector was not recording).","code":"no_frame","reason":"gap","previous":"2026-11-15T18:45:00.000Z","next":"2026-11-15T23:00:00.000Z"}
429The caller has made the server read a lot of history recently (counted per account, or per visitor and address). Retry-After says when to retry.{"error":"Replay allowance used: this caller has read a lot of fleet history recently. Retry later.","code":"replay_limit","retry_after_seconds":1200}
503The snapshot store does not exist yet on this deployment.{"error":"Fleet replay is not available yet.","code":"replay_unavailable"}
GET/api/replay/framesAPI key

Replay frames (playback)

Consecutive frames for smooth playback, oldest first.

Every snapshot in [from, to] — or with every, the earliest one per that many minutes — each in the frame format above, thinned with one shared rule so the same vessels appear in every frame and positions can be interpolated between them.

Bounded per response: at most 24 frames, 100,000 vessels in all (so at most 10 frames at the default limit of 10,000), 2,400 stored map tiles read, and a span of 31 days. When it stops early, complete is false and next is the first snapshot not returned: ask again from there.

Without Pro, a range starting more than 15 minutes before the 3-hour window is refused; one starting just before it is clamped (from in the response says where it starts).

Past snapshots never change, so frames are cached: those inside the last 3 hours publicly (for at most 60 minutes, and never past the moment they leave that window), older ones only in your own browser (24 hours). A response that the next snapshot would change is cached for 60 seconds. Ask for exact snapshot times from the timeline and snap bbox to a grid so repeated requests share cache entries.

Access: API key. Without Pro, the last 3 hours; with Pro (an API key always has it), the whole archive.

Query parameters

NameTypeDefault / limitsDescription
fromrequiredISO 8601 time with a zone, or epoch seconds—First moment (inclusive).
torequiredISO 8601 time with a zone, or epoch seconds—Last moment (inclusive).
everyminutes15 | 30 | 60 | 120 | 180 | 360 | 720 | 1440One frame per this many minutes (the earliest snapshot of each period) for faster playback.
bboxwest,south,east,north—Only vessels inside this box (decimal degrees, edges inclusive; west > east crosses the antimeridian). Omit for the whole world.
ship_categorycomma-separated slugs—As on /api/vessels/map: cargo, tanker, passenger, fishing, … ; other also matches vessels with no ship type.
ship_typecomma-separated integers—Exact AIS ship-type codes 0–99.
flagcomma-separated—Flag state: three-digit MIDs, ISO alpha-2 codes or country names.
nav_statuscomma-separated integers—AIS navigational status codes 0–15 (15 matches "not defined").
show_unknownstring1Include vessels that have not reported a ship type (left out by default, as on the live map).
limitinteger1–50000Most vessels per frame (default 10,000). A lower limit fits more frames into one response.
Request
curl -s "https://www.vesseltrack.net/api/replay/frames?from=2026-11-17T11:00:00Z&to=2026-11-17T12:00:00Z&bbox=3,51,5,52.5&limit=5000" \
  -H "X-API-Key: $VESSELTRACK_API_KEY"
Response · 200 · application/json
{
  "format": "replay-frames-v1",
  "from": "2026-11-17T11:00:00.000Z",
  "to": "2026-11-17T12:00:00.000Z",
  "every": 15,
  "limit": 10000,
  "count": 1,
  "complete": false,
  "next": "2026-11-17T11:15:00.000Z",
  "gaps": [],
  "frames": [
    {
      "format": "compact-v1",
      "count": 2,
      "limit": 10000,
      "total": 2,
      "sampled": false,
      "truncated": false,
      "freshness": null,
      "asOf": 1794916800,
      "scale": 10000,
      "names": false,
      "replay": {
        "bucket": "2026-11-17T12:00:00.000Z",
        "cadenceMinutes": 15,
        "windowMinutes": 60,
        "fleetVessels": 41873,
        "source": "live"
      },
      "mmsi": [244012345, 392005545],
      "lat": [519531, 520112],
      "lon": [41187, 39876],
      "dir": [-1, 271],
      "type": [70, 80],
      "sog": [0, 124],
      "age": [2, 0],
      "nav": [5, 0]
    }
  ]
}

Frames, oldest first.

complete
false when a cap was reached; continue from next.
gaps[]
Periods between the returned frames with nothing recorded.
frames[]
Frames in the format of GET /api/replay/frame (without previous/next).

Errors

StatusWhenBody
400A time, box, limit or filter is malformed, or a filter a snapshot cannot answer (destination, name, speed) was given.{"error":"destination is not available in replay (snapshots do not store it)","code":"invalid_request"}
403The time is older than the caller’s window (the last 3 hours without Pro). The body also carries replay_hours and earliest_allowed.{"error":"Fleet replay requires VesselTrack Pro.","code":"upgrade_required","upgrade_url":"/pricing"}
429The caller has made the server read a lot of history recently (counted per account, or per visitor and address). Retry-After says when to retry.{"error":"Replay allowance used: this caller has read a lot of fleet history recently. Retry later.","code":"replay_limit","retry_after_seconds":1200}
503The snapshot store does not exist yet on this deployment.{"error":"Fleet replay is not available yet.","code":"replay_unavailable"}

Ports

The port directory (UN/LOCODE), the vessels bound for or stopped at a port, and its recent port calls.

GET/api/portsPublic

Port directory

Search or page through known ports.

Within a page, ports with the most inbound vessels come first. inbound_vessels counts vessels whose reported destination currently resolves to the port.

Access: Public. No credentials. Served to anyone and cached at the CDN. Not counted against your key’s hourly allowance, but limited per IP address: far more requests than a person using the map would send get 429 with Retry-After.

Query parameters

NameTypeDefault / limitsDescription
qstring2–40 charsMatches UN/LOCODE, name, city and approved aliases (contains).
country_codestring—ISO 3166-1 alpha-2 country code.
countrystring≤ 60 charsCountry name, exact (case-insensitive).
locodestring—Exact UN/LOCODE.
limitintegerdefault 100 · 1–500Page size.
offsetintegerdefault 0 · 0–100000Rows to skip.
Request
curl -s "https://www.vesseltrack.net/api/ports?q=singapore&limit=2"
Response · 200 · application/json
{
  "count": 1,
  "total": 1,
  "limit": 2,
  "offset": 0,
  "ports": [
    {
      "locode": "SGSIN",
      "name": "Singapore",
      "city": "Singapore",
      "country": "Singapore",
      "country_code": "SG",
      "latitude": 1.26,
      "longitude": 103.83,
      "function_codes": "1-------",
      "source": "local-seed",
      "source_version": "demo",
      "inbound_vessels": 42
    }
  ]
}

One page of ports.

total
Ports matching the filters.
ports[].function_codes
UN/LOCODE function string; a leading 1 means a sea port.

Errors

StatusWhenBody
400country_code, locode or q is malformed.{"error":"Invalid country_code"}
GET/api/ports/{locode}API key

Port detail

One port, its known aliases, and counts of inbound vessels and recent port calls.

aliases are the spellings of this port seen in AIS destination fields (up to 100), with a review_status of approved, pending or rejected. recent_port_calls covers the last 7 days.

Access: API key. An API key. (The website reaches the same endpoint with the cookie it sets for its own pages; that cookie is rate limited per visitor and per IP address, and is not an API credential.)

Path parameters

NameTypeDefault / limitsDescription
locoderequiredUN/LOCODE—Five-character UN/LOCODE, e.g. SGSIN. Case-insensitive.
Request
curl -s "https://www.vesseltrack.net/api/ports/SGSIN" \
  -H "X-API-Key: $VESSELTRACK_API_KEY"
Response · 200 · application/json
{
  "port": {
    "locode": "SGSIN",
    "name": "Singapore",
    "city": "Singapore",
    "country": "Singapore",
    "country_code": "SG",
    "latitude": 1.26,
    "longitude": 103.83,
    "function_codes": "1-------",
    "source": "local-seed",
    "source_version": "demo",
    "is_active": true,
    "created_at": "2026-11-16T19:59:16.367Z",
    "updated_at": "2026-11-16T19:59:16.367Z",
    "alias_count": 2,
    "inbound_vessels": 42,
    "recent_port_calls": 56
  },
  "aliases": [
    {
      "raw_alias": "SINGAPORE",
      "normalized_alias": "SINGAPORE",
      "source": "local-seed",
      "confidence": "1.000",
      "review_status": "approved"
    }
  ]
}

The port and its aliases.

Errors

StatusWhenBody
400The path is not a five-character UN/LOCODE.{"error":"Invalid UN/LOCODE"}
404No port has that UN/LOCODE.{"error":"Port not found"}
GET/api/ports/{locode}/vesselsAPI key

Vessels at or bound for a port

Vessels inbound to a port, expected there, or stopped in it right now.

status=inbound (default): every vessel whose reported destination resolves to this port, most recently heard first. status=recent: the same, heard in the last 24 hours.

status=expected: vessels bound for the port that are under way and were heard in the last 7 days, soonest ETA first; each has eta_timestamp. status=in_port: vessels stationary within 10 km of the port’s coordinates and heard in the last 24 hours, nearest first, whatever destination they declare; each has distance_km.

The response repeats the thresholds it applied in criteria. For in_port, available is false when the port has no coordinates on record.

freshness says whether the AIS feed is live, as on the map endpoint. While it is stale, “the last 24 hours” and “the last 7 days” are measured from the newest position in the feed rather than from now, so the lists show the last known picture instead of emptying. Responses are private and not cached.

Without an API key (the website’s cookie, signed in or not) every row served counts against a preview allowance shared by this endpoint and the other bulk listing: 1,000 rows an hour and 3,000 a day per browser, 2,000 an hour and 6,000 a day per IP address. limit is reduced to what is left, and once nothing is left the request is refused before any query runs. Unlike the vessel list, this response has no preview block.

Access: API key. Full paging (limit up to 5,000, offset up to 100,000) needs an API key. Without one, limit and offset are capped at 100 each and rows come out of a preview allowance (below).

Path parameters

NameTypeDefault / limitsDescription
locoderequiredUN/LOCODE—Five-character UN/LOCODE, e.g. SGSIN. Case-insensitive.

Query parameters

NameTypeDefault / limitsDescription
statusstringdefault inbound · inbound | recent | in_port | expectedWhich list to return.
limitintegerdefault 500 · 1–5000Page size. Without an API key: default 100, maximum 100.
offsetintegerdefault 0 · 0–100000Rows to skip. Without an API key: maximum 100.
Request
curl -s "https://www.vesseltrack.net/api/ports/SGSIN/vessels?status=in_port&limit=1" \
  -H "X-API-Key: $VESSELTRACK_API_KEY"
Response · 200 · application/json
{
  "port": "SGSIN",
  "status": "in_port",
  "available": true,
  "count": 1,
  "total": 17,
  "limit": 1,
  "offset": 0,
  "truncated": false,
  "freshness": {
    "mode": "live",
    "latestPositionUpdate": "2026-11-16T23:40:41.428Z",
    "feedAgeMinutes": 0
  },
  "criteria": {
    "radius_km": 10,
    "stationary": "speed under 0.5 kn, or reported moored / at anchor with speed under 2 kn",
    "position_max_age_hours": 24,
    "order": "distance ascending"
  },
  "vessels": [
    {
      "identity": {
        "mmsi": 563406084,
        "name": "SUBSEA INSTALLER",
        "call_sign": "9VVMSW",
        "imo": null,
        "flag_country": "Singapore",
        "flag_emoji": "🇸🇬",
        "destination": "SINGAPORE",
        "reported_destination": "SINGAPORE",
        "matched_destination": "Singapore, SINGAPORE"
      },
      "…": "the remaining vessel fields, as in vessel detail",
      "distance_km": 0.2
    }
  ]
}

Vessel objects (as in vessel detail) with distance_km or eta_timestamp where applicable.

Errors

StatusWhenBody
400The path is not a five-character UN/LOCODE.{"error":"Invalid UN/LOCODE"}
400status is not a supported value.{"error":"status must be one of: inbound, recent, in_port, expected"}
404No port has that UN/LOCODE (whatever the status).{"error":"Port not found"}
429No API key, and the preview row allowance is used up. Retry-After and retry_after_seconds say when rows are available again.{"error":"Preview allowance used: without an API key these listings return a limited number of rows per hour. Bulk access is part of the Pro API.","code":"preview_limit","retry_after_seconds":1260,"upgrade_url":"/pricing"}
GET/api/ports/{locode}/port-callsAPI key

Port calls at a port

Arrivals, departures and expected arrivals recorded for a port, with each vessel’s name.

Newest first. days defaults to 7. The response reports the days applied and max_days for your plan.

truncated is true when more rows match than were returned; request the next page with offset increased by limit.

Access: API key. With an API key: up to 90 days and 10,000 rows per request. Without Pro: the last 7 days, 1,000 rows per request.

Path parameters

NameTypeDefault / limitsDescription
locoderequiredUN/LOCODE—Five-character UN/LOCODE, e.g. SGSIN. Case-insensitive.

Query parameters

NameTypeDefault / limitsDescription
daysintegerdefault 7 · 1–90Look-back window in days.
event_typestring≤ 64 charsOne type or a comma-separated list: arrival, departure, expected_arrival (for example arrival,departure). An unknown type is a 400.
limitintegerdefault 500 · 1–10000Page size.
offsetintegerdefault 0 · 0–1000000Rows to skip.
Request
curl -s "https://www.vesseltrack.net/api/ports/CNBHY/port-calls?event_type=arrival&days=30&limit=1" \
  -H "X-API-Key: $VESSELTRACK_API_KEY"
Response · 200 · application/json
{
  "port": "CNBHY",
  "count": 1,
  "limit": 1,
  "offset": 0,
  "truncated": true,
  "access": "plan",
  "days": 30,
  "max_days": 90,
  "port_calls": [
    {
      "id": 1372,
      "mmsi": 566358713,
      "imo": 9450753,
      "port_locode": "CNBHY",
      "port_name": "Beihai",
      "country_code": "CN",
      "event_type": "arrival",
      "arrived_at": "2026-11-11T07:06:41.317Z",
      "departed_at": null,
      "observed_at": "2026-11-11T07:06:41.317Z",
      "lat": 21.48,
      "lon": 109.08,
      "source": "ais",
      "confidence": 0.85,
      "metadata": {},
      "created_at": "2026-11-16T20:59:18.472Z",
      "vessel_name": "PEARL PROSPERITY",
      "call_sign": "9VF7",
      "ship_type": 70
    }
  ]
}

Port calls, newest first.

Errors

StatusWhenBody
400The path is not a five-character UN/LOCODE.{"error":"Invalid UN/LOCODE"}

Stats and feed status

Fleet-wide counts and whether the data feed is live.

GET/api/statsPublic

Stats and feed status

How many vessels are known and recently heard, and whether the feed is live.

feed.mode is "stale" when the newest position anywhere is more than 30 minutes old, which means the data collector is offline or stalled. Check it before treating positions as current. Cached for up to 60 seconds.

Access: Public. No credentials. Served to anyone and cached at the CDN. Not counted against your key’s hourly allowance, but limited per IP address: far more requests than a person using the map would send get 429 with Retry-After.

Request
curl -s "https://www.vesseltrack.net/api/stats"
Response · 200 · application/json
{
  "total_vessels": 2000,
  "updated_last_1h": 1729,
  "updated_last_24h": 1916,
  "latest_position_update": "2026-11-16T20:54:13.428Z",
  "top_ship_types": [
    {
      "ship_type": 70,
      "count": 579
    },
    {
      "ship_type": 30,
      "count": 220
    }
  ],
  "feed": {
    "mode": "live",
    "latestPositionUpdate": "2026-11-16T20:54:13.428Z",
    "feedAgeMinutes": 2
  }
}

Counts, the ten most common ship-type codes, and feed freshness.

total_vessels
Vessels with a position on record.
latest_position_update
The newest position timestamp in the whole feed.
feed.feedAgeMinutes
Whole minutes since that timestamp.

Fleet (watchlist)

The vessels an account follows, with groups, notes and per-vessel alert rules.

GET/api/watchlistAPI key or signed-in session

List the fleet

Every vessel on the watchlist with its current position, voyage and unread-alert count.

Newest entry first, not paginated (the list is at most 500 vessels on Pro, 10 on Free). Position fields are null for a vessel that has not been received yet.

Access: API key or signed-in session. Acts on one account’s data. Send an API key, or call it from a signed-in browser session.

Request
curl -s "https://www.vesseltrack.net/api/watchlist" \
  -H "X-API-Key: $VESSELTRACK_API_KEY"
Response · 200 · application/json
{
  "watchlist": [
    {
      "id": 1,
      "mmsi": 308738947,
      "label": "CAPE DREAM",
      "group_name": "Asia–Europe",
      "notes": "Demo watchlist entry created by the local seed.",
      "notify_on": ["destination", "sog", "speed_threshold"],
      "speed_threshold_knots": 12,
      "heading_change_degrees": null,
      "ais_gap_minutes": null,
      "created_at": "2026-11-13T19:59:15.428Z",
      "vessel_name": "CAPE DREAM",
      "imo": 9126003,
      "call_sign": "C6EE",
      "ship_type": 70,
      "lat": 19.222241,
      "lon": -107.550136,
      "sog": 11.8,
      "cog": 129,
      "true_heading": 132,
      "nav_status": 0,
      "destination": "USLAX>USNYC",
      "destination_port_code": "USNYC",
      "matched_destination": "New York, USA",
      "eta": "2026-11-26T20:47:00.000Z",
      "draught": 9,
      "last_position_update": "2026-11-16T20:51:58.428Z",
      "unread_alerts": 3
    }
  ],
  "count": 8,
  "limit": 500,
  "plan": "pro"
}

The watchlist, its size and the plan limit.

limit
How many vessels this plan may watch.
plan
"free" or "pro".
watchlist[].eta
Inferred ISO timestamp, or null.
watchlist[].unread_alerts
Unacknowledged alerts raised by this entry’s rules.

Errors

StatusWhenBody
401The request has only the website’s cookie: nobody is signed in and there is no API key.{"error":"Unauthorized"}
POST/api/watchlistAPI key or signed-in session

Add a vessel

Put one vessel on the watchlist, optionally with alert rules.

Give identifier (an IMO number or MMSI, resolved to a vessel that has been received) or mmsi (accepted even if the vessel has not been received yet). identifier wins when both are sent.

To add many vessels at once, use the import endpoint.

Access: API key or signed-in session. Alert rules (notifyOn) need Pro.

JSON body

NameTypeDefault / limitsDescription
identifierstring or number—IMO number or MMSI. Labels and separators are tolerated: "IMO 9321483", "563-000-100".
mmsiinteger1–999999999MMSI, when not using identifier.
labelstring≤ 100 chars · null clearsYour own name for the vessel.
groupstring≤ 60 chars · null clearsGroup name. Returned as group_name.
notesstring≤ 2000 chars · null clearsFree-text notes.
notifyOnarray of strings—Alert rules to switch on for this vessel: arrival, departure, destination, nav_status, sog, speed_threshold, heading_change, ais_gap, name, ship_type. An unknown key is a 400. Needs Pro.
speedThresholdnumber0.5–60 · null clearsThreshold for the speed_threshold rule, in kn. Values outside 0.5–60 are clamped. The rule does nothing until this is set. null clears it.
headingChangeDegnumber5–180 · null clearsThreshold for the heading_change rule, in °. Values outside 5–180 are clamped. Default 45 when not set. null clears it.
aisGapMinutesnumber15–1440 · null clearsThreshold for the ais_gap rule, in min. Values outside 15–1440 are clamped. Default 30 when not set. null clears it.
Request
curl -s -X POST "https://www.vesseltrack.net/api/watchlist" \
  -H "X-API-Key: $VESSELTRACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"9169902","label":"Kestrel","group":"Charters","notifyOn":["arrival","departure","speed_threshold"],"speedThreshold":14}'
Response · 201 · application/json
{
  "item": {
    "id": 30,
    "mmsi": 311871866,
    "label": "Kestrel",
    "group_name": "Charters",
    "notes": null,
    "notify_on": ["arrival", "departure", "speed_threshold"],
    "speed_threshold_knots": 14,
    "heading_change_degrees": null,
    "ais_gap_minutes": null,
    "created_at": "2026-11-16T20:59:55.467Z"
  }
}

The stored entry.

Errors

StatusWhenBody
400The body is not valid, or names an alert rule that does not exist.{"error":"Unknown alert rule \"teleport\". Valid rules: arrival, departure, destination, nav_status, sog, speed_threshold, heading_change, ais_gap, name, ship_type"}
401The request has only the website’s cookie: nobody is signed in and there is no API key.{"error":"Unauthorized"}
403notifyOn was sent without Pro access.{"error":"Alerts requires VesselTrack Pro.","code":"upgrade_required","upgrade_url":"/pricing"}
404identifier does not match a received vessel.{"error":"Vessel not found"}
409The vessel is already on the watchlist.{"error":"Vessel already on your watchlist","code":"duplicate"}
409The watchlist is at the plan limit.{"error":"You have reached your plan's limit of 500 watched vessels.","code":"limit_reached","limit":500,"upgrade_url":"/pricing"}
PUT/api/watchlistAPI key or signed-in session

Edit entries

Change the label, group, notes, alert rules or thresholds of one watchlist entry, or of many at once.

Fields you leave out are unchanged. null clears a text field or a threshold; notifyOn: [] switches every rule off.

Send id to edit one entry, or ids to apply the same fields to several in one request (for example {"ids":[5,6],"group":"Arrivals"}). ids takes entry ids, at most as many as your plan’s watchlist limit (or your current fleet size, if that is larger); a repeated id counts once. The bulk form answers { message, updated, ids, missing }: ids are the entries that were changed, missing the ones that do not exist or are not yours. It is not a 404 when some are missing.

Access: API key or signed-in session. Switching alert rules on needs Pro; clearing them does not.

JSON body

NameTypeDefault / limitsDescription
idintegermin 1The entry id (not the MMSI). Either id or ids is required, not both.
idsarray of integers≤ 500 valuesEntry ids to edit together.
labelstring≤ 100 chars · null clearsYour own name for the vessel.
groupstring≤ 60 chars · null clearsGroup name. Returned as group_name.
notesstring≤ 2000 chars · null clearsFree-text notes.
notifyOnarray of strings—Alert rules to switch on for this vessel: arrival, departure, destination, nav_status, sog, speed_threshold, heading_change, ais_gap, name, ship_type. An unknown key is a 400. Needs Pro.
speedThresholdnumber0.5–60 · null clearsThreshold for the speed_threshold rule, in kn. Values outside 0.5–60 are clamped. The rule does nothing until this is set. null clears it.
headingChangeDegnumber5–180 · null clearsThreshold for the heading_change rule, in °. Values outside 5–180 are clamped. Default 45 when not set. null clears it.
aisGapMinutesnumber15–1440 · null clearsThreshold for the ais_gap rule, in min. Values outside 15–1440 are clamped. Default 30 when not set. null clears it.
Request
curl -s -X PUT "https://www.vesseltrack.net/api/watchlist" \
  -H "X-API-Key: $VESSELTRACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":30,"notes":"On charter until March","notifyOn":["arrival","departure","ais_gap"],"aisGapMinutes":60,"speedThreshold":null}'
Response · 200 · application/json
{
  "message": "Updated",
  "item": {
    "id": 30,
    "mmsi": 311871866,
    "label": "Kestrel",
    "group_name": "Charters",
    "notes": "On charter until March",
    "notify_on": ["arrival", "departure", "ais_gap"],
    "speed_threshold_knots": null,
    "heading_change_degrees": null,
    "ais_gap_minutes": 60,
    "created_at": "2026-11-16T20:59:55.467Z"
  }
}

The updated entry.

Errors

StatusWhenBody
400Neither id nor ids was sent, or a field is invalid.{"error":"watchlist entry id is required"}
400Both id and ids were sent, or ids is empty, too long or not a list of ids.{"error":"send either id or ids, not both"}
401The request has only the website’s cookie: nobody is signed in and there is no API key.{"error":"Unauthorized"}
403notifyOn is non-empty and the caller does not have Pro access.{"error":"Alerts requires VesselTrack Pro.","code":"upgrade_required","upgrade_url":"/pricing"}
404Single form only: no entry with that id belongs to the caller.{"error":"Not found"}
DELETE/api/watchlistAPI key or signed-in session

Remove vessels

Take one vessel off the watchlist by entry id or MMSI, or several by entry id.

ids=5,6,7 removes several entries in one request, with the same bound as the bulk edit. It answers { message, removed, ids, missing } (for example {"message":"Removed","removed":0,"ids":[],"missing":[990,991]}): ids were removed, missing do not exist or are not yours. It is not a 404 when some are missing.

Access: API key or signed-in session. Acts on one account’s data. Send an API key, or call it from a signed-in browser session.

Query parameters

NameTypeDefault / limitsDescription
idintegermin 1The entry id. One of id, ids or mmsi is required.
idscomma-separated integers—Entry ids to remove together.
mmsiinteger1–999999999The vessel’s MMSI.
Request
curl -s -X DELETE "https://www.vesseltrack.net/api/watchlist?id=30" \
  -H "X-API-Key: $VESSELTRACK_API_KEY"
Response · 200 · application/json
{
  "message": "Removed"
}

Removed.

Errors

StatusWhenBody
400None of id, ids or mmsi was given.{"error":"id, ids or mmsi query param is required"}
400ids is empty, too long or not a list of ids.{"error":"ids must be a non-empty array of watchlist entry ids"}
401The request has only the website’s cookie: nobody is signed in and there is no API key.{"error":"Unauthorized"}
404id or mmsi matched nothing.{"error":"Not found"}
POST/api/watchlist/importAPI key or signed-in session

Import vessels

Add up to 500 vessels in one request.

Identifiers are processed in order. Each one is either added or reported in skipped with a reason: invalid (not a usable IMO/MMSI), not_found (no such vessel has been received), duplicate (already on the watchlist or repeated in the request) or limit_reached (the plan’s watchlist limit is full).

Imported entries have no alert rules; add them with the edit endpoint. A partial import is a 200, so check skipped.

Access: API key or signed-in session. Acts on one account’s data. Send an API key, or call it from a signed-in browser session.

JSON body

NameTypeDefault / limitsDescription
identifiersrequiredarray of strings or numbers≤ 500 values1–500 IMO numbers or MMSIs.
groupstring≤ 60 chars · null clearsGroup to put the imported vessels in.
Request
curl -s -X POST "https://www.vesseltrack.net/api/watchlist/import" \
  -H "X-API-Key: $VESSELTRACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"identifiers":["9169902","IMO 9203992",9126003,"not-a-ship",123456789],"group":"Imported"}'
Response · 200 · application/json
{
  "added": 2,
  "skipped": [
    {
      "identifier": "9126003",
      "reason": "duplicate"
    },
    {
      "identifier": "not-a-ship",
      "reason": "invalid"
    },
    {
      "identifier": "123456789",
      "reason": "not_found"
    }
  ],
  "count": 10,
  "limit": 500
}

What was added and what was not.

count
Watchlist size after the import.
limit
The plan’s watchlist limit.

Errors

StatusWhenBody
400identifiers is missing, empty or too long.{"error":"identifiers accepts at most 500 values per request"}
401The request has only the website’s cookie: nobody is signed in and there is no API key.{"error":"Unauthorized"}
GET/api/watchlist/exportPro

Export the fleet

Download the watchlist with each vessel’s current position, status, destination and ETA.

A file download named fleet-<YYYYMMDD>.csv or .json (UTC date). The JSON file is { exported_at, count, vessels } where vessels are the same objects the list endpoint returns. The CSV starts with a UTF-8 byte-order mark so spreadsheet programs read it as UTF-8; its last three columns are the thresholds of the speed, heading-change and AIS-gap rules (empty = the rule’s default). In the CSV, text from the ship is neutralised so a spreadsheet cannot run it as a formula.

Access: Pro. Needs Pro access. An API key always qualifies, because keys only work while the account has Pro. A signed-in free account gets 403 upgrade_required.

Query parameters

NameTypeDefault / limitsDescription
formatstringdefault csv · csv | jsonFile format.
Request
curl -s "https://www.vesseltrack.net/api/watchlist/export?format=csv" \
  -H "X-API-Key: $VESSELTRACK_API_KEY" \
  -o fleet.csv
Response · 200 · text/csv
mmsi,imo,name,call_sign,label,group,notes,ship_type,ship_type_text,nav_status,nav_status_text,lat,lon,sog_kn,cog_deg,heading_deg,destination,matched_destination,destination_port_code,eta_utc,draught_m,last_position_utc,alert_rules,added_utc,speed_threshold_kn,heading_change_deg,ais_gap_min
308738947,9126003,CAPE DREAM,C6EE,CAPE DREAM,Asia–Europe,Demo watchlist entry created by the local seed.,70,Cargo,0,Under way using engine,19.222241,-107.550136,11.8,129,132,USLAX>USNYC,"New York, USA",USNYC,2026-11-26T20:47:00.000Z,9,2026-11-16T20:51:58.428Z,destination sog speed_threshold,2026-11-13T19:59:15.428Z,12,,

The file.

Errors

StatusWhenBody
400format is not csv or json.{"error":"format must be csv or json"}
401The request has only the website’s cookie: nobody is signed in and there is no API key.{"error":"Unauthorized"}
403The caller does not have Pro access.{"error":"Fleet export requires VesselTrack Pro.","code":"upgrade_required","upgrade_url":"/pricing"}

Alert inbox

Alerts raised by watchlist rules and alert areas.

GET/api/watchlist/alertsAPI key or signed-in session

List alerts

The alert inbox, newest first: alerts from per-vessel rules and from alert areas.

key is the alert type: arrival, departure, destination, nav_status, sog, speed_threshold, heading_change, ais_gap, name, ship_type, area_enter, area_exit. Area alerts have watchlist_id null and area_id / area_name set, with lat/lon where the vessel crossed the boundary; for other alerts lat/lon is the vessel’s current position.

Page backwards with before=<id of the last alert you received>. Alerts are kept for 90 days. Alerts are produced only while the data feed is running; nothing is back-filled after an outage.

Access: API key or signed-in session. Acts on one account’s data. Send an API key, or call it from a signed-in browser session.

Query parameters

NameTypeDefault / limitsDescription
limitintegerdefault 50 · 1–200Page size.
beforeintegermin 1Return alerts with an id lower than this one.
unacknowledgedstring1 | trueOnly unread alerts.
Request
curl -s "https://www.vesseltrack.net/api/watchlist/alerts?limit=1&unacknowledged=1" \
  -H "X-API-Key: $VESSELTRACK_API_KEY"
Response · 200 · application/json
{
  "alerts": [
    {
      "id": 37,
      "watchlist_id": null,
      "area_id": 2,
      "area_name": "Dover Strait",
      "mmsi": 431872895,
      "vessel_name": "ONE INTEGRITY",
      "alert_type": "area_enter",
      "field_name": "area",
      "old_value": "Dover Strait",
      "new_value": "51.01221,1.46735",
      "key": "area_enter",
      "label": "Entered area",
      "message": "Entered area “Dover Strait”",
      "old_text": "Dover Strait",
      "new_text": "51.01221,1.46735",
      "acknowledged": false,
      "created_at": "2026-11-16T16:54:18.428Z",
      "lat": 51.012205,
      "lon": 1.467349
    }
  ],
  "unread": 14,
  "hasMore": true
}

One page of alerts.

unread
Total unacknowledged alerts for the account, regardless of paging.
hasMore
true when older alerts exist beyond this page.
alerts[].message
A one-line description. Contains text broadcast by ships.

Errors

StatusWhenBody
400before is not an alert id.{"error":"before must be an alert id"}
401The request has only the website’s cookie: nobody is signed in and there is no API key.{"error":"Unauthorized"}
PUT/api/watchlist/alertsAPI key or signed-in session

Acknowledge alerts

Mark specific alerts, or all of them, as read.

Access: API key or signed-in session. Acts on one account’s data. Send an API key, or call it from a signed-in browser session.

JSON body

NameTypeDefault / limitsDescription
alertIdsarray of integers≤ 500 valuesAlert ids to acknowledge (at most 500).
acknowledgeAllboolean—true to acknowledge every unread alert instead.
Request
curl -s -X PUT "https://www.vesseltrack.net/api/watchlist/alerts" \
  -H "X-API-Key: $VESSELTRACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"alertIds":[37]}'
Response · 200 · application/json
{
  "message": "Acknowledged",
  "acknowledged": 1
}

How many alerts changed from unread to read.

Errors

StatusWhenBody
400Neither alertIds nor acknowledgeAll was given.{"error":"Provide alertIds array or acknowledgeAll: true"}
401The request has only the website’s cookie: nobody is signed in and there is no API key.{"error":"Unauthorized"}

Alert areas

Rectangular areas that raise an alert when a vessel enters or leaves.

GET/api/areasAPI key or signed-in session

List areas

The account’s alert areas and how many it may have.

Without Pro access the list is empty and limit is 0.

Access: API key or signed-in session. Acts on one account’s data. Send an API key, or call it from a signed-in browser session.

Request
curl -s "https://www.vesseltrack.net/api/areas" \
  -H "X-API-Key: $VESSELTRACK_API_KEY"
Response · 200 · application/json
{
  "areas": [
    {
      "id": 8,
      "name": "Singapore Strait",
      "minLat": 1,
      "minLon": 103.4,
      "maxLat": 1.5,
      "maxLon": 104.4,
      "scope": "all",
      "shipCategories": ["cargo", "tanker"],
      "notifyEnter": true,
      "notifyExit": false,
      "enabled": true,
      "lastTriggeredAt": null,
      "createdAt": "2026-11-16T20:59:55.703Z"
    }
  ],
  "limit": 20
}

Areas, newest first.

Errors

StatusWhenBody
401The request has only the website’s cookie: nobody is signed in and there is no API key.{"error":"Unauthorized"}
POST/api/areasPro

Create an area

Define a rectangle that raises area_enter / area_exit alerts.

An alert is raised when a matching vessel’s position moves across the boundary between two consecutive reports. Alerts appear in the alert inbox and are sent to webhooks subscribed to alert.area_enter / alert.area_exit.

Access: Pro. Needs Pro access. An API key always qualifies, because keys only work while the account has Pro. A signed-in free account gets 403 upgrade_required.

JSON body

NameTypeDefault / limitsDescription
namerequiredstring≤ 80 charsName shown in alerts.
minLatrequirednumber-90–90Southern edge. Must be less than maxLat.
minLonrequirednumber-180–180Western edge. Greater than maxLon means the area crosses the antimeridian.
maxLatrequirednumber-90–90Northern edge.
maxLonrequirednumber-180–180Eastern edge.
scopestringdefault watchlist · watchlist | allwatchlist: only vessels on your watchlist. all: every vessel received — the area may then be at most 60° of longitude wide and 40° of latitude tall.
shipCategoriesarray of strings—Only vessels in these ship categories. Empty (the default) means every category.
notifyEnterbooleandefault trueAlert when a vessel enters.
notifyExitbooleandefault falseAlert when a vessel leaves. At least one of the two must be true.
Request
curl -s -X POST "https://www.vesseltrack.net/api/areas" \
  -H "X-API-Key: $VESSELTRACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Singapore Strait","minLat":1,"minLon":103.4,"maxLat":1.5,"maxLon":104.4,"scope":"all","shipCategories":["tanker","cargo"],"notifyEnter":true,"notifyExit":false}'
Response · 201 · application/json
{
  "area": {
    "id": 8,
    "name": "Singapore Strait",
    "minLat": 1,
    "minLon": 103.4,
    "maxLat": 1.5,
    "maxLon": 104.4,
    "scope": "all",
    "shipCategories": ["cargo", "tanker"],
    "notifyEnter": true,
    "notifyExit": false,
    "enabled": true,
    "lastTriggeredAt": null,
    "createdAt": "2026-11-16T20:59:55.703Z"
  }
}

The new area.

Errors

StatusWhenBody
400A field is missing or invalid, or an all-vessels area is too large.{"error":"An area that watches all vessels can be at most 60° of longitude wide. Make it smaller or set scope to 'watchlist'."}
401The request has only the website’s cookie: nobody is signed in and there is no API key.{"error":"Unauthorized"}
403The caller does not have Pro access.{"error":"Alert areas requires VesselTrack Pro.","code":"upgrade_required","upgrade_url":"/pricing"}
409The account already has the maximum number of areas.{"error":"You have reached your plan's limit of 20 alert areas.","code":"limit_reached","limit":20,"upgrade_url":"/pricing"}
PUT/api/areasPro

Update an area

Change any field of an area, or pause it with enabled: false.

Fields you leave out are unchanged. The combined result is validated as a whole.

Access: Pro. Needs Pro access. An API key always qualifies, because keys only work while the account has Pro. A signed-in free account gets 403 upgrade_required.

JSON body

NameTypeDefault / limitsDescription
idrequiredintegermin 1The area id.
namestring≤ 80 charsName shown in alerts.
minLatnumber-90–90Southern edge. Must be less than maxLat.
minLonnumber-180–180Western edge. Greater than maxLon means the area crosses the antimeridian.
maxLatnumber-90–90Northern edge.
maxLonnumber-180–180Eastern edge.
scopestringdefault watchlist · watchlist | allwatchlist: only vessels on your watchlist. all: every vessel received — the area may then be at most 60° of longitude wide and 40° of latitude tall.
shipCategoriesarray of strings—Only vessels in these ship categories. Empty (the default) means every category.
notifyEnterbooleandefault trueAlert when a vessel enters.
notifyExitbooleandefault falseAlert when a vessel leaves. At least one of the two must be true.
enabledboolean—false pauses the area without deleting it.
Request
curl -s -X PUT "https://www.vesseltrack.net/api/areas" \
  -H "X-API-Key: $VESSELTRACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":8,"notifyExit":true,"enabled":false}'
Response · 200 · application/json
{
  "area": {
    "id": 8,
    "name": "Singapore Strait",
    "minLat": 1,
    "minLon": 103.4,
    "maxLat": 1.5,
    "maxLon": 104.4,
    "scope": "all",
    "shipCategories": ["cargo", "tanker"],
    "notifyEnter": true,
    "notifyExit": true,
    "enabled": false,
    "lastTriggeredAt": null,
    "createdAt": "2026-11-16T20:59:55.703Z"
  }
}

The updated area.

Errors

StatusWhenBody
400id is missing or a field is invalid.{"error":"area id is required"}
401The request has only the website’s cookie: nobody is signed in and there is no API key.{"error":"Unauthorized"}
403The caller does not have Pro access.{"error":"Alert areas requires VesselTrack Pro.","code":"upgrade_required","upgrade_url":"/pricing"}
404No area with that id belongs to the caller.{"error":"Not found"}
DELETE/api/areasAPI key or signed-in session

Delete an area

Remove an area. Allowed on any plan.

Access: API key or signed-in session. Acts on one account’s data. Send an API key, or call it from a signed-in browser session.

Query parameters

NameTypeDefault / limitsDescription
idrequiredintegermin 1The area id.
Request
curl -s -X DELETE "https://www.vesseltrack.net/api/areas?id=8" \
  -H "X-API-Key: $VESSELTRACK_API_KEY"
Response · 200 · application/json
{
  "message": "Deleted"
}

Deleted.

Errors

StatusWhenBody
400id is missing.{"error":"id query param is required"}
401The request has only the website’s cookie: nobody is signed in and there is no API key.{"error":"Unauthorized"}
404No area with that id belongs to the caller.{"error":"Not found"}

Account

API usage for the account that owns the key.

GET/api/account/usageAPI key or signed-in session

API usage

The account’s hourly limit, requests in the last hour, a 14-day daily series and the latest requests.

Only requests made with an API key to non-public endpoints are counted, and only those that were admitted (a request rejected with 429 is not). Request records are kept for 30 days. recent[].status is currently always null: a request is logged when it is admitted, before its response exists.

Access: API key or signed-in session. Acts on one account’s data. Send an API key, or call it from a signed-in browser session.

Request
curl -s "https://www.vesseltrack.net/api/account/usage" \
  -H "X-API-Key: $VESSELTRACK_API_KEY"
Response · 200 · application/json
{
  "limitPerHour": 3600,
  "usedLastHour": 55,
  "days": [
    {
      "date": "2026-11-15",
      "count": 0
    },
    {
      "date": "2026-11-16",
      "count": 81
    }
  ],
  "recent": [
    {
      "method": "GET",
      "path": "/api/areas",
      "status": null,
      "at": "2026-11-16T20:57:33.534Z"
    }
  ]
}

Usage figures.

limitPerHour
The hourly limit enforced for this account (0 when the plan has no API key).
days
The last 14 UTC days, oldest first, zero-filled.
recent
The 20 most recent metered requests.

Errors

StatusWhenBody
401The request has only the website’s cookie: nobody is signed in and there is no API key.{"error":"Unauthorized"}

Webhooks

Endpoints of yours that VesselTrack posts events to, and their delivery log.

A webhook endpoint is a URL of yours that VesselTrack sends a signed JSON POST to when something happens. Create and manage endpoints with the API below or at Account → Webhooks.

Queued deliveries are currently sent about once a minute.

How delivery works

  • Up to 5 endpoints per account.
  • HTTPS only, on port 443 or 8443. The host must resolve to public internet addresses; redirects are not followed.
  • Respond with any 2xx status within 8 seconds. Do the real work after you have answered.
  • A failed delivery is retried up to 5 more times, waiting 1 min, 5 min, 30 min, 2 h, 6 h between attempts.
  • After 10 deliveries in a row have failed every attempt, the endpoint is switched off and you are emailed.
  • If the endpoint does not answer at all (a timeout or a refused connection), deliveries to it are paused — for 1 min, 5 min, 15 min, 1 h, 2 h, 6 h, growing each time — and held, not lost. After each pause one delivery is tried; any HTTP response resumes normal delivery. 8 unanswered tries in a row switch the endpoint off.
  • Switching an endpoint back on does not end a pause. A successful test event does.
  • At most 500 deliveries per endpoint per hour; events beyond that are dropped, not queued.
  • Delivery is at-least-once and not ordered. Use the delivery id to ignore duplicates and createdAt to order events.
  • Delivery attempts are kept for 7 days. Response bodies are not stored.
  • Deliveries are sent by a scheduled job that currently runs about once a minute; an event waits for the next run. Events more than 72 hours old when the job runs are not sent.
  • Events are produced from AIS data received by terrestrial stations. When the data feed is offline no events are produced, and they are not back-filled afterwards.

Event catalogue

An endpoint has one scope, which decides which events it can receive. Leave eventTypes empty to receive every type of the scope.

scope: "watchlist" — My alerts

Every alert raised for you — by the alert rules on vessels in your fleet and by your alert areas — is queued for delivery and posted when the delivery job next runs (currently about once a minute). Whatever appears in your alert inbox can be delivered here.

Event typeNameSent when
alert.arrivalArrivalThe vessel reports it has moored or anchored.
alert.departureDepartureThe vessel gets under way after being moored or at anchor.
alert.destinationDestination changeThe crew enters a new destination in the AIS transponder.
alert.nav_statusNavigation status changeAny change of reported status, e.g. under way → restricted manoeuvrability.
alert.sogSpeed changeSpeed over ground changes by 2 knots or more between reports.
alert.speed_thresholdSpeed thresholdSpeed crosses the threshold you set, in either direction.
alert.heading_changeCourse alterationHeading changes by at least the number of degrees you set.
alert.ais_gapAIS signal lostNo position report has been received for the period you set.
alert.nameName changeThe vessel starts broadcasting a different name.
alert.ship_typeShip type changeThe broadcast ship-type code changes.
alert.area_enterEntered areaA matching vessel crosses into one of your alert areas.
alert.area_exitLeft areaA matching vessel leaves one of your alert areas.

scope: "fleet" — All vessels, filtered

Events from every vessel VesselTrack receives, narrowed by filters you choose: ship category, flag, destination port or country, a bounding box, or specific vessels. At least one filter is required.

Event typeNameSent when
port.arrivalPort arrivalA vessel comes to a stop (moored, at anchor or stationary) within range of a known port. Sent once per port call.
port.departurePort departureA vessel that was in a port moves away from it. Sent once per port call, and only when the departure was observed.
port.expected_arrivalExpected arrivalThe destination a vessel reports newly resolves to a known port, or changes to a different port.
vessel.destinationDestination changeThe destination text a vessel broadcasts changes.
vessel.draughtDraught changeThe reported maximum draught changes, which usually means cargo was loaded or discharged.
vessel.nameName changeA vessel starts broadcasting a different name.
vessel.call_signCall sign changeA vessel starts broadcasting a different call sign.
vessel.imoIMO number changeThe IMO number a vessel broadcasts changes.
vessel.ship_typeShip type changeThe broadcast ship-type code changes.

Payload

Every event has the same envelope. Values in this sample are illustrative.

POST body
{
  "id": "evt_1842",
  "type": "port.arrival",
  "apiVersion": "2026-11-01",
  "createdAt": "2026-11-17T04:12:09.000Z",
  "scope": "fleet",
  "webhookId": 12,
  "summary": "MAERSK TAURANGA arrived at Tauranga (NZTRG)",
  "vessel": {
    "mmsi": 512345678,
    "imo": 9321483,
    "name": "MAERSK TAURANGA",
    "callSign": "ZMAB",
    "shipType": 71,
    "shipCategory": "cargo",
    "flag": "NZ",
    "lat": -37.6412,
    "lon": 176.1803,
    "sog": 0.1,
    "cog": null,
    "heading": 214,
    "navStatus": 5,
    "destination": "NZ TRG",
    "destinationPort": "NZTRG",
    "lastPositionAt": "2026-11-17T04:11:52.000Z"
  },
  "event": {
    "source": "vessel_event",
    "id": 480921,
    "observedAt": "2026-11-17T04:11:52.000Z"
  },
  "port": {
    "locode": "NZTRG",
    "name": "Tauranga",
    "country": "NZ"
  }
}
FieldMeaning
idDelivery id. Unique per endpoint delivery and the same on every retry.
typeEvent type from the catalogue, or "ping" for a test event.
apiVersionPayload version, currently 2026-11-01. Fields may be added within a version.
createdAtWhen VesselTrack recorded the event (ISO 8601, UTC).
scope"watchlist" (your alerts) or "fleet" (all vessels, filtered).
webhookIdThe endpoint the event was sent to.
summaryOne line in words. Contains text broadcast by ships: escape it before putting it in HTML.
vesselThe vessel's current record. Values a ship reports as "not available" are null. null for test events.
eventsource (watchlist_alert, vessel_event, vessel_history or test), the id within that source, and observedAt.
changePresent when a value changed: field, old, new (text).
portPresent for port events: locode, name, country.
areaPresent for alert-area alerts: id, name, and the lat/lon where the vessel crossed the boundary.

Request headers

HeaderValue
Content-Typeapplication/json; charset=utf-8
User-AgentVesselTrack-Webhooks/1.0 (+https://www.vesseltrack.net/api-docs)
Accept*/*
X-VesselTrack-EventThe event type, e.g. port.arrival. Same as "type" in the body.
X-VesselTrack-DeliveryThe delivery id, e.g. evt_1842. Same as "id" in the body and identical on every retry — dedupe on it.
X-VesselTrack-AttemptAttempt number, starting at 1.
X-VesselTrack-Signaturet=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" keyed with your signing secret>

Verifying signatures

Each endpoint has a signing secret (whsec_…), shown once when the endpoint is created or the secret is rotated. Compute the HMAC over the raw request body, exactly as received, and compare in constant time. Reject requests whose timestamp is too old, so a captured request cannot be replayed.

Node.js
import crypto from 'node:crypto';

// rawBody: the request body exactly as received (a string or Buffer), not re-serialised JSON.
// header:  the value of the X-VesselTrack-Signature header.
export function verifyVesselTrackSignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    String(header || '').split(',').map((part) => part.trim().split('=')),
  );
  const timestamp = Number(parts.t);
  if (!Number.isInteger(timestamp) || !/^[0-9a-f]{64}$/.test(parts.v1 || '')) return false;

  // Reject old requests so a captured one cannot be replayed later.
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest();
  const given = Buffer.from(parts.v1, 'hex');
  return given.length === expected.length && crypto.timingSafeEqual(given, expected);
}

// Express example — note express.raw(), so the body is not parsed before it is verified:
//
//   app.post('/vesseltrack', express.raw({ type: 'application/json' }), (req, res) => {
//     const ok = verifyVesselTrackSignature(
//       req.body, req.get('X-VesselTrack-Signature'), process.env.VESSELTRACK_WEBHOOK_SECRET);
//     if (!ok) return res.status(400).end();
//     res.status(204).end();                    // answer first…
//     handle(JSON.parse(req.body));             // …then do the work
//   });
Python
import hashlib
import hmac
import re
import time


def verify_vesseltrack_signature(raw_body: bytes, header: str, secret: str,
                                 tolerance_seconds: int = 300) -> bool:
    """raw_body is the request body exactly as received, before any JSON parsing."""
    parts = dict(p.strip().split("=", 1) for p in (header or "").split(",") if "=" in p)
    timestamp, signature = parts.get("t", ""), parts.get("v1", "")
    if not timestamp.isdigit() or not re.fullmatch(r"[0-9a-f]{64}", signature):
        return False

    # Reject old requests so a captured one cannot be replayed later.
    if abs(time.time() - int(timestamp)) > tolerance_seconds:
        return False

    expected = hmac.new(
        secret.encode("utf-8"),
        timestamp.encode("ascii") + b"." + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


# Flask example:
#
#   @app.post("/vesseltrack")
#   def vesseltrack():
#       ok = verify_vesseltrack_signature(
#           request.get_data(), request.headers.get("X-VesselTrack-Signature", ""),
#           os.environ["VESSELTRACK_WEBHOOK_SECRET"])
#       if not ok:
#           abort(400)
#       enqueue(request.get_json())   # do the work after answering
#       return "", 204

Management API

GET/api/webhooksAPI key or signed-in session

List endpoints

The account’s webhook endpoints and how many it may have.

Existing endpoints are listed on any plan so they can still be seen and deleted after a subscription ends; limit is 0 without Pro, and nothing is delivered.

health is one of: active; failing (recent deliveries are failing); unreachable (the endpoint is not answering, deliveries are held until pausedUntil); secret_unreadable (deliveries are held until you rotate the signing secret); paused (switched off by you); disabled (switched off automatically; see disabledReason).

An endpoint that does not answer at all (timeout, refused connection, TLS or DNS failure) is paused: pausedUntil is set (1 min, 5 min, 15 min, 1 h, 2 h, 6 h, growing with each silence) and pauseReason is "unreachable"; its queued deliveries are held until then, not failed. After the pause one delivery is tried; any HTTP response resumes normal delivery, and 8 unanswered tries in a row switch the endpoint off. pauseReason "secret_unreadable" means the stored signing secret can no longer be decrypted on our side: deliveries are held until you rotate the secret.

Access: API key or signed-in session. Acts on one account’s data. Send an API key, or call it from a signed-in browser session.

Request
curl -s "https://www.vesseltrack.net/api/webhooks" \
  -H "X-API-Key: $VESSELTRACK_API_KEY"
Response · 200 · application/json
{
  "webhooks": [
    {
      "id": 1,
      "url": "https://hooks.example.com/vesseltrack",
      "description": "Ops alerts",
      "scope": "watchlist",
      "eventTypes": ["alert.arrival", "alert.departure", "alert.area_enter"],
      "filters": {},
      "enabled": true,
      "disabledReason": null,
      "consecutiveFailures": 0,
      "lastSuccessAt": null,
      "lastFailureAt": null,
      "pausedUntil": null,
      "pauseReason": null,
      "createdAt": "2026-11-16T21:08:25.238Z",
      "health": "active",
      "secretHint": "Ja_U",
      "disabledAt": null,
      "lastRateLimitedAt": null
    },
    {
      "id": 2,
      "url": "https://hooks.example.com/tankers",
      "description": null,
      "scope": "fleet",
      "eventTypes": ["port.arrival", "port.departure"],
      "filters": {
        "shipCategories": ["tanker"],
        "destinationPorts": ["SGSIN"]
      },
      "enabled": true,
      "disabledReason": null,
      "consecutiveFailures": 0,
      "lastSuccessAt": null,
      "lastFailureAt": null,
      "pausedUntil": null,
      "pauseReason": null,
      "createdAt": "2026-11-16T21:08:25.253Z",
      "health": "active",
      "secretHint": "Rqcg",
      "disabledAt": null,
      "lastRateLimitedAt": null
    }
  ],
  "limit": 5
}

Endpoints, oldest first.

webhooks[].secretHint
The last four characters of the signing secret. The secret itself is only returned when it is created or rotated.
webhooks[].lastRateLimitedAt
The last time events were dropped because of the hourly delivery cap.
webhooks[].pausedUntil
Deliveries are held until this time, or null. Switching the endpoint off and on does not clear it; a successful test event does.
webhooks[].pauseReason
"unreachable", "secret_unreadable" or null.

Errors

StatusWhenBody
401The request has only the website’s cookie: nobody is signed in and there is no API key.{"error":"Unauthorized"}
POST/api/webhooksPro

Create an endpoint

Register a URL to receive events, and get its signing secret.

secret is returned in this response and never again: store it now. A new endpoint starts from the moment it is created; earlier events are not sent.

The host is resolved when you save, so use a URL of your own: the placeholder host in this example does not resolve and is rejected with a 400.

Create, update, test and rotate-secret calls are limited to 30 per account per 10 minutes, and creates plus URL changes to 12 per hour; past that the answer is 429 rate_limited with Retry-After.

Access: Pro. Needs Pro access. An API key always qualifies, because keys only work while the account has Pro. A signed-in free account gets 403 upgrade_required.

JSON body

NameTypeDefault / limitsDescription
urlrequiredstring≤ 2048 charsWhere to POST events. HTTPS only, port 443 or 8443, no credentials in the URL, and the host must resolve to public internet addresses. Host names that spell a non-public address (127.0.0.1.nip.io, 10-0-0-1.sslip.io, 7f000001.nip.io), names that always point at the local machine (localtest.me, lvh.me, vcap.me) and internal-looking names (.local, .internal, .lan, …) are refused.
scoperequiredstringwatchlist | fleetwatchlist: your own alerts (per-vessel rules and alert areas). fleet: events from every vessel received, narrowed by filters.
descriptionstring≤ 200 chars · null clearsA note for yourself.
eventTypesarray of strings—Event types to send; empty or omitted means every type of the scope. watchlist: alert.arrival, alert.departure, alert.destination, alert.nav_status, alert.sog, alert.speed_threshold, alert.heading_change, alert.ais_gap, alert.name, alert.ship_type, alert.area_enter, alert.area_exit. fleet: port.arrival, port.departure, port.expected_arrival, vessel.destination, vessel.draught, vessel.name, vessel.call_sign, vessel.imo, vessel.ship_type. A type from the other scope is a 400.
filtersobject—fleet scope only, and at least one is required there: shipCategories, flags, mmsis, destinationPorts, destinationCountries, bbox. shipCategories takes category slugs (cargo, tanker, passenger, …); flags and destinationCountries take ISO alpha-2 codes; destinationPorts takes UN/LOCODEs that exist in the port directory (each list at most 50 entries); mmsis takes up to 500 nine-digit MMSIs; bbox is { minLat, minLon, maxLat, maxLon }, at most 60° wide and 40° tall. Every filter present must match; within a list any entry may match. An unknown filter name is a 400.
enabledbooleandefault truefalse switches the endpoint off and cancels whatever is queued for it. true switches it back on, starting from now; it does not end a pause that is still running (see pausedUntil), and the endpoint comes back one delivery at a time until one is answered.
Request
curl -s -X POST "https://www.vesseltrack.net/api/webhooks" \
  -H "X-API-Key: $VESSELTRACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/vesseltrack","description":"Ops alerts","scope":"watchlist","eventTypes":["alert.arrival","alert.departure","alert.area_enter"]}'
Response · 201 · application/json
{
  "webhook": {
    "id": 1,
    "url": "https://hooks.example.com/vesseltrack",
    "description": "Ops alerts",
    "scope": "watchlist",
    "eventTypes": ["alert.arrival", "alert.departure", "alert.area_enter"],
    "filters": {},
    "enabled": true,
    "disabledReason": null,
    "consecutiveFailures": 0,
    "lastSuccessAt": null,
    "lastFailureAt": null,
    "pausedUntil": null,
    "pauseReason": null,
    "createdAt": "2026-11-16T21:08:25.238Z",
    "health": "active",
    "secretHint": "Ja_U",
    "disabledAt": null,
    "lastRateLimitedAt": null
  },
  "secret": "whsec_<43 characters, shown once>"
}

The endpoint and its signing secret.

Errors

StatusWhenBody
400The URL is not acceptable, an event type or filter is unknown, or a fleet endpoint has no filter.{"error":"url must start with https://"}
400The host name itself is not allowed: it spells a non-public address, always points at the local machine, or looks internal.{"error":"url host name spells a loopback address (127.0.0.1), which is not allowed"}
400The host does not resolve, or resolves to an address that is not on the public internet.{"error":"url: The host name could not be resolved"}
401The request has only the website’s cookie: nobody is signed in and there is no API key.{"error":"Unauthorized"}
403The caller does not have Pro access.{"error":"Webhooks requires VesselTrack Pro.","code":"upgrade_required","upgrade_url":"/pricing"}
429Too many create, update, test or rotate-secret calls from this account in a short time. Retry-After says when to try again.{"error":"Too many webhook changes in a short time. Try again in a few minutes.","code":"rate_limited"}
429More than 12 creates and URL changes from this account in an hour.{"error":"Too many endpoint URL changes. Try again later.","code":"rate_limited"}
409The account already has the maximum number of endpoints.{"error":"You have reached your plan's limit of 5 webhook endpoints.","code":"limit_reached","limit":5,"upgrade_url":"/pricing"}
PUT/api/webhooksPro

Update an endpoint

Change an endpoint’s URL, events or filters, or switch it off and on.

Fields you leave out are unchanged. Changing scope drops the old event types and filters unless you send new ones. Switching an endpoint on, or changing what it matches, restarts it from now: events from while it was off are not sent. Switching it on or changing the URL clears its failure streak (consecutiveFailures).

Switching an endpoint on does not end a pause (pausedUntil): a pause that is still running keeps running, and the endpoint comes back on probation, one delivery at a time, until a delivery is answered. To lift an "unreachable" pause early, send a test event that succeeds, or change the URL (a new URL also starts on probation).

Create, update, test and rotate-secret calls are limited to 30 per account per 10 minutes, and creates plus URL changes to 12 per hour; past that the answer is 429 rate_limited with Retry-After.

Access: Pro. Needs Pro access. An API key always qualifies, because keys only work while the account has Pro. A signed-in free account gets 403 upgrade_required.

JSON body

NameTypeDefault / limitsDescription
idrequiredintegermin 1The endpoint id.
urlstring≤ 2048 charsWhere to POST events. HTTPS only, port 443 or 8443, no credentials in the URL, and the host must resolve to public internet addresses. Host names that spell a non-public address (127.0.0.1.nip.io, 10-0-0-1.sslip.io, 7f000001.nip.io), names that always point at the local machine (localtest.me, lvh.me, vcap.me) and internal-looking names (.local, .internal, .lan, …) are refused.
scopestringwatchlist | fleetwatchlist: your own alerts (per-vessel rules and alert areas). fleet: events from every vessel received, narrowed by filters.
descriptionstring≤ 200 chars · null clearsA note for yourself.
eventTypesarray of strings—Event types to send; empty or omitted means every type of the scope. watchlist: alert.arrival, alert.departure, alert.destination, alert.nav_status, alert.sog, alert.speed_threshold, alert.heading_change, alert.ais_gap, alert.name, alert.ship_type, alert.area_enter, alert.area_exit. fleet: port.arrival, port.departure, port.expected_arrival, vessel.destination, vessel.draught, vessel.name, vessel.call_sign, vessel.imo, vessel.ship_type. A type from the other scope is a 400.
filtersobject—fleet scope only, and at least one is required there: shipCategories, flags, mmsis, destinationPorts, destinationCountries, bbox. shipCategories takes category slugs (cargo, tanker, passenger, …); flags and destinationCountries take ISO alpha-2 codes; destinationPorts takes UN/LOCODEs that exist in the port directory (each list at most 50 entries); mmsis takes up to 500 nine-digit MMSIs; bbox is { minLat, minLon, maxLat, maxLon }, at most 60° wide and 40° tall. Every filter present must match; within a list any entry may match. An unknown filter name is a 400.
enabledbooleandefault truefalse switches the endpoint off and cancels whatever is queued for it. true switches it back on, starting from now; it does not end a pause that is still running (see pausedUntil), and the endpoint comes back one delivery at a time until one is answered.
Request
curl -s -X PUT "https://www.vesseltrack.net/api/webhooks" \
  -H "X-API-Key: $VESSELTRACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":1,"description":"Ops alerts (staging)","enabled":false}'
Response · 200 · application/json
{
  "webhook": {
    "id": 1,
    "url": "https://hooks.example.com/vesseltrack",
    "description": "Ops alerts (staging)",
    "scope": "watchlist",
    "eventTypes": ["alert.arrival", "alert.departure", "alert.area_enter"],
    "filters": {},
    "enabled": false,
    "disabledReason": null,
    "consecutiveFailures": 0,
    "lastSuccessAt": null,
    "lastFailureAt": null,
    "pausedUntil": null,
    "pauseReason": null,
    "createdAt": "2026-11-16T21:08:25.238Z",
    "health": "paused",
    "secretHint": "Ja_U",
    "disabledAt": "2026-11-16T21:08:25.266Z",
    "lastRateLimitedAt": null
  }
}

The updated endpoint.

Errors

StatusWhenBody
400id is missing or a field is invalid.{"error":"webhook id is required"}
401The request has only the website’s cookie: nobody is signed in and there is no API key.{"error":"Unauthorized"}
403The caller does not have Pro access.{"error":"Webhooks requires VesselTrack Pro.","code":"upgrade_required","upgrade_url":"/pricing"}
404Nothing with that id belongs to the caller.{"error":"Not found"}
429Too many create, update, test or rotate-secret calls from this account in a short time. Retry-After says when to try again.{"error":"Too many webhook changes in a short time. Try again in a few minutes.","code":"rate_limited"}
429More than 12 creates and URL changes from this account in an hour.{"error":"Too many endpoint URL changes. Try again later.","code":"rate_limited"}
DELETE/api/webhooksAPI key or signed-in session

Delete an endpoint

Remove an endpoint and its delivery log. Allowed on any plan.

Access: API key or signed-in session. Acts on one account’s data. Send an API key, or call it from a signed-in browser session.

Query parameters

NameTypeDefault / limitsDescription
idrequiredintegermin 1The endpoint id.
Request
curl -s -X DELETE "https://www.vesseltrack.net/api/webhooks?id=1" \
  -H "X-API-Key: $VESSELTRACK_API_KEY"
Response · 200 · application/json
{
  "message": "Deleted"
}

Deleted.

Errors

StatusWhenBody
400id is missing.{"error":"id query param is required"}
401The request has only the website’s cookie: nobody is signed in and there is no API key.{"error":"Unauthorized"}
404Nothing with that id belongs to the caller.{"error":"Not found"}
POST/api/webhooks/{id}/testPro

Send a test event

Post a signed "ping" event to the endpoint now and report what came back.

Synchronous, one attempt, no retries. The request to VesselTrack succeeds with 200 even when your endpoint fails: check ok. error is a short code (timeout, dns_failed, tls_error, connection_refused, http_503, …) and errorDetail says it in words. One test per endpoint every 10 seconds.

Works on a switched-off endpoint, so you can check it before switching it back on. A test does not count towards the failure streak, but it is evidence: a 2xx answer ends an "unreachable" pause at once and releases the held deliveries (the endpoint stays on probation until a real delivery is answered), and error signing_unavailable marks the endpoint secret_unreadable until you rotate the secret.

Create, update, test and rotate-secret calls are limited to 30 per account per 10 minutes, and creates plus URL changes to 12 per hour; past that the answer is 429 rate_limited with Retry-After.

Access: Pro. Needs Pro access. An API key always qualifies, because keys only work while the account has Pro. A signed-in free account gets 403 upgrade_required.

Path parameters

NameTypeDefault / limitsDescription
idrequiredintegermin 1The webhook endpoint id.
Request
curl -s -X POST "https://www.vesseltrack.net/api/webhooks/1/test" \
  -H "X-API-Key: $VESSELTRACK_API_KEY"
Response · 200 · application/json
{
  "ok": true,
  "statusCode": 204,
  "durationMs": 142,
  "error": null,
  "errorDetail": null,
  "deliveryId": 1
}

The outcome of the attempt.

deliveryId
The test appears in the delivery log under this id.

Errors

StatusWhenBody
401The request has only the website’s cookie: nobody is signed in and there is no API key.{"error":"Unauthorized"}
403The caller does not have Pro access.{"error":"Webhooks requires VesselTrack Pro.","code":"upgrade_required","upgrade_url":"/pricing"}
404Nothing with that id belongs to the caller.{"error":"Not found"}
429A test was sent to this endpoint moments ago.{"error":"A test event was sent a moment ago. Wait 10 seconds between tests.","code":"test_rate_limited"}
429Too many create, update, test or rotate-secret calls from this account in a short time. Retry-After says when to try again.{"error":"Too many webhook changes in a short time. Try again in a few minutes.","code":"rate_limited"}
POST/api/webhooks/{id}/rotate-secretPro

Rotate the signing secret

Replace an endpoint’s signing secret.

The new secret is returned once. The old one stops working immediately: every delivery from now on, retries included, is signed with the new secret.

Rotating is also the fix for health secret_unreadable: the hold is lifted and the deliveries that were waiting are sent, signed with the new secret.

Create, update, test and rotate-secret calls are limited to 30 per account per 10 minutes, and creates plus URL changes to 12 per hour; past that the answer is 429 rate_limited with Retry-After.

Access: Pro. Needs Pro access. An API key always qualifies, because keys only work while the account has Pro. A signed-in free account gets 403 upgrade_required.

Path parameters

NameTypeDefault / limitsDescription
idrequiredintegermin 1The webhook endpoint id.
Request
curl -s -X POST "https://www.vesseltrack.net/api/webhooks/1/rotate-secret" \
  -H "X-API-Key: $VESSELTRACK_API_KEY"
Response · 200 · application/json
{
  "secret": "whsec_<43 characters, shown once>"
}

The new secret.

Errors

StatusWhenBody
401The request has only the website’s cookie: nobody is signed in and there is no API key.{"error":"Unauthorized"}
403The caller does not have Pro access.{"error":"Webhooks requires VesselTrack Pro.","code":"upgrade_required","upgrade_url":"/pricing"}
404Nothing with that id belongs to the caller.{"error":"Not found"}
429Too many create, update, test or rotate-secret calls from this account in a short time. Retry-After says when to try again.{"error":"Too many webhook changes in a short time. Try again in a few minutes.","code":"rate_limited"}
GET/api/webhooks/{id}/deliveriesAPI key or signed-in session

Delivery log

Recent deliveries to an endpoint, newest first, with the state of each.

status is pending (queued or waiting to retry), success, exhausted (all 6 attempts failed), failed (a test event that failed) or canceled. request is the request as it would be sent now; the signature is recomputed for every attempt, so only its format is shown. Response bodies are never stored. Deliveries are kept for 7 days. Page with before=<id of the last delivery you received>.

Access: API key or signed-in session. Acts on one account’s data. Send an API key, or call it from a signed-in browser session.

Path parameters

NameTypeDefault / limitsDescription
idrequiredintegermin 1The webhook endpoint id.

Query parameters

NameTypeDefault / limitsDescription
limitintegerdefault 50 · 1–200Page size.
beforeintegermin 1Return deliveries with an id lower than this one.
Request
curl -s "https://www.vesseltrack.net/api/webhooks/1/deliveries?limit=1" \
  -H "X-API-Key: $VESSELTRACK_API_KEY"
Response · 200 · application/json
{
  "deliveries": [
    {
      "id": 1,
      "eventId": "evt_1",
      "type": "ping",
      "typeLabel": "Test event",
      "status": "success",
      "attempts": 1,
      "maxAttempts": 1,
      "statusCode": 204,
      "durationMs": 142,
      "error": null,
      "errorDetail": null,
      "nextAttemptAt": null,
      "lastAttemptAt": "2026-11-16T21:08:25.281Z",
      "deliveredAt": "2026-11-16T21:08:25.283Z",
      "createdAt": "2026-11-16T21:08:25.281Z",
      "canRedeliver": false,
      "request": {
        "method": "POST",
        "url": "https://hooks.example.com/vesseltrack",
        "headers": {
          "Content-Type": "application/json; charset=utf-8",
          "User-Agent": "VesselTrack-Webhooks/1.0 (+https://www.vesseltrack.net/api-docs)",
          "Accept": "*/*",
          "X-VesselTrack-Event": "ping",
          "X-VesselTrack-Delivery": "evt_1",
          "X-VesselTrack-Attempt": "1",
          "X-VesselTrack-Signature": "t=<unix seconds>,v1=<hmac-sha256 hex>"
        },
        "body": {
          "id": "evt_1",
          "type": "ping",
          "apiVersion": "2026-11-01",
          "scope": "watchlist",
          "webhookId": 1,
          "createdAt": "2026-11-16T21:08:25.281Z",
          "summary": "Test event from VesselTrack. If you can read this, your endpoint is reachable.",
          "vessel": null,
          "event": {
            "source": "test",
            "id": 1794863305280,
            "observedAt": "2026-11-16T21:08:25.281Z"
          }
        }
      },
      "response": {
        "statusCode": 204,
        "durationMs": 142
      }
    }
  ],
  "hasMore": false
}

One page of deliveries.

Errors

StatusWhenBody
400before is not a delivery id.{"error":"before must be a delivery id"}
401The request has only the website’s cookie: nobody is signed in and there is no API key.{"error":"Unauthorized"}
404Nothing with that id belongs to the caller.{"error":"Not found"}
POST/api/webhooks/{id}/deliveries/{deliveryId}/redeliverPro

Redeliver

Queue a delivery that was given up or cancelled again, with a fresh set of attempts.

Only deliveries whose canRedeliver is true (status exhausted or canceled, not a test event, source event still on record), on an endpoint that is switched on. It is sent by the next delivery run, not inline.

Access: Pro. Needs Pro access. An API key always qualifies, because keys only work while the account has Pro. A signed-in free account gets 403 upgrade_required.

Path parameters

NameTypeDefault / limitsDescription
idrequiredintegermin 1The webhook endpoint id.
deliveryIdrequiredintegermin 1The numeric delivery id from the delivery log (not the evt_… string).
Request
curl -s -X POST "https://www.vesseltrack.net/api/webhooks/1/deliveries/1/redeliver" \
  -H "X-API-Key: $VESSELTRACK_API_KEY"
Response · 202 · application/json
{
  "message": "Queued for redelivery"
}

Queued.

Errors

StatusWhenBody
401The request has only the website’s cookie: nobody is signed in and there is no API key.{"error":"Unauthorized"}
403The caller does not have Pro access.{"error":"Webhooks requires VesselTrack Pro.","code":"upgrade_required","upgrade_url":"/pricing"}
404Nothing with that id belongs to the caller.{"error":"Not found"}
409The delivery is not in a state that can be redelivered.{"error":"Only deliveries that were given up or cancelled can be redelivered.","code":"not_redeliverable"}
409The endpoint is switched off.{"error":"Switch the endpoint on before redelivering.","code":"endpoint_disabled"}

This API

The machine-readable description of everything on this page.

GET/api/openapi.jsonPublic

OpenAPI description

This reference as an OpenAPI 3.1 document, generated from the same catalogue as this page.

Response schemas are derived from the documented examples. A property shown as nullable may be null whenever the ship did not report it.

Access: Public. No credentials. Served to anyone and cached at the CDN. Not counted against your key’s hourly allowance, but limited per IP address: far more requests than a person using the map would send get 429 with Retry-After.

Request
curl -s "https://www.vesseltrack.net/api/openapi.json"
Response · 200 · application/json
{
  "openapi": "3.1.0",
  "info": {
    "title": "VesselTrack API",
    "version": "2026-11"
  },
  "…": "servers, tags, paths, components"
}

An OpenAPI 3.1 document.