The objects these APIs describe, how they relate, and the maritime vocabulary you need to read a response. For request mechanics see Pagination & Filtering, and for credentials see Authentication.
Almost every call starts from one of five things. Knowing which one you are holding tells you which category to reach for.
Vessel
A ship, identified by IMO number. The IMO stays with the hull for life, so it is the safest key to store. Everything about identity, position and behaviour hangs off it.
Voyage
A vessel's activity over time, expressed as events: port calls, zone crossings, AIS gaps, ship-to-ship pairings, positional discrepancies and port state control inspections. We derive all but the inspections from positions; inspection regimes publish those.
Zone
An area of water. Some are jurisdictional and standard, some are ours, some you draw yourself. A port is modelled as a type of zone.
Fleet
A named group of vessels you define. Group once, then subscribe to or read the whole group without listing members every time.
Subscription
A standing request to be told when something happens. Scope it to a vessel or a fleet, or to a set of zones and ports.
A fleet is a convenience layer. You can subscribe to a fleet exactly as you would to one vessel, and read its members, its composition and its recent events through Fleet Management. Not every endpoint takes a fleet yet: Vessel Positions rejects fleet_id, so pass the member IMOs instead.There are two kinds of subscription, and they are configured differently. A vessel subscription follows one ship or one fleet wherever it goes. A zone and port subscription watches a set of places and reports any vessel that moves through them. Notifications & Webhooks covers both.
A port is a type of zone. The two share one taxonomy and one identifier scheme, which is why Zone & Port Types lists them together.The read endpoints are shared as well. Zone and port questions go to the same reads under /zone-port-insights/v1/, and the identifier you pass decides which answer you get: a zone by ID and its UUID, a port by ID or UNLOCODE. Notifications are shared the same way. Zones & Ports lists the endpoints.A custom zone is always a zone. You can draw an area of water, but you cannot define a port.
Inbound vessels, berth traffic and custom zones carry the /zone-port-insights/ prefix all the same. The prefix tells you which service answers an endpoint. It does not tell you whether the endpoint covers both kinds of area.
Always, where you have it. Assigned by the International Maritime Organization and unchanged by renaming or reflagging
MMSI
9 digits
Working with raw AIS. Reassignable, so it is a weaker key than IMO
Callsign
Alphanumeric
Radio identification. Not a reliable primary key
Flag
Country code
The state of registration, which holds legal jurisdiction. All country codes, including flag, are ISO 3166-1 alpha-3 (three letters). The only two-letter code anywhere is the country prefix inside a UN/LOCODE, which is not a country code field itself.
Store the IMO, not the name
Vessel names change, flags change, MMSIs get reassigned. The IMO does not. Key your own records on anything else and you create a reconciliation problem later.
Any zone or port, including your custom zones. The only identifier the zone endpoints accept
UN/LOCODE
5 characters, such as NLRTM
Ports only. The United Nations code for a trade location, and the one most shipping systems already hold
id_type
ID or UNLOCODE
On port endpoints that take either, it says which of the two you are passing. A few endpoints spell it in lower case, so copy the value from the endpoint's reference
Berth ID
Identifier
A single berth inside a port, returned on berth traffic and Port Analytics
This distinction catches people out, and getting it wrong changes your numbers. A full call runs through six events, in this order:
Event
Means
PORT_AREA_ARRIVAL
The vessel entered the port's defined boundary
PORT_ARRIVAL
The vessel stopped inside that boundary
BERTH_ARRIVAL
The vessel arrived at a berth
BERTH_DEPARTURE
The vessel left the berth
PORT_DEPARTURE
The vessel started moving again inside the boundary
PORT_AREA_DEPARTURE
The vessel left the boundary
A call that berthed produces all six. A call that anchored without berthing produces the four port events and no berth pair. A vessel can also enter a port area and leave without ever "arriving". Do not assume the events arrive in pairs.Which ones you want depends on the question:
Calls: use port arrival and departure
Traffic or congestion: use the area events
Berth occupancy and time alongside: use the berth events
Zones outside ports have two events of their own, ZONE_ENTRY and ZONE_EXIT. A vessel can be inside several overlapping zones at once, so one movement can produce more than one event.
The four port events plus zone entry and exit, for one vessel
zone-and-port-traffic
The four port events for one port, or zone entry and exit for one zone
port-berth-traffic
The berth pair, for one port, each event carrying its berth
Each endpoint checks event types against its own set and rejects the rest, so asking zone-and-port-traffic for a berth event is an error, not an empty result. Port Insights and Voyage Insights cover the endpoints in detail.A zone and port subscription can deliver all eight movement events. It adds two that come from what a vessel reports rather than what we observe: NEW_INBOUND, when a vessel first names a watched port as its destination, and ETA_CHANGE, when an inbound vessel changes its ETA. See Zone & Port Notifications.
Two more terms sit alongside these. Congestion has no endpoint of its own: readers must fetch the snapshot and filter for stationary vessels themselves, since vessels-in-zone-or-port has no speed filter. Inbound vessels are the ships naming a port as their destination in AIS, which we parse against our port library. That is what vessels say, not what we observed, so it will not always agree with the event feeds.
Automatic Identification System, the transponder-based tracking system vessels broadcast on
Position source
Where a position came from: satellite (S_AIS) or terrestrial (T_AIS) AIS, other AIS feeds, SATCOMMS or LRIT. What you receive depends on your licence
AIS gap
A period with no AIS transmission, longer than a threshold you set. Sometimes coverage, sometimes deliberate
STS pairing
Ship-to-ship activity, two vessels alongside each other. The API calls it a pairing and types it as Cargo, Bunkering, Fishing or Unknown
Positional discrepancy
Positions that do not behave like a real track, such as the same point repeated for hours. Can indicate AIS spoofing. Voyage Insights lists the patterns we detect
Dark activity
Informal term for a period a vessel cannot be accounted for, usually an AIS gap in a context that matters
Gaps and discrepancies are signals, not verdicts
An AIS gap in poor-coverage water is unremarkable. The same gap off a sanctioned coast is not. These endpoints give you the observation; the risk judgement stays yours.
What the ship is built to do, such as a crude oil tanker. Each type rolls up into broader categories. See Vessel Types
Vessel class
A size band within a type, such as Handysize or Capesize. See Vessel Classes
Vessel status
Where the hull is in its life, from projected to scrapped. Not the same as navigational status. See Vessel Statuses
Navigational status
The vessel's own broadcast status, such as under way, at anchor or moored. Self-reported, so treat it as a claim and not an observation
Ownership roles
Registered owner, operator, technical manager, ship manager and group beneficial owner, which are often different companies
Gross tonnage (GT)
A measure of a vessel's total internal volume, not its weight. Used as a size filter on analytics endpoints
Deadweight (DWT)
How much weight a vessel can carry: cargo, fuel, stores and crew combined
Draught
How deep the hull sits in the water. A change usually means cargo was loaded or discharged, which is why draught change is a subscribable event
Laden / ballast
Carrying cargo, or sailing with tanks filled with water for stability instead
Flag state
The country of registration, responsible for the vessel's regulatory oversight
Port state control
Inspection of a foreign vessel in a national port, checking compliance with international rules. Detentions and deficiencies form part of a vessel's record
Estimated time of arrival, as reported by the vessel. Changes frequently, which is why it is a subscribable event
Destination
Free text typed aboard the vessel. We return it raw and, where we can, matched to a port and its UN/LOCODE
Bunkering
Taking on fuel. A recognised type of ship-to-ship pairing
Self-reported versus observed
Navigational status, destination and ETA are broadcast by the vessel. Positions, gaps and zone crossings are observed. When the two disagree, that gap is usually worth investigating.
Endpoints carry the version in the path, for example /notifications/v1/vessels. Most Insights endpoints are on v1. Fleet Management is on v2, with v1 still running for existing integrations.
We ship breaking changes as a new version, never as changes to the existing one
Deprecated means on its way out: marked in the documentation, with its replacement named, and kept running so integrations do not break unannounced
Legacy means superseded but supported, with no removal planned
Build against the latest version and plan for migration. No version runs forever. See Versioning & Deprecation.
Insights responses are JSON throughout, in snake_case, inside a meta and data envelope. We accept HTTPS only and do not process plain HTTP requests.Email notification digests are the one Insights exception: they attach a CSV of the events.
A call with a real key reaches production. The mock server, built from the contract, is the safe place to experiment. Testing & Sandbox shows how to switch to it.
PurpleTRAC, MTI, Weather and Podium were built separately from Insights, and each still carries its own host, authentication or conventions. We are moving them to the Insights API key scheme; until then, read each one's own pages.
