Voyage event API: port calls and AIS gaps

Six endpoints that answer "what has this ship been doing?". Each one takes an IMO and a time window, and returns the events of one kind that fall inside it.

Six different services sit behind them. That is invisible to you: one key, one host, one response envelope, and largely the same window and paging parameters, with a few documented per-endpoint exceptions.

The six event families

Endpoint	Returns
`vessel-port-calls/{imo}`	Port and berth arrivals and departures
`vessel-zone-and-port-events/{imo}`	Zone entries and exits, plus port-area events
`vessel-ais-reporting-gaps/{imo}`	Periods where the vessel stopped transmitting
`vessel-sts-pairings/{imo}`	Ship-to-ship pairings, with type and duration
`vessel-positional-discrepancy/{imo}`	Positions that do not behave like a real track
`vessel-port-state-control/{imo}`	Inspections and detentions

All six live under https://api.polestar-production.com/voyage-insights/v1/.

What every call has in common

Learn the shape once and it holds across all six.

The IMO is in the path, and must be exactly seven digits.

timestamp_start is required. UTC, yyyy-MM-ddTHH:mm:ss, with an optional trailing Z. It cannot be in the future.

timestamp_end is optional and defaults to the time of the request, so omitting it means "up to now". We treat a value in the future as the current time rather than rejecting it.

limit and offset page the results. The default page is 100 and the ceiling is 500.

Windows are bounded by the data, not by the calendar

A window that reaches back further than our coverage for that vessel returns fewer events, not an error. An empty result means we recorded no events of that kind in that window. It does not mean the vessel was idle.

Port calls

Six event types, which together describe an approach, a stop and a departure:

Event	Means
`PORT_AREA_ARRIVAL`	The vessel enters the port area
`PORT_ARRIVAL`	The vessel has stopped inside the port area
`BERTH_ARRIVAL`	The vessel has arrived at the berth
`BERTH_DEPARTURE`	The vessel has left the berth
`PORT_DEPARTURE`	The vessel is moving again but still inside the port area
`PORT_AREA_DEPARTURE`	The vessel exits the port area

Filter with event_type, repeatable. You can also narrow by place: port_id (UUIDs), unlocode, country_code (three-letter codes) and sub_type are all repeatable on this endpoint.

A call that berthed produces all six. A call that anchored without berthing produces four. Do not assume the events arrive in pairs.

Zone & port events

The same port-area events as above, minus the berth pair, plus zone movement:

ZONE_ENTRY, the vessel enters the zone

ZONE_EXIT, the vessel exits the zone

Filter by types and sub_type for whole classes of zone, or by id for specific ones. The zone or port identifier is a query parameter called id here, not a path parameter, because the path already carries the IMO. Zone & Port Types lists the taxonomy both parameters accept.

A vessel can be inside several overlapping zones at once, so a single physical movement can generate more than one event.

AIS reporting gaps

A gap is a period where the vessel stopped transmitting for longer than a threshold you set with gap_threshold_gte, in hours. The minimum accepted threshold is 3. Below that, normal satellite coverage produces too much noise to be useful.

sort_by controls the sort direction applied to the gap end timestamp.

Ship-to-ship pairings

Filter with sts_type, whose values are case-insensitive and normalised, and with sts_duration_gte, a minimum pairing duration in hours. Only pairings at or above that duration are returned.

Positional discrepancies

Positions that do not behave like a real track. Four types are identified today:

Type	Pattern
Same position	The exact same location transmitted for the whole duration
Bounding box	Positions confined to a 50m by 50m area
Circle	A persistent circular pattern
MMSI outlier	Outlier positions suggesting MMSI spoofing

Narrow with event_types, repeatable or comma-separated, and duration_hours_gte.

timestamp_end is exclusive on this endpoint, where it is inclusive on the others.

Port state control

Inspections and detentions, with the inspecting authority, the port, the inspection type and, where one applies, the detention duration. sort_by applies to the inspection date.

timestamp_start here accepts two formats: an offset-qualified date-time, or the plain UTC form used by the other five endpoints.

These are signals, not verdicts

A reporting gap means a vessel stopped transmitting. It does not say why: equipment fails, and satellite coverage is imperfect. The same holds for pairings and discrepancies, which describe observed behaviour and not intent. Treat all three as inputs to your own risk model, and see Concepts & Terminology for what each event asserts.

Voyage Insights: Worked Examples

Gap, pairing and port-call queries end to end, with the responses.

Vessel Insights

Finding the IMO that every endpoint on this page needs.

Pagination & Filtering

How limit, offset and repeatable filters behave across the APIs.

Overview

The six event families#

What every call has in common#

Port calls#

Zone & port events#

AIS reporting gaps#

Ship-to-ship pairings#

Positional discrepancies#

Port state control#

Related#