AIS Trail MCP Server

Everything known about one ship now: identity (name, IMO, call sign, flag, type, size), last position, speed, course, heading, navigational status, destination (port codes decoded) and ETA as given by the crew, how long ago it was heard, its track over the last 40 minutes, and the data sources to credit. flag (ISO code) and flag_country come from the MMSI: the flag of the radio licence, usually but not always the registry flag. dwt_estimate is an estimate from the AIS dimensions (tonnes, size class such as Panamax or VLCC, hull, draught used), not a registry value; null for tugs, pleasure craft and other types where deadweight does not apply. For archive records and sanctions flags, use lookup_vessels (API key).

Events of a ship between two times (UTC, ISO 8601), computed from the AIS Trail archive. from and to are optional: without to, now (24 hours ago on plans without live data); without from, 7 days before to (on Free, no earlier than the oldest day the plan includes), as on the REST endpoint. Give mmsi or imo (with imo, every MMSI that reported that IMO number in the range). Types: ENTER_ZONE and EXIT_ZONE (arrival at and departure from a port or anchorage; port_id for port_calls, zone port or anchorage), STATE_CHANGED (MOVING, NOT_MOVING, LONG_STOP), NAME_CHANGED, IMO_CHANGED, CALLSIGN_CHANGED, DESTINATION_CHANGED and DRAUGHT_CHANGED (old and new value); only when asked by name or with types ['all']: AIS_GAP (long AIS silence while under way; old_value hours, new_value nautical miles), ENCOUNTER (slow close approach to another ship outside port areas, a candidate ship-to-ship transfer; new_value the other ship's MMSI), FLAG_CHANGED (the IMO number reappears under an MMSI with another flag) and POSITION_JUMP (a physically impossible position jump). Rows: [time, event, old_value, new_value, lat, lon, mmsi, port_id, zone, sanctions, detail]; detail says more about behaviour events. The sanctions column gives the codes of the sanctions lists (OFAC, UK, EU) that name the ship's IMO number; informational only, not a compliance determination. Needs an AIS Trail API key sent by the MCP client as the HTTP header 'Authorization: Bearer ap_live_…'. At most 200 events per call and at most 31 days; the plan's history depth, credits (1 per event returned), rate limit and 24-hour delay (on plans without live data) apply.

Port calls of a ship between two times (UTC, ISO 8601), from the AIS Trail archive: port, arrival, departure, draught on arrival and departure, cargo estimate (loaded, ballast or unchanged, from the draught change), previous and next port. Give mmsi or imo. A port call starts when the ship stops for at least 15 minutes inside a port area and ends when it leaves; departure is null while it is still in port. The sanctions column gives the codes of the sanctions lists (OFAC, UK, EU) that name the ship's IMO number; informational only, not a compliance determination. Needs an AIS Trail API key sent by the MCP client as the HTTP header 'Authorization: Bearer ap_live_…'. At most 100 port calls per call and at most 366 days; the plan's history depth, credits (1 per port call returned), rate limit and 24-hour delay (on plans without live data) apply.

Where a ship has been between two times (UTC, ISO 8601), from the AIS Trail archive. Needs an AIS Trail API key sent by the MCP client as the HTTP header 'Authorization: Bearer ap_live_…' (keys at https://aistrail.com); clients that cannot add headers (OAuth-only web connectors) cannot use it yet. Resolution: raw (up to 24 h per call), 1m (up to 7 days) or 1h (up to 366 days); at most 200 points per call, as rows of [time, lat, lon, speed_kn, course_deg]. The plan's history depth, credits (as on the track endpoint: 1 per vessel-day) and rate limit apply, and the 24-hour delay on recent data on plans without live data. sources_through gives, per source, the time up to which the archive holds its data; pending_days lists days in the range a source has not delivered yet, so no points on those days does not mean the ship was absent.

Find ships by name (or part of it), MMSI (9 digits) or IMO number (7 digits). Returns live ships first, then ships out of range with their last known position (up to 7 days). List results are compact rows (mmsi, name, category, flag (ISO code from the MMSI), lat, lon, speed_kn, course_deg, length_m, destination, age_s, status, source); call get_vessel for full details of one ship. Private vessels (pleasure craft, sailing vessels and Class B transponders without a valid IMO number) are never listed or looked up individually; area and nearby results report how many were left out (private_vessels).

Ships heard in the last hour inside a box (at most 5° on each side), largest first. List results are compact rows (mmsi, name, category, flag (ISO code from the MMSI), lat, lon, speed_kn, course_deg, length_m, destination, age_s, status, source); call get_vessel for full details of one ship. Private vessels (pleasure craft, sailing vessels and Class B transponders without a valid IMO number) are never listed or looked up individually; area and nearby results report how many were left out (private_vessels).

Ships heard in the last hour within a radius (at most 50 nautical miles) of a point or of another ship, nearest first. List results are compact rows (mmsi, name, category, flag (ISO code from the MMSI), lat, lon, speed_kn, course_deg, length_m, destination, age_s, status, source); call get_vessel for full details of one ship. Private vessels (pleasure craft, sailing vessels and Class B transponders without a valid IMO number) are never listed or looked up individually; area and nearby results report how many were left out (private_vessels).

Find ports by name (or part of it), UN/LOCODE (e.g. NLRTM) or two-letter country code (e.g. NL) in the port reference (World Port Index and UN/LOCODE ports): id (for port_calls), name, country, UN/LOCODE, position, harbor size (World Port Index ports only) and the radius of the port area used to detect port calls. At most 20 ports, larger harbors first. No API key needed.

Ships that called at one port between two times (UTC, ISO 8601), from the AIS Trail archive: ship (with its flag from the MMSI), arrival, departure, draught on arrival and departure, cargo estimate, previous and next port. Get the port_id from find_port. event: any (in port at any time in the range, default), arrival or departure. The sanctions column gives the codes of the sanctions lists (OFAC, UK, EU) that name the ship's IMO number; informational only, not a compliance determination. Needs an AIS Trail API key sent by the MCP client as the HTTP header 'Authorization: Bearer ap_live_…'. At most 100 port calls per call and at most 366 days; the plan's rules and credits (1 per port call returned) apply as for vessel_port_calls.

How many ships are live now (live_ships_private: how many of them are private vessels, counted only), how many are known from the last 7 days, the date range of the history archive per source with available_until (the latest time vessel_track can return for that source on plans without live data), and the service status: ok or degraded, with reason codes in reasons.

Records of up to 20 ships at once from the AIS Trail archive, by mmsi and/or imo (lists): identity and particulars (name, IMO, call sign, type, flag from the MMSI, length, beam, estimated deadweight, first and last seen) and sanctions flags by IMO number from three official lists: OFAC SDN, UK Sanctions List and EU Regulation 833/2014 Annex XLII (list, programmes, date listed). An IMO number resolves to the MMSI that reported it last; ships not in the plan's sources come back with found false. Sanctions flags are informational, not a compliance determination: only ships a list names by IMO number are matched, ownership-based sanctions are not covered. Needs an AIS Trail API key sent by the MCP client as the HTTP header 'Authorization: Bearer ap_live_…'. Credits: 1 per ship returned (none for ships not found); the plan's sources and 24-hour delay (on plans without live data) apply.