Voyage Insights examples | Pole Star APIs

Six questions a compliance or operations team asks, each answered with one call. Every example uses a real vessel and a window known to contain the events it illustrates.

The windows are historical on purpose. Reuse the shape, not the dates.

A port call timeline

Question: where did this vessel call during December 2024?

Use zone and port events instead of port calls when you want arrivals and departures without the berth detail cluttering the timeline.

sub_type=Port is doing real work here. Without it you also get arrivals and departures for anchorage areas, which are port-type zones but not port calls. The types=Ports filter is redundant once you have asked for PORT_ARRIVAL and PORT_DEPARTURE, since those event types only occur on ports.

Has it entered a war risk zone?

Question: has this vessel entered a JWC War Zone in the last 90 days?

Two things to copy from this one. timestamp_end is omitted, so the window runs to the moment of the request. For a rolling "last 90 days" check, only the start date needs computing. Filtering by types instead of by zone ID also saves you enumerating the zones first, or maintaining that list as it changes. Zone & Port Types lists the type names this parameter accepts.

How often did it go dark?

Question: how many AIS gaps of six hours or more did this vessel have in 2024?

Each event carries a stopped block and a resumed block, with position, course, speed, draught and navigational status at both ends:

{
  "event_id": "f3f776bf-9ea1-427e-b8c8-525978477192",
  "gap_duration_hours": 40.59,
  "draught_change": 0.0,
  "stopped": {
    "latitude": 43.943417,
    "longitude": 135.47728,
    "draught": 4.8,
    "navigational_status": { "status": "AT ANCHOR", "code": "2" },
    "timestamp": "2024-12-26T12:11:35Z"
  },
  "resumed": { "...": "same shape" }
}

A gap that is still open returns a null resumed block

If the vessel has not started transmitting again, every field inside resumed is null, including timestamp, while gap_duration_hours counts from stopped to now. Check for a null resumed.timestamp before treating a gap as finished, or an ongoing gap will look like a completed one of the same length.

draught_change is the field worth watching. A vessel that went dark and resumed at a materially different draught moved cargo while it was not transmitting.

Ship-to-ship cargo transfers

Question: how many STS cargo transfers did this vessel take part in during 2024?

sts_duration_gte is in hours and filters on the pairing duration. Setting it to 1 removes the brief proximity events that are two vessels passing, not transferring. Raise it if you only care about transfers long enough to move a meaningful volume.

Signs of position spoofing

Question: did this vessel report positions that do not add up in the second half of 2024?

With no event_types filter you get all four discrepancy patterns. Add the filter when you are looking for one in particular. A stationary transmitter reporting the same coordinates for days is a different problem from positions scattered outside a plausible track.

Remember that timestamp_end is exclusive on this endpoint and inclusive on the other five.

Inspection history

Question: what port state control inspections and detentions does this vessel have on record for 2024?

The response carries the inspecting authority, the port, the inspection type and the detention duration where one applies. Inspection records arrive from the regional port state control regimes, so an inspection appears once the relevant authority has published it, not on the day it happened.

Putting them together

A single-vessel risk picture is these six calls against the same IMO and the same window, merged on your side:

Resolve the identifier first

Everything here is IMO-keyed. Vessel Insights turns a name or MMSI into one.

Run the six event queries over one window

They are independent, so issue them in parallel. Use the same timestamp_start for all six so the results line up.

Merge on time, not on event ID

Event IDs are unique per family and are not comparable across them. A gap that starts where an STS pairing starts is the correlation that matters, and timestamps are what reveal it.

Subscribe instead of polling this

Running these six calls on a schedule to spot new events is the pattern Vessel Notifications exists to replace. One subscription covers all of these event types, for one vessel or a whole fleet, and delivers by webhook or email digest.

To look back across a whole fleet instead of one vessel, Fleet Management lists recent events for every member in one call.

Voyage Insights

The six endpoints, their filters and the parameters they share.

Vessel Notifications: Worked Examples

The same events, pushed to you instead of polled.

Errors & Status Codes

What a rejected window or a malformed IMO comes back as.

Worked Examples

A port call timeline#

Has it entered a war risk zone?#

How often did it go dark?#

Ship-to-ship cargo transfers#

Signs of position spoofing#

Inspection history#

Putting them together#

Related#