/api/vessels/mapPublicMap 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
| Name | Type | Default / limits | Description |
|---|---|---|---|
| format | string | default json · json | compact | json: 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). |
| bbox | west,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_category | comma-separated slugs | ≤ 20 values | Ship 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_type | comma-separated integers | ≤ 100 values | Exact 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_status | comma-separated integers | ≤ 16 values | AIS navigational status codes, 0–15 (0 under way using engine, 1 at anchor, 5 moored, …). |
| fix_type | comma-separated integers | ≤ 16 values | AIS position-fix device codes, 0–15 (1 GPS, 2 GLONASS, …). |
| flag | comma-separated | ≤ 20 values | Flag 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_min | number | 0–102.2 | Minimum speed over ground, knots. Vessels whose speed is “not available” never match a speed bound. |
| sog_max | number | 0–102.2 | Maximum speed over ground, knots. |
| has_name | string | 1 | true | Only vessels that broadcast a name. |
| stale_minutes | integer | 1–527040 | Only vessels whose last position is newer than this many minutes. |
| updated_since | ISO 8601 timestamp | — | Only vessels whose last position is at or after this ISO 8601 instant. |
| updated_before | ISO 8601 timestamp | — | Only vessels whose last position is at or before this ISO 8601 instant. |
| destination | string | 2–40 chars | Substring of the destination text the crew entered (case-insensitive). |
| destination_port | comma-separated UN/LOCODEs | ≤ 20 values | Vessels whose destination resolves to one of these ports, e.g. SGSIN,NLRTM. Alias: dest_ports. |
| destination_country | comma-separated | ≤ 20 values | Vessels bound for one of these countries, as names or ISO alpha-2 codes. Alias: dest_countries. Ports and countries are OR-ed together. |
| destination_city | comma-separated | ≤ 20 values | Vessels bound for one of these cities. AND-ed with the port/country selection. |
| mmsi | comma-separated MMSIs | ≤ 100 values | Only 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_unknown | string | 1 | Include vessels that have not reported a ship type. |
| limit | integer | 1–50000 | Maximum 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. |
curl -s "https://www.vesseltrack.net/api/vessels/map?bbox=103,0.5,105,2&ship_category=cargo,tanker&limit=2"{
"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.
curl -s "https://www.vesseltrack.net/api/vessels/map?format=compact&bbox=103,0.5,105,2&ship_category=cargo,tanker&sog_min=8"{
"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.
// 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
| Status | When | Body |
|---|---|---|
| 400 | A 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."} |
| 400 | bbox is not four numbers, or has no area. | {"error":"bbox must be west,south,east,north in decimal degrees"} |
| 400 | format is not json or compact. | {"error":"format must be json or compact"} |
| 400 | mmsi 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)"} |