Vessel Positions
The two endpoints
| Endpoint | Answers |
|---|---|
POST /v1/latest | Where are these vessels, or what is in this area, right now? |
POST /v1/historical | Where has this vessel been, between these two times? |
These endpoints sit behind a base path of their own
/meridia-voyage-intelligence. Call it at https://api.polestar-production.com/meridia-voyage-intelligence/v1/latest and /v1/historical. The reference pages show the full path including this prefix.Both are reads, despite the verb
Latest known positions
POST /v1/latest returns the most recent position for each matching vessel. Send at least one of vessel or geographic_filter.voyage_last_location block: position, timestamp, source, speed, course, heading, navigational status, draught, and the destination the vessel reported. matched_destination is our reading of that free text against the port library, so you get a port name and UN/LOCODE alongside the raw_destination string the crew typed.The lookback window is set by us, not by you
geographic_filter we look back 3 hours; without one we look back 31 days. An area search therefore answers "what is here now", and an identifier search answers "where was this vessel last seen", even though both are the same call. A vessel silent for longer than the window is absent from the response rather than returned with a stale position.Historical tracks
POST /v1/historical returns positions for one vessel, or for an area, across a time window. Both timestamps are required.voyages array of positions in the same shape latest uses for its single reading. The window may not exceed 731 days, and neither bound may be in the future.downsampling_frequency thins the track to one position every N minutes. A year of a busy vessel at full resolution is a large response and usually more detail than a map needs.The identifier fields are not the same on both endpoints
/v1/latest | /v1/historical | |
|---|---|---|
| By IMO | imo_numbers, an array | imo_number, a single value |
| By MMSI | mmsi_numbers, an array | mmsi, a single value |
latest is a batch endpoint and takes lists; historical builds one track and takes one vessel. Set exactly one of the identifier fields in either case.fleet_id exists on the wire and is rejected
fleet_id, and both reject it with a 400 and ERROR_152. Fleet filtering is not supported on these endpoints yet. Read the fleet's membership with Fleet Management and pass the IMO numbers to /v1/latest instead.Searching an area
geographic_filter takes exactly one of circle or polygon. Sending both, or an empty object, is a 400 with ERROR_146.latitude, longitude and radius together, and the radius is in metres, between 100 and 50,000. A polygon is an array of [longitude, latitude] pairs, longitude first, with at least three points. We close the ring for you if the first and last points differ.Narrowing the result
sources restricts the position sources we draw from: S_AIS and T_AIS for satellite and terrestrial AIS, R_AIS, PT_AIS, SATCOMMS and LRIT. Sources you are not licensed for are ignored rather than rejected, so listing one you do not hold changes nothingspeed_min and speed_max bound speed over ground in knots. An upper bound is how you separate vessels at anchor or alongside from traffic under wayPaging
latest uses limit and offset. historical uses an opaque cursor: read meta.next_cursor from a response and send it back as cursor on the next call. Keep requesting until next_cursor comes back empty rather than counting against total_count.Related
Modified at 2026-10-02 14:00:21