{"openapi": "3.1.0", "info": {"title": "AIS Trail API", "version": "1.7.0", "description": "Normalized historical AIS vessel positions from public authorities and community receiver networks, with coastal coverage worldwide: vessel search, tracks by MMSI or IMO, and historical area queries, as JSON, GeoJSON, CSV or Excel; port calls by vessel, IMO or port and across ports, and vessel events, as JSON, CSV or Excel. Live positions come with the Pro and Business plans.\n\nUsage is measured in credits. Each plan includes monthly credits; they renew every billing period (every calendar month, UTC, on Free) and are used first, then credit packs, starting with the pack that expires soonest. Credits per response:\n- Historical track: 1 credit per vessel-day: all positions of one vessel on one UTC day\n- Area query: 1 credit per distinct vessel-day in the rows returned\n- Vessel details, batch, IMO lookup, search: 1 credit per vessel returned\n- Port calls: 1 credit per port-call record\n- Vessel events: 1 credit per event record\n- Live position (REST): 1 credit per vessel returned\n- Live WebSocket stream: Included in Pro and Business, no credits\n- Status, sources, usage, docs: Free\n\nEmpty results and errors (4xx, 5xx) use no credits. Credits are taken after a successful response; responses that are already running when the balance reaches zero still complete, so the balance can go below zero by at most one page per response. A page of a track continues the vessel-days of the previous page without charging them again; area queries count vessel-days per page. Metered responses carry X-Credits-Used and X-Credits-Remaining. When no credits are left, metered endpoints answer 402 (Out of credits) before running the query, with credits_reset_at and pricing_url. GET /v1/usage shows plan credits, credit packs with their expiry and the credits used this period.\n\nThe most recent 24 hours are not available on the history endpoints (embargo) unless your plan includes live data (Pro and Business), which also opens the live endpoints.\n\nPlans:\n- **Free** (`free`, $0/month): 500 credits/month, 1 request/s, last 7 days of history, area queries not included, up to 1,000 rows per page, no live data (24-hour delay)\n- **Starter** (`starter`, $29/month or $290/year): 15,000 credits/month, 5 requests/s, last 12 months of history, area queries up to 2\u00b0 x 2\u00b0, up to 50,000 rows per page, no live data (24-hour delay)\n- **Pro** (`pro`, $129/month or $1,290/year): 60,000 credits/month, 10 requests/s, last 12 months of history, area queries up to 2\u00b0 x 2\u00b0, up to 50,000 rows per page, live data with 2 concurrent WebSocket connections per account and no 24-hour delay\n- **Business** (`business`, $249/month or $2,490/year): 250,000 credits/month, 20 requests/s, last 12 months of history, area queries up to 10\u00b0 x 10\u00b0, up to 50,000 rows per page, live data with 5 concurrent WebSocket connections per account and no 24-hour delay\n- **Credit pack** ($49, one-time, any plan including Free): 20,000 credits, valid for 12 months; packs stack\n\nLive endpoints (Pro and Business plans): GET /v1/positions, GET /v1/vessels/{mmsi}/position and the WebSocket /v1/stream serve the latest positions from `aisstream`, `barentswatch`, `digitraffic`, `openwaters` only, the customer-licensed live sources; positions and static data (name, destination) from other sources are never merged in. Live responses carry meta.sources, meta.private_vessels, meta.attribution and meta.notice; the stream's subscribed message carries the same fields. Live HTTP positions use 1 credit per vessel returned; the WebSocket stream is included in the plan and uses no credits. The concurrent connection limit applies per account. While the live view is starting, the live endpoints answer 503 with Retry-After; when it is not current they serve the last known state with X-Live-Status: stale and X-Live-Stale-S. History stays limited to the customer sources and reaches the newest minutes only after the archive's next write (about every 5 minutes); use the live endpoints for the latest positions.\n\nOne query may span at most: raw 24 h, 1m 7 days, 1h 366 days. Longer ranges: split them. Results are paged with an opaque cursor; a page may hold fewer rows than limit, keep following next_cursor until complete is true.\n\nPort calls are detected from the archive every night: a call starts when a vessel stops (speed under 1 knot) for at least 15 minutes inside a port area and ends when it leaves the area. Ports come from the World Port Index and UN/LOCODE (/v1/ports); a port area is a circle sized by harbor size, and where areas overlap the nearest port wins. Port calls follow the same plan, embargo, source and private vessel rules as the other history endpoints; searching port calls across ports (/v1/port-calls) is included in the Starter, Pro and Business plans. meta.calls_through gives, per source, the time up to which port calls are built.\n\nAt most 2 requests per key are processed at a time (429 otherwise). A query that runs longer than the server limit is stopped with 503; narrow the box or the time range. Errors are RFC 9457 problem details.\n\nSources: `aisstream`, `barentswatch`, `digitraffic`, `dma`, `noaa`, `openwaters`. Attribution is required when you redistribute data. Source names, licences and the attribution texts are at /v1/sources and on [the sources page](https://aistrail.com/docs/sources/).\n\nEvery data response carries the attribution of the sources it was built from in meta.attribution (track, area, search, vessel, IMO and port call responses, GeoJSON included; the X-Attribution header for CSV). Search results and IMO matches list their sources per row; vessel observations name theirs. Port call and port responses also credit the World Port Index (`wpi`), the source of port names and positions.\n\nVessel particulars we derive ourselves, at no extra credit cost: search results, the vessel lookup and IMO matches carry flag (ISO 3166-1 alpha-2 code and name from the MMSI's Maritime Identification Digits, ITU MID table) and dwt_estimate (deadweight and size class estimated from the AIS length, beam and deepest reported draught). Track, area and port call rows carry the flag code. The MMSI flag is the flag of the station licence: usually, but not always, the registry flag. dwt_estimate is an estimate, not a registry value, and is null where deadweight does not apply.\n\nSanctions lists, at no extra credit cost: the vessel lookup (current IMO) and the IMO lookup carry sanctions, the official lists that name the IMO number (OFAC: the OFAC SDN List; UK: the UK Sanctions List; EU: Annex XLII of Council Regulation (EU) No 833/2014), with programme and listing date; the IMO track carries it in meta.sanctions. Search, port call and event rows carry the list codes. meta.sanctions_lists gives each list's publication date; lists are refreshed nightly. Informational only, not a compliance determination: only vessels named by IMO number are matched (no ownership-based or indirect designations); see [Sanctions lists](https://aistrail.com/docs/#sanctions).\n\nNot for navigation. AIS data can be missing, delayed or wrong; do not use it for navigation, collision avoidance, search and rescue or any other safety-of-life purpose. Every data response repeats this in meta.notice and the X-Notice header.\n\nSources arrive on different schedules: `dma` publishes each day a few days later, the live sources (`aisstream`, `barentswatch`, `digitraffic`, `openwaters`) are collected continuously, `noaa` is a historical archive published by the source months later and loaded a year at a time. meta.sources_through gives, per source, the time up to which the archive holds its data; meta.pending_days lists days in your window that a source has not delivered yet (never for `noaa`: days after the end of its archive are outside its coverage) and meta.missing_days days without data before that (failed loads or collection gaps). Days a source never published are in meta.unavailable_days. meta.data_complete is false when pending_days or missing_days is not empty; complete refers to paging only. CSV: X-Data-Through and X-Data-Complete headers. Per source available_until is in /v1/sources.\n\nPrivate vessels (pleasure craft, sailing vessels and Class B transponders without a valid IMO number) and MMSIs withdrawn at their owner's request are not served. Track and area results leave them out, search skips them, and the vessel and IMO lookups and the live position of one vessel answer 404 with the same detail as for a vessel never seen, so a response does not reveal that a vessel is private. Live positions and the stream leave them out as well. meta.private_vessels (excluded or included) says whether private vessels are part of a response for your account. Business accounts can request access to them for a declared purpose by writing to hello@aistrail.com; every response that returns one is logged (on the stream once per connection, vessel and UTC day), and /v1/usage shows the account's access (private_vessels). Withdrawn MMSIs stay out on every plan, with or without access."}, "servers": [{"url": "https://api.aistrail.com"}], "components": {"securitySchemes": {"bearer": {"type": "http", "scheme": "bearer", "description": "API key ap_live_\u2026"}}, "schemas": {"Position": {"type": "object", "properties": {"mmsi": {"type": "integer"}, "ts": {"type": "string", "format": "date-time", "description": "Message timestamp (UTC) as reported by the source"}, "lat": {"type": "number"}, "lon": {"type": "number"}, "sog": {"type": ["number", "null"], "description": "Speed over ground, knots"}, "cog": {"type": ["number", "null"], "description": "Course over ground, degrees"}, "heading": {"type": ["integer", "null"], "description": "True heading, degrees; null if unavailable (raw 511)"}, "nav_status": {"type": ["integer", "null"], "description": "ITU-R M.1371 navigational status 0-14"}, "source": {"type": "string", "description": "Data source id, see /v1/sources"}, "flags": {"type": ["string", "null"], "description": "Quality flag, e.g. implausible_jump (kept, never dropped)"}, "flag": {"type": ["string", "null"], "description": "Flag of the vessel: ISO 3166-1 alpha-2 code derived from the MMSI (see Vessel particulars); null when the MMSI is not a ship station or its MID is not allocated"}, "imo": {"type": ["integer", "null"], "description": "IMO number; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "name": {"type": ["string", "null"], "description": "Vessel name; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "callsign": {"type": ["string", "null"], "description": "Call sign; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "ship_type": {"type": ["integer", "null"], "description": "AIS ship type code; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "length_m": {"type": ["number", "null"], "description": "Length, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "width_m": {"type": ["number", "null"], "description": "Beam, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "draught_m": {"type": ["number", "null"], "description": "Draught, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "destination": {"type": ["string", "null"], "description": "Destination as broadcast; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "eta": {"type": ["string", "null"], "format": "date-time", "description": "ETA as broadcast (UTC); with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "dim_a": {"type": ["integer", "null"], "description": "AIS dimension A: GPS antenna to bow, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "dim_b": {"type": ["integer", "null"], "description": "AIS dimension B: GPS antenna to stern, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "dim_c": {"type": ["integer", "null"], "description": "AIS dimension C: GPS antenna to port side, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "dim_d": {"type": ["integer", "null"], "description": "AIS dimension D: GPS antenna to starboard side, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}}}, "PageMeta": {"type": "object", "properties": {"from": {"type": "string", "format": "date-time"}, "to": {"type": "string", "format": "date-time"}, "resolution": {"type": "string", "enum": ["raw", "1m", "1h"]}, "count": {"type": "integer"}, "complete": {"type": "boolean", "description": "true when there are no more pages (paging only; see data_complete)"}, "next_cursor": {"type": ["string", "null"], "description": "Pass as ?cursor= to get the next page"}, "next": {"type": ["string", "null"], "description": "Relative URL of the next page"}, "embargo_cutoff": {"type": ["string", "null"], "format": "date-time", "description": "Data newer than this is not available on your plan (null on plans with live data)"}, "include": {"type": "string", "enum": ["static", "none"], "description": "Whether rows carry static data (the include parameter, or its default for the format)"}, "sources_through": {"type": "object", "additionalProperties": {"type": ["string", "null"], "format": "date-time"}, "description": "Per source: the archive holds this source's data up to this time, never later than embargo_cutoff (null: no data yet)"}, "pending_days": {"type": "object", "additionalProperties": {"type": "array", "items": {"type": "string", "format": "date"}}, "description": "Per source: UTC days in this window the source has not delivered yet (at most 100)"}, "missing_days": {"type": "object", "additionalProperties": {"type": "array", "items": {"type": "string", "format": "date"}}, "description": "Per source: UTC days in this window up to sources_through without data (at most 100)"}, "unavailable_days": {"type": "object", "additionalProperties": {"type": "array", "items": {"type": "string", "format": "date"}}, "description": "Per source: UTC days in this window the source never published; they will not arrive and do not count against data_complete (at most 100)"}, "data_complete": {"type": "boolean", "description": "false when pending_days or missing_days is not empty for any source"}, "private_vessels": {"type": "string", "enum": ["excluded", "included"], "description": "Whether private vessels are part of this response for your account"}, "attribution": {"type": "array", "items": {"type": "object"}, "description": "Required attribution for the sources in this response"}, "sanctions": {"type": "array", "items": {"$ref": "#/components/schemas/SanctionListing"}, "description": "IMO track only: official sanctions lists that name this IMO number"}, "sanctions_lists": {"$ref": "#/components/schemas/SanctionsLists"}, "notice": {"type": "string", "description": "Not-for-navigation notice (also in the X-Notice header)"}}}, "ResponseMeta": {"type": "object", "properties": {"embargo_cutoff": {"type": ["string", "null"], "format": "date-time", "description": "Data newer than this is not available on your plan (null on plans with live data)"}, "sources_through": {"type": "object", "additionalProperties": {"type": ["string", "null"], "format": "date-time"}, "description": "Per source: the archive holds this source's data up to this time, never later than embargo_cutoff (null: no data yet)"}, "private_vessels": {"type": "string", "enum": ["excluded", "included"], "description": "Whether private vessels are part of this response for your account"}, "attribution": {"type": "array", "items": {"type": "object"}, "description": "Required attribution for the sources in this response"}, "sanctions_lists": {"$ref": "#/components/schemas/SanctionsLists"}, "notice": {"type": "string", "description": "Not-for-navigation notice (also in the X-Notice header)"}}}, "Flag": {"type": ["object", "null"], "description": "Flag derived from the MMSI's Maritime Identification Digits (ITU MID table). It is the flag of the ship station licence: usually, but not always, the registry flag. null when the MMSI is not a ship station (coast stations, SAR aircraft, AIS-SART/MOB/EPIRB, aids to navigation, handhelds) or its MID is not allocated.", "properties": {"code": {"type": "string", "description": "ISO 3166-1 alpha-2 country or territory code"}, "name": {"type": "string", "description": "English short name"}, "source": {"type": "string", "enum": ["mmsi"]}}}, "DwtEstimate": {"type": ["object", "null"], "description": "Estimated deadweight from AIS dimensions, not a registry value: tonnes = k x length x beam x draught, with k per hull (block coefficient, waterline length and lightship share folded into one factor) calibrated on vessels with published deadweight. null for implausible dimensions and for ship types where deadweight does not apply or the hull is unknown (tugs, pilot, search and rescue, port and law enforcement craft, military, sailing and pleasure craft, high speed craft, other and unknown types).", "properties": {"tonnes": {"type": "integer", "description": "Estimated deadweight, metric tonnes, rounded to 3 significant digits"}, "class": {"type": ["string", "null"], "enum": ["Handysize", "MR", "Panamax", "Aframax", "Suezmax", "VLCC", "ULCC", "Handymax", "Supramax", "Ultramax", "Post-Panamax", "Capesize", "VLOC", "Feeder", "New Panamax", "ULCV", null], "description": "Industry size class: by estimated deadweight for tankers and bulk carriers, by dimensions for container ships; null for passenger and fishing vessels and below 10,000 t"}, "hull": {"type": "string", "enum": ["tanker", "bulk", "container", "passenger", "fishing"], "description": "Hull family used; for AIS cargo types bulk (dry bulk and general cargo) or container is inferred from the dimensions"}, "draught_m": {"type": "number", "description": "Draught used, metres"}, "draught_source": {"type": "string", "enum": ["ais_max", "typical"], "description": "ais_max: the deepest draught the vessel has reported; typical: none reported, or too shallow to be a loaded draught, so a typical draught for the beam"}, "method": {"type": "string", "enum": ["dimensions"]}, "note": {"type": "string"}}}, "VesselSummary": {"type": "object", "properties": {"mmsi": {"type": "integer"}, "name": {"type": ["string", "null"]}, "imo": {"type": ["integer", "null"]}, "callsign": {"type": ["string", "null"]}, "ship_type": {"type": ["integer", "null"]}, "length_m": {"type": ["number", "null"]}, "last_seen": {"type": "string", "format": "date-time"}, "sources": {"type": "array", "items": {"type": "string"}}, "flag": {"$ref": "#/components/schemas/Flag"}, "dwt_estimate": {"$ref": "#/components/schemas/DwtEstimate"}, "sanctions": {"type": "array", "items": {"type": "string", "enum": ["OFAC", "UK", "EU"]}, "description": "Sanctions lists that name this row's IMO number (empty when none; CSV: joined with |). Informational, not a compliance determination: see Sanctions lists in the docs"}}}, "Vessel": {"type": "object", "properties": {"mmsi": {"type": "integer"}, "current": {"type": "object", "description": "Latest known imo, name, callsign, ship_type, length_m, width_m, draught_m, destination, eta"}, "first_seen": {"type": ["string", "null"], "format": "date-time"}, "last_seen": {"type": ["string", "null"], "format": "date-time"}, "observations": {"type": "array", "items": {"type": "object"}, "description": "Distinct static reports, newest first (at most 50)"}, "flag": {"$ref": "#/components/schemas/Flag"}, "dwt_estimate": {"$ref": "#/components/schemas/DwtEstimate"}, "sanctions": {"type": "array", "items": {"$ref": "#/components/schemas/SanctionListing"}, "description": "Official sanctions lists that name the current IMO number (empty when none or no IMO)"}, "live_position": {"description": "Latest live position (a LivePosition) on plans with live data (Pro and Business), otherwise null"}}}, "SanctionListing": {"type": "object", "description": "One official sanctions list naming the vessel by IMO number", "properties": {"list": {"type": "string", "enum": ["OFAC", "UK", "EU"], "description": "OFAC: the OFAC SDN List; UK: the UK Sanctions List; EU: Annex XLII of Council Regulation (EU) No 833/2014 (vessels under the Article 3s port and services ban)"}, "programmes": {"type": "array", "items": {"type": "string"}, "description": "Sanctions programmes or regimes as written on the list"}, "listed": {"type": ["string", "null"], "format": "date", "description": "Date the vessel was designated, as published on the list"}, "name": {"type": ["string", "null"], "description": "Vessel name on the list"}, "ref": {"type": ["string", "null"], "description": "The list's own identifier for the entry"}}}, "SanctionsLists": {"type": "object", "description": "The sanctions lists checked for this response: per list its publication date, when AIS Trail fetched it and how many vessels it names (stale: the last fetch failed, the previous copy is used), plus a note", "properties": {"lists": {"type": "object", "additionalProperties": {"type": "object", "properties": {"name": {"type": "string"}, "published": {"type": ["string", "null"], "format": "date"}, "fetched_at": {"type": ["string", "null"], "format": "date-time"}, "vessels": {"type": ["integer", "null"]}, "stale": {"type": "boolean"}}}}, "note": {"type": "string"}}}, "BatchVessel": {"type": "object", "properties": {"query": {"type": "object", "description": "The identifier asked for: {\"mmsi\": \u2026} or {\"imo\": \u2026}"}, "mmsi": {"type": "integer"}, "imo": {"type": ["integer", "null"]}, "name": {"type": ["string", "null"]}, "callsign": {"type": ["string", "null"]}, "ship_type": {"type": ["integer", "null"]}, "length_m": {"type": ["number", "null"]}, "width_m": {"type": ["number", "null"]}, "draught_m": {"type": ["number", "null"]}, "destination": {"type": ["string", "null"]}, "eta": {"type": ["string", "null"], "format": "date-time"}, "first_seen": {"type": "string", "format": "date-time"}, "last_seen": {"type": "string", "format": "date-time"}, "sources": {"type": "array", "items": {"type": "string"}}, "flag": {"$ref": "#/components/schemas/Flag"}, "dwt_estimate": {"$ref": "#/components/schemas/DwtEstimate"}, "sanctions": {"type": "array", "items": {"$ref": "#/components/schemas/SanctionListing"}, "description": "Official sanctions lists that name the card's current IMO number and, for an IMO query, the IMO number asked for (empty when none)"}}}, "ImoMatch": {"type": "object", "properties": {"mmsi": {"type": "integer"}, "first_seen": {"type": "string", "format": "date-time"}, "last_seen": {"type": "string", "format": "date-time"}, "name": {"type": ["string", "null"]}, "callsign": {"type": ["string", "null"]}, "sources": {"type": "array", "items": {"type": "string"}}, "flag": {"$ref": "#/components/schemas/Flag", "description": "Flag of this MMSI: a change of MMSI usually means a change of flag"}, "dwt_estimate": {"$ref": "#/components/schemas/DwtEstimate"}}}, "LivePosition": {"type": "object", "properties": {"mmsi": {"type": "integer"}, "ts": {"type": "string", "format": "date-time", "description": "Message timestamp (UTC) as reported by the source"}, "lat": {"type": "number"}, "lon": {"type": "number"}, "sog": {"type": ["number", "null"], "description": "Speed over ground, knots"}, "cog": {"type": ["number", "null"], "description": "Course over ground, degrees"}, "heading": {"type": ["integer", "null"], "description": "True heading, degrees; null if unavailable (raw 511)"}, "nav_status": {"type": ["integer", "null"], "description": "ITU-R M.1371 navigational status 0-14"}, "source": {"type": "string", "description": "Data source id, see /v1/sources"}, "flags": {"type": ["string", "null"], "description": "Quality flag, e.g. implausible_jump (kept, never dropped)"}, "imo": {"type": ["integer", "null"]}, "name": {"type": ["string", "null"]}, "callsign": {"type": ["string", "null"], "description": "Call sign; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "ship_type": {"type": ["integer", "null"]}, "length_m": {"type": ["number", "null"]}, "width_m": {"type": ["number", "null"]}, "draught_m": {"type": ["number", "null"]}, "destination": {"type": ["string", "null"], "description": "Destination as declared by the vessel"}, "eta": {"type": ["string", "null"], "format": "date-time", "description": "ETA as declared by the vessel"}, "dim_a": {"type": ["integer", "null"], "description": "AIS dimension A: GPS antenna to bow, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "dim_b": {"type": ["integer", "null"], "description": "AIS dimension B: GPS antenna to stern, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "dim_c": {"type": ["integer", "null"], "description": "AIS dimension C: GPS antenna to port side, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "dim_d": {"type": ["integer", "null"], "description": "AIS dimension D: GPS antenna to starboard side, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "rot": {"type": ["number", "null"], "description": "Rate of turn, degrees per minute"}, "ais_class": {"type": ["string", "null"], "description": "AIS transponder class, A or B"}, "age_s": {"type": "number", "description": "Seconds since ts"}, "received_at": {"type": "string", "format": "date-time", "description": "When AIS Trail received the position"}}}, "LiveMeta": {"type": "object", "properties": {"sources": {"description": "Source ids the live endpoints serve on your plan", "oneOf": [{"type": "array", "items": {"type": "string"}}, {"type": "string", "enum": ["all"]}]}, "private_vessels": {"type": "string", "enum": ["excluded", "included"], "description": "Whether private vessels are part of this response for your account"}, "attribution": {"type": "array", "items": {"type": "object"}, "description": "Required attribution for the sources in this response"}, "notice": {"type": "string", "description": "Not-for-navigation notice (also in the X-Notice header)"}}}, "Port": {"type": "object", "properties": {"id": {"type": "integer", "description": "Port id: the World Port Index number for WPI ports; ports listed only in UN/LOCODE have ids from 10,000,000"}, "name": {"type": "string"}, "alternate_names": {"type": "array", "items": {"type": "string"}}, "country": {"type": ["string", "null"], "description": "ISO 3166-1 alpha-2 country code"}, "locode": {"type": ["string", "null"], "description": "UN/LOCODE, e.g. NLRTM"}, "lat": {"type": "number"}, "lon": {"type": "number"}, "harbor_size": {"type": ["string", "null"], "enum": ["Large", "Medium", "Small", "Very Small", null]}, "harbor_type": {"type": ["string", "null"]}, "radius_km": {"type": "number", "description": "Radius of the port area used for port call detection"}}}, "PortCall": {"type": "object", "properties": {"mmsi": {"type": "integer"}, "imo": {"type": ["integer", "null"], "description": "IMO number reported at arrival; otherwise filled from one consistent report of the same MMSI within 30 days, preferring a report with the vessel's name and then the closest in time (all filled fields from the same report); left empty when the MMSI is ambiguous"}, "name": {"type": ["string", "null"], "description": "Vessel name reported at arrival; otherwise filled from one consistent report of the same MMSI within 30 days, preferring a report with the vessel's name and then the closest in time (all filled fields from the same report); left empty when the MMSI is ambiguous"}, "ship_type": {"type": ["integer", "null"], "description": "AIS ship type reported at arrival; otherwise filled from one consistent report of the same MMSI within 30 days, preferring a report with the vessel's name and then the closest in time (all filled fields from the same report); left empty when the MMSI is ambiguous"}, "flag": {"type": ["string", "null"], "description": "ISO 3166-1 alpha-2 flag code derived from the MMSI"}, "port": {"type": ["object", "null"], "properties": {"id": {"type": "integer", "description": "Port id: the World Port Index number for WPI ports; ports listed only in UN/LOCODE have ids from 10,000,000"}, "name": {"type": "string"}, "country": {"type": ["string", "null"], "description": "ISO 3166-1 alpha-2 country code"}, "locode": {"type": ["string", "null"], "description": "UN/LOCODE, e.g. NLRTM"}}}, "arrival": {"type": "string", "format": "date-time", "description": "Start of the first stop of at least 15 minutes inside the port area"}, "departure": {"type": ["string", "null"], "format": "date-time", "description": "Last position inside the port area before the vessel left; null while it is still in port (or after embargo_cutoff)"}, "duration_s": {"type": ["integer", "null"], "description": "departure minus arrival, seconds"}, "draught_arrival_m": {"type": ["number", "null"], "description": "Draught reported at arrival, metres"}, "draught_departure_m": {"type": ["number", "null"], "description": "Draught reported at departure, metres"}, "draught_change_m": {"type": ["number", "null"]}, "cargo_estimate": {"type": ["string", "null"], "enum": ["loaded", "ballast", "unchanged", null], "description": "From the draught change: loaded (deeper by 0.3 m or more), ballast (shallower by 0.3 m or more), unchanged; null when a draught is unknown"}, "previous_port": {"type": ["object", "null"], "description": "The vessel's previous port call (id, name, country, locode, departure), at most 30 days before arrival; null when unknown"}, "next_port": {"type": ["object", "null"], "description": "The vessel's next port call (id, name, country, locode, arrival), at most 30 days after departure; null when unknown"}, "zone": {"type": "string", "enum": ["port", "anchorage"], "description": "port: a call inside the port area; anchorage: a wait at the port's anchorage (zones)"}, "sources": {"type": "array", "items": {"type": "string"}, "description": "Data sources the port call was detected in. pelyr: detected from positions of a source the API does not serve otherwise (see the sources page); imo, name, ship_type and draughts never come from it, and meta.attribution then carries its credit"}, "sanctions": {"type": "array", "items": {"type": "string", "enum": ["OFAC", "UK", "EU"]}, "description": "Sanctions lists that name this row's IMO number (empty when none; CSV: joined with |). Informational, not a compliance determination: see Sanctions lists in the docs"}}}, "PortCallEvent": {"type": "object", "description": "layout=events: the port call as zone events, like a port-calls report (ENTER_ZONE at arrival, EXIT_ZONE at departure)", "properties": {"mmsi": {"type": "integer"}, "imo": {"type": ["integer", "null"]}, "name": {"type": ["string", "null"]}, "ship_type": {"type": ["integer", "null"]}, "flag": {"type": ["string", "null"]}, "event": {"type": "string", "enum": ["ENTER_ZONE", "EXIT_ZONE"]}, "ts": {"type": "string", "format": "date-time", "description": "arrival (ENTER_ZONE) or departure (EXIT_ZONE)"}, "draught_m": {"type": ["number", "null"], "description": "Draught reported at arrival or departure"}, "port": {"type": "object", "description": "id, name, country, locode; for an anchorage the name ends in ' Anch.'"}, "zone": {"type": "string", "enum": ["port", "anchorage"]}, "sanctions": {"type": "array", "items": {"type": "string", "enum": ["OFAC", "UK", "EU"]}, "description": "Sanctions lists that name this row's IMO number (empty when none; CSV: joined with |). Informational, not a compliance determination: see Sanctions lists in the docs"}}}, "VesselEvent": {"type": "object", "description": "A vessel event, computed from the archive when requested", "properties": {"mmsi": {"type": "integer"}, "imo": {"type": ["integer", "null"], "description": "IMO at the event time"}, "name": {"type": ["string", "null"], "description": "Name at the event time"}, "flag": {"type": ["string", "null"]}, "ts": {"type": "string", "format": "date-time"}, "event": {"type": "string", "enum": ["ENTER_ZONE", "EXIT_ZONE", "STATE_CHANGED", "NAME_CHANGED", "IMO_CHANGED", "CALLSIGN_CHANGED", "DESTINATION_CHANGED", "DRAUGHT_CHANGED", "AIS_GAP", "ENCOUNTER", "FLAG_CHANGED", "POSITION_JUMP"], "description": "ENTER_ZONE / EXIT_ZONE: port call arrival and departure (new_value / old_value is 'Port / LOCODE'); STATE_CHANGED: MOVING, NOT_MOVING (stopped at least 15 min, from the start of the stop) or LONG_STOP (stopped for 6 h, at that moment); *_CHANGED: a static field the vessel broadcasts changed (single short reports are ignored as noise); AIS_GAP: no positions for 6 h or more while under way (old_value hours, new_value nautical miles between the two ends); ENCOUNTER: another vessel within 500 m, both slower than 3 kn, for 2 h or more outside port areas (old_value hours, new_value the other MMSI); FLAG_CHANGED: the IMO number moved to this MMSI from one with another flag (old_value / new_value flag codes); POSITION_JUMP: a physically impossible position (old_value nautical miles from the last good position, new_value the implied speed in knots), once per hour. See detail"}, "old_value": {"description": "Value before the event (string or number; null for ENTER_ZONE)"}, "new_value": {"description": "Value after the event (string or number; null for EXIT_ZONE)"}, "lat": {"type": ["number", "null"]}, "lon": {"type": ["number", "null"], "description": "Position at the event, or the last one before it within 6 h; null when none"}, "port": {"type": ["object", "null"], "description": "Zone events: id, name, country, locode"}, "source": {"type": ["string", "null"], "description": "Source(s) the event was detected in"}, "sanctions": {"type": "array", "items": {"type": "string", "enum": ["OFAC", "UK", "EU"]}, "description": "Sanctions lists that name this row's IMO number (empty when none; CSV: joined with |). Informational, not a compliance determination: see Sanctions lists in the docs"}, "detail": {"type": ["object", "null"], "description": "AIS_GAP: reappeared_at, reappeared_lat, reappeared_lon, others_nearby (other vessels heard within about 12 nm in the first hours of the gap; 0 suggests no receiver coverage there, null when not checked). ENCOUNTER: other_mmsi, other_name, other_imo, other_ship_type, end, min_distance_m. FLAG_CHANGED: imo, old_mmsi, new_mmsi. POSITION_JUMP: flagged_in_hour. null for the other events. CSV and Excel: JSON text"}}}, "EventsMeta": {"type": "object", "properties": {"from": {"type": "string", "format": "date-time"}, "to": {"type": "string", "format": "date-time"}, "types": {"type": "array", "items": {"type": "string"}, "description": "Event types in this response"}, "count": {"type": "integer"}, "complete": {"type": "boolean", "description": "true when there are no more pages (paging only; see data_complete)"}, "next_cursor": {"type": ["string", "null"], "description": "Pass as ?cursor= to get the next page"}, "next": {"type": ["string", "null"], "description": "Relative URL of the next page"}, "embargo_cutoff": {"type": ["string", "null"], "format": "date-time", "description": "Data newer than this is not available on your plan (null on plans with live data)"}, "private_vessels": {"type": "string", "enum": ["excluded", "included"], "description": "Whether private vessels are part of this response for your account"}, "attribution": {"type": "array", "items": {"type": "object"}, "description": "Required attribution for the sources in this response"}, "sanctions_lists": {"$ref": "#/components/schemas/SanctionsLists"}, "notice": {"type": "string", "description": "Not-for-navigation notice (also in the X-Notice header)"}}}, "PortCallMeta": {"type": "object", "properties": {"from": {"type": "string", "format": "date-time"}, "to": {"type": "string", "format": "date-time"}, "event": {"type": "string", "enum": ["any", "arrival", "departure"]}, "layout": {"type": "string", "enum": ["calls", "events"], "description": "calls: one row per port call; events: ENTER_ZONE / EXIT_ZONE rows (the layout parameter)"}, "zones": {"type": "string", "enum": ["port", "anchorage", "all"], "description": "Which zones the rows cover (the zones parameter)"}, "count": {"type": "integer"}, "complete": {"type": "boolean", "description": "true when there are no more pages (paging only; see data_complete)"}, "next_cursor": {"type": ["string", "null"], "description": "Pass as ?cursor= to get the next page"}, "next": {"type": ["string", "null"], "description": "Relative URL of the next page"}, "embargo_cutoff": {"type": ["string", "null"], "format": "date-time", "description": "Data newer than this is not available on your plan (null on plans with live data)"}, "calls_through": {"type": "object", "additionalProperties": {"type": ["string", "null"], "format": "date-time"}, "description": "Per source: port calls are built from this source's data up to this time (the archive is processed nightly), never later than embargo_cutoff"}, "private_vessels": {"type": "string", "enum": ["excluded", "included"], "description": "Whether private vessels are part of this response for your account"}, "attribution": {"type": "array", "items": {"type": "object"}, "description": "Required attribution for the sources in this response"}, "sanctions_lists": {"$ref": "#/components/schemas/SanctionsLists"}, "notice": {"type": "string", "description": "Not-for-navigation notice (also in the X-Notice header)"}}}, "Problem": {"type": "object", "properties": {"type": {"type": "string"}, "title": {"type": "string"}, "status": {"type": "integer"}, "detail": {"type": "string"}, "retry_after_s": {"type": "integer"}, "upgrade_url": {"type": "string", "format": "uri"}, "credits_remaining": {"type": "integer", "description": "402 only: credits left (0)"}, "credits_reset_at": {"type": "string", "format": "date-time", "description": "402 only: when monthly credits renew"}, "pricing_url": {"type": "string", "format": "uri", "description": "402 only: plans and credit packs"}}}}, "responses": {"Problem": {"description": "RFC 9457 problem details", "content": {"application/problem+json": {"schema": {"type": "object", "properties": {"type": {"type": "string"}, "title": {"type": "string"}, "status": {"type": "integer"}, "detail": {"type": "string"}, "retry_after_s": {"type": "integer"}, "upgrade_url": {"type": "string", "format": "uri"}, "credits_remaining": {"type": "integer", "description": "402 only: credits left (0)"}, "credits_reset_at": {"type": "string", "format": "date-time", "description": "402 only: when monthly credits renew"}, "pricing_url": {"type": "string", "format": "uri", "description": "402 only: plans and credit packs"}}}}}}}}, "paths": {"/v1/status": {"get": {"summary": "Service status and data coverage per source (public)", "description": "status is ok or degraded, HTTP 200 in both cases. reasons lists the failed checks as codes: dma_stale (no new dma day for too long), digitraffic_stale (no digitraffic data written for too long), writer_error, disk_warning, coverage_error, live_heartbeat (live collection unhealthy), live_replica_stale (live data on this API is not current: the live collector is unreachable), privacy_registry_missing (private vessels are excluded by a stricter interim rule until the registry is rebuilt; vessel lookups may return no results meanwhile). Each coverage entry carries available_until: the time up to which that source can be queried, never later than the embargo cutoff. With an API key the cutoff is your plan's (available_until is null on plans with live data) and live gives the live view: included, sources, state (syncing, live or stale) and stale_s.", "responses": {"200": {"description": "ok or degraded"}}}}, "/v1/sources": {"get": {"summary": "Data sources, licences, required attribution and coverage (public)", "description": "Each source carries its coverage and available_until: the time up to which its data can be queried, never later than the embargo cutoff (dma lags by its publication delay, noaa ends with its last loaded year). notice is the not-for-navigation notice.", "responses": {"200": {"description": "ok"}}}}, "/v1/usage": {"get": {"summary": "Plan, limits and credits (uses no credits)", "security": [{"bearer": []}], "description": "label is the plan's name (for example Pro), limits the plan's limits (credits: monthly credits; live and ws: live data and WebSocket connections). credits: remaining (usable now), plan (monthly, used, remaining, period_start, resets_at), packs (credits, remaining, purchased_at, expires_at; valid packs, the one used next first), packs_remaining and used_this_period (all credits used this period, packs included). period_resets_at is credits.plan.resets_at. live: included, sources (the live endpoints' sources), ws_limit and ws_open (concurrent WebSocket connections of the account).", "responses": {"200": {"description": "ok"}, "401": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}}}}, "/v1/vessels/search": {"get": {"summary": "Search vessels by name, call sign, MMSI prefix or IMO", "security": [{"bearer": []}], "parameters": [{"name": "q", "in": "query", "required": true, "description": "At least 2 characters", "schema": {"type": "string"}}, {"name": "limit", "in": "query", "required": false, "description": "1-50", "schema": {"type": "integer", "default": 20}}, {"name": "offset", "in": "query", "required": false, "description": "0-1000; use next_offset from the previous page", "schema": {"type": "integer", "default": 0}}], "responses": {"200": {"description": "Most recently seen first", "headers": {"X-Credits-Used": {"description": "Credits this response used (0 for empty results and errors)", "schema": {"type": "integer"}}, "X-Credits-Remaining": {"description": "Credits left after this response: monthly credits plus credit packs", "schema": {"type": "integer"}}, "X-Notice": {"description": "Not-for-navigation notice (same text as meta.notice)", "schema": {"type": "string"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"query": {"type": "string"}, "offset": {"type": "integer"}, "results": {"type": "array", "items": {"$ref": "#/components/schemas/VesselSummary"}}, "next_offset": {"type": ["integer", "null"]}, "meta": {"$ref": "#/components/schemas/ResponseMeta"}}}}}}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}}}, "/v1/vessels/{mmsi}": {"get": {"summary": "Vessel identity by MMSI: current static data and observation log", "security": [{"bearer": []}], "description": "live_position is the latest live position (a LivePosition) on plans with live data (Pro and Business), null otherwise. flag and dwt_estimate are derived (see Flag and DwtEstimate); the estimate uses the latest dimensions and the deepest draught in all of the vessel's reports.", "parameters": [{"name": "mmsi", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"description": "ok", "headers": {"X-Credits-Used": {"description": "Credits this response used (0 for empty results and errors)", "schema": {"type": "integer"}}, "X-Credits-Remaining": {"description": "Credits left after this response: monthly credits plus credit packs", "schema": {"type": "integer"}}, "X-Notice": {"description": "Not-for-navigation notice (same text as meta.notice)", "schema": {"type": "string"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"mmsi": {"type": "integer"}, "current": {"type": "object", "description": "Latest known imo, name, callsign, ship_type, length_m, width_m, draught_m, destination, eta"}, "first_seen": {"type": ["string", "null"], "format": "date-time"}, "last_seen": {"type": ["string", "null"], "format": "date-time"}, "observations": {"type": "array", "items": {"type": "object"}, "description": "Distinct static reports, newest first (at most 50)"}, "flag": {"$ref": "#/components/schemas/Flag"}, "dwt_estimate": {"$ref": "#/components/schemas/DwtEstimate"}, "sanctions": {"type": "array", "items": {"$ref": "#/components/schemas/SanctionListing"}, "description": "Official sanctions lists that name the current IMO number (empty when none or no IMO)"}, "live_position": {"description": "Latest live position (a LivePosition) on plans with live data (Pro and Business), otherwise null"}, "meta": {"$ref": "#/components/schemas/ResponseMeta"}}}}}}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}}}, "/v1/vessels/{mmsi}/track": {"get": {"summary": "Track of one MMSI over a time range", "security": [{"bearer": []}], "description": "At raw resolution, copies of one report received by several sources (same MMSI, timestamps at most 2 seconds and positions at most 1 metre apart) are merged into one row, the preferred source's: barentswatch, digitraffic and dma first, then aisstream, then openwaters. Rows from one source are never merged, and a copy from a source outside the plan never removes a row.", "parameters": [{"name": "mmsi", "in": "path", "required": true, "schema": {"type": "integer"}}, {"name": "from", "in": "query", "required": false, "description": "ISO 8601 start (inclusive); default: to minus 24 h", "schema": {"type": "string", "format": "date-time"}}, {"name": "to", "in": "query", "required": false, "description": "ISO 8601 end (exclusive); default: now on plans with live data, otherwise now minus 24 h. Later values are clamped (see meta.embargo_cutoff)", "schema": {"type": "string", "format": "date-time"}}, {"name": "resolution", "in": "query", "required": false, "description": "raw = every fix; 1m / 1h = latest fix per vessel per minute / hour (no interpolation)", "schema": {"type": "string", "enum": ["raw", "1m", "1h"], "default": "raw"}}, {"name": "format", "in": "query", "required": false, "description": "json, geojson (application/geo+json), csv (text/csv) or xlsx (Excel workbook); csv and xlsx page through the Link / X-Next-Cursor headers", "schema": {"type": "string", "enum": ["json", "geojson", "csv", "xlsx"], "default": "json"}}, {"name": "include", "in": "query", "required": false, "description": "static = add the vessel's static data to every row (IMO, name, call sign, ship type, length, beam, draught, destination, ETA and the AIS dimensions A, B, C, D as reported at that time); none = position fields only. Default: static for csv and xlsx, none for json and geojson. No extra credits", "schema": {"type": "string", "enum": ["static", "none"]}}, {"name": "limit", "in": "query", "required": false, "description": "Rows per page, up to the plan's track_points; the default is 5000, or track_points when that is lower", "schema": {"type": "integer", "default": 5000}}, {"name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from meta.next_cursor. When given, from, to, resolution and the subject are taken from the cursor", "schema": {"type": "string"}}], "responses": {"200": {"description": "Positions ordered by time", "headers": {"X-Credits-Used": {"description": "Credits this response used (0 for empty results and errors)", "schema": {"type": "integer"}}, "X-Credits-Remaining": {"description": "Credits left after this response: monthly credits plus credit packs", "schema": {"type": "integer"}}, "X-Notice": {"description": "Not-for-navigation notice (same text as meta.notice)", "schema": {"type": "string"}}, "X-Count": {"description": "Rows in this page", "schema": {"type": "integer"}}, "X-Complete": {"description": "true when there are no more pages", "schema": {"type": "string"}}, "X-Next-Cursor": {"description": "Cursor of the next page (absent on the last page)", "schema": {"type": "string"}}, "Link": {"description": "rel=\"next\" URL of the next page", "schema": {"type": "string"}}, "X-Attribution": {"description": "Required attribution for the sources in this page", "schema": {"type": "string"}}, "X-Data-Through": {"description": "meta.sources_through as source=time pairs, comma separated (source=- when the source has no data)", "schema": {"type": "string"}}, "X-Data-Complete": {"description": "meta.data_complete: true or false", "schema": {"type": "string"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"meta": {"type": "object", "properties": {"from": {"type": "string", "format": "date-time"}, "to": {"type": "string", "format": "date-time"}, "resolution": {"type": "string", "enum": ["raw", "1m", "1h"]}, "count": {"type": "integer"}, "complete": {"type": "boolean", "description": "true when there are no more pages (paging only; see data_complete)"}, "next_cursor": {"type": ["string", "null"], "description": "Pass as ?cursor= to get the next page"}, "next": {"type": ["string", "null"], "description": "Relative URL of the next page"}, "embargo_cutoff": {"type": ["string", "null"], "format": "date-time", "description": "Data newer than this is not available on your plan (null on plans with live data)"}, "include": {"type": "string", "enum": ["static", "none"], "description": "Whether rows carry static data (the include parameter, or its default for the format)"}, "sources_through": {"type": "object", "additionalProperties": {"type": ["string", "null"], "format": "date-time"}, "description": "Per source: the archive holds this source's data up to this time, never later than embargo_cutoff (null: no data yet)"}, "pending_days": {"type": "object", "additionalProperties": {"type": "array", "items": {"type": "string", "format": "date"}}, "description": "Per source: UTC days in this window the source has not delivered yet (at most 100)"}, "missing_days": {"type": "object", "additionalProperties": {"type": "array", "items": {"type": "string", "format": "date"}}, "description": "Per source: UTC days in this window up to sources_through without data (at most 100)"}, "unavailable_days": {"type": "object", "additionalProperties": {"type": "array", "items": {"type": "string", "format": "date"}}, "description": "Per source: UTC days in this window the source never published; they will not arrive and do not count against data_complete (at most 100)"}, "data_complete": {"type": "boolean", "description": "false when pending_days or missing_days is not empty for any source"}, "private_vessels": {"type": "string", "enum": ["excluded", "included"], "description": "Whether private vessels are part of this response for your account"}, "attribution": {"type": "array", "items": {"type": "object"}, "description": "Required attribution for the sources in this response"}, "sanctions": {"type": "array", "items": {"$ref": "#/components/schemas/SanctionListing"}, "description": "IMO track only: official sanctions lists that name this IMO number"}, "sanctions_lists": {"$ref": "#/components/schemas/SanctionsLists"}, "notice": {"type": "string", "description": "Not-for-navigation notice (also in the X-Notice header)"}}}, "positions": {"type": "array", "items": {"type": "object", "properties": {"mmsi": {"type": "integer"}, "ts": {"type": "string", "format": "date-time", "description": "Message timestamp (UTC) as reported by the source"}, "lat": {"type": "number"}, "lon": {"type": "number"}, "sog": {"type": ["number", "null"], "description": "Speed over ground, knots"}, "cog": {"type": ["number", "null"], "description": "Course over ground, degrees"}, "heading": {"type": ["integer", "null"], "description": "True heading, degrees; null if unavailable (raw 511)"}, "nav_status": {"type": ["integer", "null"], "description": "ITU-R M.1371 navigational status 0-14"}, "source": {"type": "string", "description": "Data source id, see /v1/sources"}, "flags": {"type": ["string", "null"], "description": "Quality flag, e.g. implausible_jump (kept, never dropped)"}, "flag": {"type": ["string", "null"], "description": "Flag of the vessel: ISO 3166-1 alpha-2 code derived from the MMSI (see Vessel particulars); null when the MMSI is not a ship station or its MID is not allocated"}, "imo": {"type": ["integer", "null"], "description": "IMO number; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "name": {"type": ["string", "null"], "description": "Vessel name; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "callsign": {"type": ["string", "null"], "description": "Call sign; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "ship_type": {"type": ["integer", "null"], "description": "AIS ship type code; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "length_m": {"type": ["number", "null"], "description": "Length, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "width_m": {"type": ["number", "null"], "description": "Beam, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "draught_m": {"type": ["number", "null"], "description": "Draught, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "destination": {"type": ["string", "null"], "description": "Destination as broadcast; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "eta": {"type": ["string", "null"], "format": "date-time", "description": "ETA as broadcast (UTC); with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "dim_a": {"type": ["integer", "null"], "description": "AIS dimension A: GPS antenna to bow, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "dim_b": {"type": ["integer", "null"], "description": "AIS dimension B: GPS antenna to stern, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "dim_c": {"type": ["integer", "null"], "description": "AIS dimension C: GPS antenna to port side, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "dim_d": {"type": ["integer", "null"], "description": "AIS dimension D: GPS antenna to starboard side, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}}}}}}}, "application/geo+json": {"schema": {"type": "object"}}, "text/csv": {"schema": {"type": "string"}}, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {"schema": {"type": "string", "format": "binary"}}}}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}}}, "/v1/vessels/batch": {"get": {"summary": "Vessel details for up to 100 MMSIs and IMO numbers in one request", "description": "Each result carries the identifier asked for (query) and the vessel's latest static data, first and last seen, sources, flag, dwt_estimate and sanctions. An IMO number resolves to the MMSI that reported it last. Identifiers not found in the sources of your plan are listed in not_found. 1 credit per vessel returned (a vessel asked for twice counts once).", "security": [{"bearer": []}], "parameters": [{"name": "mmsi", "in": "query", "schema": {"type": "string"}, "description": "Comma-separated 9-digit MMSIs"}, {"name": "imo", "in": "query", "schema": {"type": "string"}, "description": "Comma-separated IMO numbers (valid check digit); mmsi and imo together at most 100"}], "responses": {"200": {"description": "ok", "headers": {"X-Credits-Used": {"description": "Credits this response used (0 for empty results and errors)", "schema": {"type": "integer"}}, "X-Credits-Remaining": {"description": "Credits left after this response: monthly credits plus credit packs", "schema": {"type": "integer"}}, "X-Notice": {"description": "Not-for-navigation notice (same text as meta.notice)", "schema": {"type": "string"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"results": {"type": "array", "items": {"$ref": "#/components/schemas/BatchVessel"}}, "not_found": {"type": "array", "items": {"type": "object"}, "description": "Identifiers without a vessel, e.g. {\"mmsi\": 123456789}"}, "meta": {"$ref": "#/components/schemas/ResponseMeta"}}}}}}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}}}, "/v1/vessels/imo/{imo}": {"get": {"summary": "MMSIs that have reported this IMO number, newest first (at most 50; truncated=true beyond that; the /track endpoint is not limited)", "security": [{"bearer": []}], "parameters": [{"name": "imo", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"description": "ok", "headers": {"X-Credits-Used": {"description": "Credits this response used (0 for empty results and errors)", "schema": {"type": "integer"}}, "X-Credits-Remaining": {"description": "Credits left after this response: monthly credits plus credit packs", "schema": {"type": "integer"}}, "X-Notice": {"description": "Not-for-navigation notice (same text as meta.notice)", "schema": {"type": "string"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"imo": {"type": "integer"}, "sanctions": {"type": "array", "items": {"$ref": "#/components/schemas/SanctionListing"}, "description": "Official sanctions lists that name this IMO number (empty when none)"}, "vessels": {"type": "array", "items": {"$ref": "#/components/schemas/ImoMatch"}}, "truncated": {"type": "boolean"}, "meta": {"$ref": "#/components/schemas/ResponseMeta"}}}}}}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}}}, "/v1/vessels/imo/{imo}/track": {"get": {"summary": "Track of one IMO across MMSI changes. Each MMSI counts only while it reported this IMO (\u00b110 min)", "security": [{"bearer": []}], "description": "At raw resolution, copies of one report received by several sources (same MMSI, timestamps at most 2 seconds and positions at most 1 metre apart) are merged into one row, the preferred source's: barentswatch, digitraffic and dma first, then aisstream, then openwaters. Rows from one source are never merged, and a copy from a source outside the plan never removes a row.", "parameters": [{"name": "imo", "in": "path", "required": true, "schema": {"type": "integer"}}, {"name": "from", "in": "query", "required": false, "description": "ISO 8601 start (inclusive); default: to minus 24 h", "schema": {"type": "string", "format": "date-time"}}, {"name": "to", "in": "query", "required": false, "description": "ISO 8601 end (exclusive); default: now on plans with live data, otherwise now minus 24 h. Later values are clamped (see meta.embargo_cutoff)", "schema": {"type": "string", "format": "date-time"}}, {"name": "resolution", "in": "query", "required": false, "description": "raw = every fix; 1m / 1h = latest fix per vessel per minute / hour (no interpolation)", "schema": {"type": "string", "enum": ["raw", "1m", "1h"], "default": "raw"}}, {"name": "format", "in": "query", "required": false, "description": "json, geojson (application/geo+json), csv (text/csv) or xlsx (Excel workbook); csv and xlsx page through the Link / X-Next-Cursor headers", "schema": {"type": "string", "enum": ["json", "geojson", "csv", "xlsx"], "default": "json"}}, {"name": "include", "in": "query", "required": false, "description": "static = add the vessel's static data to every row (IMO, name, call sign, ship type, length, beam, draught, destination, ETA and the AIS dimensions A, B, C, D as reported at that time); none = position fields only. Default: static for csv and xlsx, none for json and geojson. No extra credits", "schema": {"type": "string", "enum": ["static", "none"]}}, {"name": "limit", "in": "query", "required": false, "description": "Rows per page, up to the plan's track_points; the default is 5000, or track_points when that is lower", "schema": {"type": "integer", "default": 5000}}, {"name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from meta.next_cursor. When given, from, to, resolution and the subject are taken from the cursor", "schema": {"type": "string"}}], "responses": {"200": {"description": "Positions ordered by time; each row carries its mmsi", "headers": {"X-Credits-Used": {"description": "Credits this response used (0 for empty results and errors)", "schema": {"type": "integer"}}, "X-Credits-Remaining": {"description": "Credits left after this response: monthly credits plus credit packs", "schema": {"type": "integer"}}, "X-Notice": {"description": "Not-for-navigation notice (same text as meta.notice)", "schema": {"type": "string"}}, "X-Count": {"description": "Rows in this page", "schema": {"type": "integer"}}, "X-Complete": {"description": "true when there are no more pages", "schema": {"type": "string"}}, "X-Next-Cursor": {"description": "Cursor of the next page (absent on the last page)", "schema": {"type": "string"}}, "Link": {"description": "rel=\"next\" URL of the next page", "schema": {"type": "string"}}, "X-Attribution": {"description": "Required attribution for the sources in this page", "schema": {"type": "string"}}, "X-Data-Through": {"description": "meta.sources_through as source=time pairs, comma separated (source=- when the source has no data)", "schema": {"type": "string"}}, "X-Data-Complete": {"description": "meta.data_complete: true or false", "schema": {"type": "string"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"meta": {"type": "object", "properties": {"from": {"type": "string", "format": "date-time"}, "to": {"type": "string", "format": "date-time"}, "resolution": {"type": "string", "enum": ["raw", "1m", "1h"]}, "count": {"type": "integer"}, "complete": {"type": "boolean", "description": "true when there are no more pages (paging only; see data_complete)"}, "next_cursor": {"type": ["string", "null"], "description": "Pass as ?cursor= to get the next page"}, "next": {"type": ["string", "null"], "description": "Relative URL of the next page"}, "embargo_cutoff": {"type": ["string", "null"], "format": "date-time", "description": "Data newer than this is not available on your plan (null on plans with live data)"}, "include": {"type": "string", "enum": ["static", "none"], "description": "Whether rows carry static data (the include parameter, or its default for the format)"}, "sources_through": {"type": "object", "additionalProperties": {"type": ["string", "null"], "format": "date-time"}, "description": "Per source: the archive holds this source's data up to this time, never later than embargo_cutoff (null: no data yet)"}, "pending_days": {"type": "object", "additionalProperties": {"type": "array", "items": {"type": "string", "format": "date"}}, "description": "Per source: UTC days in this window the source has not delivered yet (at most 100)"}, "missing_days": {"type": "object", "additionalProperties": {"type": "array", "items": {"type": "string", "format": "date"}}, "description": "Per source: UTC days in this window up to sources_through without data (at most 100)"}, "unavailable_days": {"type": "object", "additionalProperties": {"type": "array", "items": {"type": "string", "format": "date"}}, "description": "Per source: UTC days in this window the source never published; they will not arrive and do not count against data_complete (at most 100)"}, "data_complete": {"type": "boolean", "description": "false when pending_days or missing_days is not empty for any source"}, "private_vessels": {"type": "string", "enum": ["excluded", "included"], "description": "Whether private vessels are part of this response for your account"}, "attribution": {"type": "array", "items": {"type": "object"}, "description": "Required attribution for the sources in this response"}, "sanctions": {"type": "array", "items": {"$ref": "#/components/schemas/SanctionListing"}, "description": "IMO track only: official sanctions lists that name this IMO number"}, "sanctions_lists": {"$ref": "#/components/schemas/SanctionsLists"}, "notice": {"type": "string", "description": "Not-for-navigation notice (also in the X-Notice header)"}}}, "positions": {"type": "array", "items": {"type": "object", "properties": {"mmsi": {"type": "integer"}, "ts": {"type": "string", "format": "date-time", "description": "Message timestamp (UTC) as reported by the source"}, "lat": {"type": "number"}, "lon": {"type": "number"}, "sog": {"type": ["number", "null"], "description": "Speed over ground, knots"}, "cog": {"type": ["number", "null"], "description": "Course over ground, degrees"}, "heading": {"type": ["integer", "null"], "description": "True heading, degrees; null if unavailable (raw 511)"}, "nav_status": {"type": ["integer", "null"], "description": "ITU-R M.1371 navigational status 0-14"}, "source": {"type": "string", "description": "Data source id, see /v1/sources"}, "flags": {"type": ["string", "null"], "description": "Quality flag, e.g. implausible_jump (kept, never dropped)"}, "flag": {"type": ["string", "null"], "description": "Flag of the vessel: ISO 3166-1 alpha-2 code derived from the MMSI (see Vessel particulars); null when the MMSI is not a ship station or its MID is not allocated"}, "imo": {"type": ["integer", "null"], "description": "IMO number; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "name": {"type": ["string", "null"], "description": "Vessel name; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "callsign": {"type": ["string", "null"], "description": "Call sign; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "ship_type": {"type": ["integer", "null"], "description": "AIS ship type code; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "length_m": {"type": ["number", "null"], "description": "Length, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "width_m": {"type": ["number", "null"], "description": "Beam, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "draught_m": {"type": ["number", "null"], "description": "Draught, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "destination": {"type": ["string", "null"], "description": "Destination as broadcast; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "eta": {"type": ["string", "null"], "format": "date-time", "description": "ETA as broadcast (UTC); with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "dim_a": {"type": ["integer", "null"], "description": "AIS dimension A: GPS antenna to bow, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "dim_b": {"type": ["integer", "null"], "description": "AIS dimension B: GPS antenna to stern, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "dim_c": {"type": ["integer", "null"], "description": "AIS dimension C: GPS antenna to port side, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "dim_d": {"type": ["integer", "null"], "description": "AIS dimension D: GPS antenna to starboard side, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}}}}}}}, "application/geo+json": {"schema": {"type": "object"}}, "text/csv": {"schema": {"type": "string"}}, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {"schema": {"type": "string", "format": "binary"}}}}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}}}, "/v1/area": {"get": {"summary": "Historical positions inside a bounding box (Starter, Pro and Business plans)", "security": [{"bearer": []}], "description": "Rows are returned day by day and, at raw resolution, 1\u00b0 tile by tile; inside a tile ordered by vessel and time. Follow next_cursor until complete is true. At raw resolution, copies of one report received by several sources (same MMSI, timestamps at most 2 seconds and positions at most 1 metre apart) are merged into one row, the preferred source's: barentswatch, digitraffic and dma first, then aisstream, then openwaters. Rows from one source are never merged, and a copy from a source outside the plan never removes a row. Copies are matched within each day and tile.", "parameters": [{"name": "bbox", "in": "query", "required": false, "description": "lat_min,lon_min,lat_max,lon_max; each side at most the plan's max_bbox_deg. Required unless cursor is given", "schema": {"type": "string"}}, {"name": "from", "in": "query", "required": false, "description": "ISO 8601 start (inclusive); default: to minus 1 h", "schema": {"type": "string", "format": "date-time"}}, {"name": "to", "in": "query", "required": false, "description": "ISO 8601 end (exclusive); default: now on plans with live data, otherwise now minus 24 h. Later values are clamped (see meta.embargo_cutoff)", "schema": {"type": "string", "format": "date-time"}}, {"name": "resolution", "in": "query", "required": false, "description": "raw = every fix; 1m / 1h = latest fix per vessel per minute / hour (no interpolation)", "schema": {"type": "string", "enum": ["raw", "1m", "1h"], "default": "raw"}}, {"name": "format", "in": "query", "required": false, "description": "json, geojson (application/geo+json), csv (text/csv) or xlsx (Excel workbook); csv and xlsx page through the Link / X-Next-Cursor headers", "schema": {"type": "string", "enum": ["json", "geojson", "csv", "xlsx"], "default": "json"}}, {"name": "include", "in": "query", "required": false, "description": "static = add the vessel's static data to every row (IMO, name, call sign, ship type, length, beam, draught, destination, ETA and the AIS dimensions A, B, C, D as reported at that time); none = position fields only. Default: static for csv and xlsx, none for json and geojson. No extra credits", "schema": {"type": "string", "enum": ["static", "none"]}}, {"name": "limit", "in": "query", "required": false, "description": "Rows per page, up to the plan's track_points; the default is 5000, or track_points when that is lower", "schema": {"type": "integer", "default": 5000}}, {"name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from meta.next_cursor. When given, from, to, resolution and the subject are taken from the cursor", "schema": {"type": "string"}}], "responses": {"200": {"description": "Positions in the box", "headers": {"X-Credits-Used": {"description": "Credits this response used (0 for empty results and errors)", "schema": {"type": "integer"}}, "X-Credits-Remaining": {"description": "Credits left after this response: monthly credits plus credit packs", "schema": {"type": "integer"}}, "X-Notice": {"description": "Not-for-navigation notice (same text as meta.notice)", "schema": {"type": "string"}}, "X-Count": {"description": "Rows in this page", "schema": {"type": "integer"}}, "X-Complete": {"description": "true when there are no more pages", "schema": {"type": "string"}}, "X-Next-Cursor": {"description": "Cursor of the next page (absent on the last page)", "schema": {"type": "string"}}, "Link": {"description": "rel=\"next\" URL of the next page", "schema": {"type": "string"}}, "X-Attribution": {"description": "Required attribution for the sources in this page", "schema": {"type": "string"}}, "X-Data-Through": {"description": "meta.sources_through as source=time pairs, comma separated (source=- when the source has no data)", "schema": {"type": "string"}}, "X-Data-Complete": {"description": "meta.data_complete: true or false", "schema": {"type": "string"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"meta": {"type": "object", "properties": {"from": {"type": "string", "format": "date-time"}, "to": {"type": "string", "format": "date-time"}, "resolution": {"type": "string", "enum": ["raw", "1m", "1h"]}, "count": {"type": "integer"}, "complete": {"type": "boolean", "description": "true when there are no more pages (paging only; see data_complete)"}, "next_cursor": {"type": ["string", "null"], "description": "Pass as ?cursor= to get the next page"}, "next": {"type": ["string", "null"], "description": "Relative URL of the next page"}, "embargo_cutoff": {"type": ["string", "null"], "format": "date-time", "description": "Data newer than this is not available on your plan (null on plans with live data)"}, "include": {"type": "string", "enum": ["static", "none"], "description": "Whether rows carry static data (the include parameter, or its default for the format)"}, "sources_through": {"type": "object", "additionalProperties": {"type": ["string", "null"], "format": "date-time"}, "description": "Per source: the archive holds this source's data up to this time, never later than embargo_cutoff (null: no data yet)"}, "pending_days": {"type": "object", "additionalProperties": {"type": "array", "items": {"type": "string", "format": "date"}}, "description": "Per source: UTC days in this window the source has not delivered yet (at most 100)"}, "missing_days": {"type": "object", "additionalProperties": {"type": "array", "items": {"type": "string", "format": "date"}}, "description": "Per source: UTC days in this window up to sources_through without data (at most 100)"}, "unavailable_days": {"type": "object", "additionalProperties": {"type": "array", "items": {"type": "string", "format": "date"}}, "description": "Per source: UTC days in this window the source never published; they will not arrive and do not count against data_complete (at most 100)"}, "data_complete": {"type": "boolean", "description": "false when pending_days or missing_days is not empty for any source"}, "private_vessels": {"type": "string", "enum": ["excluded", "included"], "description": "Whether private vessels are part of this response for your account"}, "attribution": {"type": "array", "items": {"type": "object"}, "description": "Required attribution for the sources in this response"}, "sanctions": {"type": "array", "items": {"$ref": "#/components/schemas/SanctionListing"}, "description": "IMO track only: official sanctions lists that name this IMO number"}, "sanctions_lists": {"$ref": "#/components/schemas/SanctionsLists"}, "notice": {"type": "string", "description": "Not-for-navigation notice (also in the X-Notice header)"}}}, "positions": {"type": "array", "items": {"type": "object", "properties": {"mmsi": {"type": "integer"}, "ts": {"type": "string", "format": "date-time", "description": "Message timestamp (UTC) as reported by the source"}, "lat": {"type": "number"}, "lon": {"type": "number"}, "sog": {"type": ["number", "null"], "description": "Speed over ground, knots"}, "cog": {"type": ["number", "null"], "description": "Course over ground, degrees"}, "heading": {"type": ["integer", "null"], "description": "True heading, degrees; null if unavailable (raw 511)"}, "nav_status": {"type": ["integer", "null"], "description": "ITU-R M.1371 navigational status 0-14"}, "source": {"type": "string", "description": "Data source id, see /v1/sources"}, "flags": {"type": ["string", "null"], "description": "Quality flag, e.g. implausible_jump (kept, never dropped)"}, "flag": {"type": ["string", "null"], "description": "Flag of the vessel: ISO 3166-1 alpha-2 code derived from the MMSI (see Vessel particulars); null when the MMSI is not a ship station or its MID is not allocated"}, "imo": {"type": ["integer", "null"], "description": "IMO number; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "name": {"type": ["string", "null"], "description": "Vessel name; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "callsign": {"type": ["string", "null"], "description": "Call sign; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "ship_type": {"type": ["integer", "null"], "description": "AIS ship type code; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "length_m": {"type": ["number", "null"], "description": "Length, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "width_m": {"type": ["number", "null"], "description": "Beam, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "draught_m": {"type": ["number", "null"], "description": "Draught, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "destination": {"type": ["string", "null"], "description": "Destination as broadcast; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "eta": {"type": ["string", "null"], "format": "date-time", "description": "ETA as broadcast (UTC); with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "dim_a": {"type": ["integer", "null"], "description": "AIS dimension A: GPS antenna to bow, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "dim_b": {"type": ["integer", "null"], "description": "AIS dimension B: GPS antenna to stern, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "dim_c": {"type": ["integer", "null"], "description": "AIS dimension C: GPS antenna to port side, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}, "dim_d": {"type": ["integer", "null"], "description": "AIS dimension D: GPS antenna to starboard side, metres; with include=static (default for csv and xlsx): the latest value the vessel reported at or before this row's time, up to 30 days back, from the sources on your plan; null when none"}}}}}}}, "application/geo+json": {"schema": {"type": "object"}}, "text/csv": {"schema": {"type": "string"}}, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {"schema": {"type": "string", "format": "binary"}}}}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}}}, "/v1/vessels/{mmsi}/events": {"get": {"summary": "Events of one MMSI: port arrivals and departures, stops and moves, and changes of name, IMO, call sign, destination or draught", "security": [{"bearer": []}], "description": "Computed from the archive when requested, ordered by time. Static changes are detected per source; the same change reported by several sources within an hour is listed once. A private vessel without access returns an empty page.", "parameters": [{"name": "mmsi", "in": "path", "required": true, "schema": {"type": "integer"}}, {"name": "from", "in": "query", "required": false, "description": "ISO 8601 start; default: to minus 7 days", "schema": {"type": "string", "format": "date-time"}}, {"name": "to", "in": "query", "required": false, "description": "ISO 8601 end (exclusive); default: now on plans with live data, otherwise now minus 24 h. Later values are clamped (see meta.embargo_cutoff). One query may span at most 31 days", "schema": {"type": "string", "format": "date-time"}}, {"name": "types", "in": "query", "required": false, "description": "all, or comma-separated event types: ENTER_ZONE, EXIT_ZONE, STATE_CHANGED, NAME_CHANGED, IMO_CHANGED, CALLSIGN_CHANGED, DESTINATION_CHANGED, DRAUGHT_CHANGED, AIS_GAP, ENCOUNTER, FLAG_CHANGED, POSITION_JUMP. Default: the first eight; the last four only when named or with all", "schema": {"type": "string"}}, {"name": "format", "in": "query", "required": false, "description": "json, csv (text/csv) or xlsx (Excel workbook); csv columns mmsi, imo, name, lat, lon, ts, event, old_value, new_value, port_id, port_locode, source, flag, sanctions, detail", "schema": {"type": "string", "enum": ["json", "csv", "xlsx"], "default": "json"}}, {"name": "limit", "in": "query", "required": false, "description": "Events per page, up to 10000 or the plan's rows per page when that is lower; default 1000", "schema": {"type": "integer", "default": 1000}}, {"name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from meta.next_cursor. When given, from, to and types are taken from the cursor", "schema": {"type": "string"}}], "responses": {"200": {"description": "Vessel events", "headers": {"X-Credits-Used": {"description": "Credits this response used (0 for empty results and errors)", "schema": {"type": "integer"}}, "X-Credits-Remaining": {"description": "Credits left after this response: monthly credits plus credit packs", "schema": {"type": "integer"}}, "X-Notice": {"description": "Not-for-navigation notice (same text as meta.notice)", "schema": {"type": "string"}}, "X-Count": {"description": "Rows in this page", "schema": {"type": "integer"}}, "X-Complete": {"description": "true when there are no more pages", "schema": {"type": "string"}}, "X-Next-Cursor": {"description": "Cursor of the next page (absent on the last page)", "schema": {"type": "string"}}, "Link": {"description": "rel=\"next\" URL of the next page", "schema": {"type": "string"}}, "X-Attribution": {"description": "Required attribution for the sources in this page", "schema": {"type": "string"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"meta": {"$ref": "#/components/schemas/EventsMeta"}, "events": {"type": "array", "items": {"$ref": "#/components/schemas/VesselEvent"}}}}}, "text/csv": {"schema": {"type": "string"}}, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {"schema": {"type": "string", "format": "binary"}}}}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}}}}, "/v1/vessels/imo/{imo}/events": {"get": {"summary": "Events of one IMO across MMSI changes. Each MMSI counts only while it reported this IMO (\u00b110 min)", "security": [{"bearer": []}], "parameters": [{"name": "imo", "in": "path", "required": true, "schema": {"type": "integer"}}, {"name": "from", "in": "query", "required": false, "description": "ISO 8601 start; default: to minus 7 days", "schema": {"type": "string", "format": "date-time"}}, {"name": "to", "in": "query", "required": false, "description": "ISO 8601 end (exclusive); default: now on plans with live data, otherwise now minus 24 h. Later values are clamped (see meta.embargo_cutoff). One query may span at most 31 days", "schema": {"type": "string", "format": "date-time"}}, {"name": "types", "in": "query", "required": false, "description": "all, or comma-separated event types: ENTER_ZONE, EXIT_ZONE, STATE_CHANGED, NAME_CHANGED, IMO_CHANGED, CALLSIGN_CHANGED, DESTINATION_CHANGED, DRAUGHT_CHANGED, AIS_GAP, ENCOUNTER, FLAG_CHANGED, POSITION_JUMP. Default: the first eight; the last four only when named or with all", "schema": {"type": "string"}}, {"name": "format", "in": "query", "required": false, "description": "json, csv (text/csv) or xlsx (Excel workbook); csv columns mmsi, imo, name, lat, lon, ts, event, old_value, new_value, port_id, port_locode, source, flag, sanctions, detail", "schema": {"type": "string", "enum": ["json", "csv", "xlsx"], "default": "json"}}, {"name": "limit", "in": "query", "required": false, "description": "Events per page, up to 10000 or the plan's rows per page when that is lower; default 1000", "schema": {"type": "integer", "default": 1000}}, {"name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from meta.next_cursor. When given, from, to and types are taken from the cursor", "schema": {"type": "string"}}], "responses": {"200": {"description": "Vessel events; each row carries its mmsi", "headers": {"X-Credits-Used": {"description": "Credits this response used (0 for empty results and errors)", "schema": {"type": "integer"}}, "X-Credits-Remaining": {"description": "Credits left after this response: monthly credits plus credit packs", "schema": {"type": "integer"}}, "X-Notice": {"description": "Not-for-navigation notice (same text as meta.notice)", "schema": {"type": "string"}}, "X-Count": {"description": "Rows in this page", "schema": {"type": "integer"}}, "X-Complete": {"description": "true when there are no more pages", "schema": {"type": "string"}}, "X-Next-Cursor": {"description": "Cursor of the next page (absent on the last page)", "schema": {"type": "string"}}, "Link": {"description": "rel=\"next\" URL of the next page", "schema": {"type": "string"}}, "X-Attribution": {"description": "Required attribution for the sources in this page", "schema": {"type": "string"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"meta": {"$ref": "#/components/schemas/EventsMeta"}, "events": {"type": "array", "items": {"$ref": "#/components/schemas/VesselEvent"}}}}}, "text/csv": {"schema": {"type": "string"}}, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {"schema": {"type": "string", "format": "binary"}}}}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}}}}, "/v1/vessels/{mmsi}/port-calls": {"get": {"summary": "Port calls of one MMSI over a time range", "security": [{"bearer": []}], "description": "Ordered by arrival (by departure with event=departure). A private vessel without access returns an empty page, like a vessel without port calls.", "parameters": [{"name": "mmsi", "in": "path", "required": true, "schema": {"type": "integer"}}, {"name": "from", "in": "query", "required": false, "description": "ISO 8601 start; default: to minus 30 days", "schema": {"type": "string", "format": "date-time"}}, {"name": "to", "in": "query", "required": false, "description": "ISO 8601 end (exclusive); default: now on plans with live data, otherwise now minus 24 h. Later values are clamped (see meta.embargo_cutoff). One query may span at most 366 days", "schema": {"type": "string", "format": "date-time"}}, {"name": "event", "in": "query", "required": false, "description": "any = calls in port at any time in the range (default); arrival = calls that arrived in the range; departure = calls that departed in the range", "schema": {"type": "string", "enum": ["any", "arrival", "departure"], "default": "any"}}, {"name": "format", "in": "query", "required": false, "description": "json, csv (text/csv) or xlsx (Excel workbook); csv and xlsx page through the Link / X-Next-Cursor headers", "schema": {"type": "string", "enum": ["json", "csv", "xlsx"], "default": "json"}}, {"name": "zones", "in": "query", "required": false, "description": "port = port calls (default); anchorage = waits at the port's anchorage: a stop of at least 1 hour just outside the port area (up to 12 km beyond it); all = both, in one order", "schema": {"type": "string", "enum": ["port", "anchorage", "all"], "default": "port"}}, {"name": "layout", "in": "query", "required": false, "description": "calls = one row per port call (default); events = one ENTER_ZONE row at arrival and, once the vessel has left, one EXIT_ZONE row at departure, with the draught reported then (json: events instead of port_calls). Paging and credits stay per port call", "schema": {"type": "string", "enum": ["calls", "events"], "default": "calls"}}, {"name": "limit", "in": "query", "required": false, "description": "Port calls per page, up to 10000 or the plan's rows per page when that is lower; default 1000", "schema": {"type": "integer", "default": 1000}}, {"name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from meta.next_cursor. When given, from, to, event and the filters are taken from the cursor", "schema": {"type": "string"}}], "responses": {"200": {"description": "Port calls", "headers": {"X-Credits-Used": {"description": "Credits this response used (0 for empty results and errors)", "schema": {"type": "integer"}}, "X-Credits-Remaining": {"description": "Credits left after this response: monthly credits plus credit packs", "schema": {"type": "integer"}}, "X-Notice": {"description": "Not-for-navigation notice (same text as meta.notice)", "schema": {"type": "string"}}, "X-Count": {"description": "Rows in this page", "schema": {"type": "integer"}}, "X-Complete": {"description": "true when there are no more pages", "schema": {"type": "string"}}, "X-Next-Cursor": {"description": "Cursor of the next page (absent on the last page)", "schema": {"type": "string"}}, "Link": {"description": "rel=\"next\" URL of the next page", "schema": {"type": "string"}}, "X-Attribution": {"description": "Required attribution for the sources in this page", "schema": {"type": "string"}}, "X-Data-Through": {"description": "meta.calls_through as source=time pairs (CSV)", "schema": {"type": "string"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"meta": {"$ref": "#/components/schemas/PortCallMeta"}, "port_calls": {"type": "array", "items": {"$ref": "#/components/schemas/PortCall"}}, "events": {"type": "array", "items": {"$ref": "#/components/schemas/PortCallEvent"}, "description": "With layout=events, instead of port_calls"}}}}, "text/csv": {"schema": {"type": "string"}}, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {"schema": {"type": "string", "format": "binary"}}}}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}}}, "/v1/vessels/imo/{imo}/port-calls": {"get": {"summary": "Port calls of one IMO across MMSI changes. Each MMSI counts only while it reported this IMO (\u00b110 min)", "security": [{"bearer": []}], "parameters": [{"name": "imo", "in": "path", "required": true, "schema": {"type": "integer"}}, {"name": "from", "in": "query", "required": false, "description": "ISO 8601 start; default: to minus 30 days", "schema": {"type": "string", "format": "date-time"}}, {"name": "to", "in": "query", "required": false, "description": "ISO 8601 end (exclusive); default: now on plans with live data, otherwise now minus 24 h. Later values are clamped (see meta.embargo_cutoff). One query may span at most 366 days", "schema": {"type": "string", "format": "date-time"}}, {"name": "event", "in": "query", "required": false, "description": "any = calls in port at any time in the range (default); arrival = calls that arrived in the range; departure = calls that departed in the range", "schema": {"type": "string", "enum": ["any", "arrival", "departure"], "default": "any"}}, {"name": "format", "in": "query", "required": false, "description": "json, csv (text/csv) or xlsx (Excel workbook); csv and xlsx page through the Link / X-Next-Cursor headers", "schema": {"type": "string", "enum": ["json", "csv", "xlsx"], "default": "json"}}, {"name": "zones", "in": "query", "required": false, "description": "port = port calls (default); anchorage = waits at the port's anchorage: a stop of at least 1 hour just outside the port area (up to 12 km beyond it); all = both, in one order", "schema": {"type": "string", "enum": ["port", "anchorage", "all"], "default": "port"}}, {"name": "layout", "in": "query", "required": false, "description": "calls = one row per port call (default); events = one ENTER_ZONE row at arrival and, once the vessel has left, one EXIT_ZONE row at departure, with the draught reported then (json: events instead of port_calls). Paging and credits stay per port call", "schema": {"type": "string", "enum": ["calls", "events"], "default": "calls"}}, {"name": "limit", "in": "query", "required": false, "description": "Port calls per page, up to 10000 or the plan's rows per page when that is lower; default 1000", "schema": {"type": "integer", "default": 1000}}, {"name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from meta.next_cursor. When given, from, to, event and the filters are taken from the cursor", "schema": {"type": "string"}}], "responses": {"200": {"description": "Port calls; each row carries its mmsi", "headers": {"X-Credits-Used": {"description": "Credits this response used (0 for empty results and errors)", "schema": {"type": "integer"}}, "X-Credits-Remaining": {"description": "Credits left after this response: monthly credits plus credit packs", "schema": {"type": "integer"}}, "X-Notice": {"description": "Not-for-navigation notice (same text as meta.notice)", "schema": {"type": "string"}}, "X-Count": {"description": "Rows in this page", "schema": {"type": "integer"}}, "X-Complete": {"description": "true when there are no more pages", "schema": {"type": "string"}}, "X-Next-Cursor": {"description": "Cursor of the next page (absent on the last page)", "schema": {"type": "string"}}, "Link": {"description": "rel=\"next\" URL of the next page", "schema": {"type": "string"}}, "X-Attribution": {"description": "Required attribution for the sources in this page", "schema": {"type": "string"}}, "X-Data-Through": {"description": "meta.calls_through as source=time pairs (CSV)", "schema": {"type": "string"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"meta": {"$ref": "#/components/schemas/PortCallMeta"}, "port_calls": {"type": "array", "items": {"$ref": "#/components/schemas/PortCall"}}, "events": {"type": "array", "items": {"$ref": "#/components/schemas/PortCallEvent"}, "description": "With layout=events, instead of port_calls"}}}}, "text/csv": {"schema": {"type": "string"}}, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {"schema": {"type": "string", "format": "binary"}}}}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}}}, "/v1/ports/{port_id}/calls": {"get": {"summary": "Arrivals, departures and port calls at one port over a time range", "security": [{"bearer": []}], "description": "meta.port is the port (a Port).", "parameters": [{"name": "port_id", "in": "path", "required": true, "schema": {"type": "integer"}}, {"name": "from", "in": "query", "required": false, "description": "ISO 8601 start; default: to minus 30 days", "schema": {"type": "string", "format": "date-time"}}, {"name": "to", "in": "query", "required": false, "description": "ISO 8601 end (exclusive); default: now on plans with live data, otherwise now minus 24 h. Later values are clamped (see meta.embargo_cutoff). One query may span at most 366 days", "schema": {"type": "string", "format": "date-time"}}, {"name": "event", "in": "query", "required": false, "description": "any = calls in port at any time in the range (default); arrival = calls that arrived in the range; departure = calls that departed in the range", "schema": {"type": "string", "enum": ["any", "arrival", "departure"], "default": "any"}}, {"name": "format", "in": "query", "required": false, "description": "json, csv (text/csv) or xlsx (Excel workbook); csv and xlsx page through the Link / X-Next-Cursor headers", "schema": {"type": "string", "enum": ["json", "csv", "xlsx"], "default": "json"}}, {"name": "zones", "in": "query", "required": false, "description": "port = port calls (default); anchorage = waits at the port's anchorage: a stop of at least 1 hour just outside the port area (up to 12 km beyond it); all = both, in one order", "schema": {"type": "string", "enum": ["port", "anchorage", "all"], "default": "port"}}, {"name": "layout", "in": "query", "required": false, "description": "calls = one row per port call (default); events = one ENTER_ZONE row at arrival and, once the vessel has left, one EXIT_ZONE row at departure, with the draught reported then (json: events instead of port_calls). Paging and credits stay per port call", "schema": {"type": "string", "enum": ["calls", "events"], "default": "calls"}}, {"name": "limit", "in": "query", "required": false, "description": "Port calls per page, up to 10000 or the plan's rows per page when that is lower; default 1000", "schema": {"type": "integer", "default": 1000}}, {"name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from meta.next_cursor. When given, from, to, event and the filters are taken from the cursor", "schema": {"type": "string"}}], "responses": {"200": {"description": "Port calls at the port", "headers": {"X-Credits-Used": {"description": "Credits this response used (0 for empty results and errors)", "schema": {"type": "integer"}}, "X-Credits-Remaining": {"description": "Credits left after this response: monthly credits plus credit packs", "schema": {"type": "integer"}}, "X-Notice": {"description": "Not-for-navigation notice (same text as meta.notice)", "schema": {"type": "string"}}, "X-Count": {"description": "Rows in this page", "schema": {"type": "integer"}}, "X-Complete": {"description": "true when there are no more pages", "schema": {"type": "string"}}, "X-Next-Cursor": {"description": "Cursor of the next page (absent on the last page)", "schema": {"type": "string"}}, "Link": {"description": "rel=\"next\" URL of the next page", "schema": {"type": "string"}}, "X-Attribution": {"description": "Required attribution for the sources in this page", "schema": {"type": "string"}}, "X-Data-Through": {"description": "meta.calls_through as source=time pairs (CSV)", "schema": {"type": "string"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"meta": {"$ref": "#/components/schemas/PortCallMeta"}, "port_calls": {"type": "array", "items": {"$ref": "#/components/schemas/PortCall"}}, "events": {"type": "array", "items": {"$ref": "#/components/schemas/PortCallEvent"}, "description": "With layout=events, instead of port_calls"}}}}, "text/csv": {"schema": {"type": "string"}}, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {"schema": {"type": "string", "format": "binary"}}}}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}}}}, "/v1/port-calls": {"get": {"summary": "Port calls across ports, filtered by port, country, UN/LOCODE or bounding box (Starter, Pro and Business plans)", "security": [{"bearer": []}], "description": "Filters combine (all must match); without filters every port is included. meta carries no subject field.", "parameters": [{"name": "port_id", "in": "query", "required": false, "description": "Up to 100 port ids, comma separated", "schema": {"type": "string"}}, {"name": "country", "in": "query", "required": false, "description": "ISO 3166-1 alpha-2 country code of the port, e.g. NL", "schema": {"type": "string"}}, {"name": "locode", "in": "query", "required": false, "description": "UN/LOCODE of the port, e.g. NLRTM", "schema": {"type": "string"}}, {"name": "bbox", "in": "query", "required": false, "description": "lat_min,lon_min,lat_max,lon_max: ports inside the box", "schema": {"type": "string"}}, {"name": "from", "in": "query", "required": false, "description": "ISO 8601 start; default: to minus 30 days", "schema": {"type": "string", "format": "date-time"}}, {"name": "to", "in": "query", "required": false, "description": "ISO 8601 end (exclusive); default: now on plans with live data, otherwise now minus 24 h. Later values are clamped (see meta.embargo_cutoff). One query may span at most 366 days", "schema": {"type": "string", "format": "date-time"}}, {"name": "event", "in": "query", "required": false, "description": "any = calls in port at any time in the range (default); arrival = calls that arrived in the range; departure = calls that departed in the range", "schema": {"type": "string", "enum": ["any", "arrival", "departure"], "default": "any"}}, {"name": "format", "in": "query", "required": false, "description": "json, csv (text/csv) or xlsx (Excel workbook); csv and xlsx page through the Link / X-Next-Cursor headers", "schema": {"type": "string", "enum": ["json", "csv", "xlsx"], "default": "json"}}, {"name": "zones", "in": "query", "required": false, "description": "port = port calls (default); anchorage = waits at the port's anchorage: a stop of at least 1 hour just outside the port area (up to 12 km beyond it); all = both, in one order", "schema": {"type": "string", "enum": ["port", "anchorage", "all"], "default": "port"}}, {"name": "layout", "in": "query", "required": false, "description": "calls = one row per port call (default); events = one ENTER_ZONE row at arrival and, once the vessel has left, one EXIT_ZONE row at departure, with the draught reported then (json: events instead of port_calls). Paging and credits stay per port call", "schema": {"type": "string", "enum": ["calls", "events"], "default": "calls"}}, {"name": "limit", "in": "query", "required": false, "description": "Port calls per page, up to 10000 or the plan's rows per page when that is lower; default 1000", "schema": {"type": "integer", "default": 1000}}, {"name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from meta.next_cursor. When given, from, to, event and the filters are taken from the cursor", "schema": {"type": "string"}}], "responses": {"200": {"description": "Port calls", "headers": {"X-Credits-Used": {"description": "Credits this response used (0 for empty results and errors)", "schema": {"type": "integer"}}, "X-Credits-Remaining": {"description": "Credits left after this response: monthly credits plus credit packs", "schema": {"type": "integer"}}, "X-Notice": {"description": "Not-for-navigation notice (same text as meta.notice)", "schema": {"type": "string"}}, "X-Count": {"description": "Rows in this page", "schema": {"type": "integer"}}, "X-Complete": {"description": "true when there are no more pages", "schema": {"type": "string"}}, "X-Next-Cursor": {"description": "Cursor of the next page (absent on the last page)", "schema": {"type": "string"}}, "Link": {"description": "rel=\"next\" URL of the next page", "schema": {"type": "string"}}, "X-Attribution": {"description": "Required attribution for the sources in this page", "schema": {"type": "string"}}, "X-Data-Through": {"description": "meta.calls_through as source=time pairs (CSV)", "schema": {"type": "string"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"meta": {"$ref": "#/components/schemas/PortCallMeta"}, "port_calls": {"type": "array", "items": {"$ref": "#/components/schemas/PortCall"}}, "events": {"type": "array", "items": {"$ref": "#/components/schemas/PortCallEvent"}, "description": "With layout=events, instead of port_calls"}}}}, "text/csv": {"schema": {"type": "string"}}, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {"schema": {"type": "string", "format": "binary"}}}}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}}}, "/v1/ports": {"get": {"summary": "Search ports by name, country, UN/LOCODE or bounding box", "security": [{"bearer": []}], "description": "Ports of the World Port Index and UN/LOCODE. q matches the name or an alternate name (case and accent insensitive): exact names first, then names starting with q, then the rest; larger harbors first within each group. Response: ports (Port objects), count, total, offset, next_offset (null on the last page) and meta (attribution and notice). Port lookups use no credits.", "parameters": [{"name": "q", "in": "query", "required": false, "description": "2 to 64 characters", "schema": {"type": "string"}}, {"name": "country", "in": "query", "required": false, "description": "ISO 3166-1 alpha-2 country code, e.g. NL", "schema": {"type": "string"}}, {"name": "locode", "in": "query", "required": false, "description": "UN/LOCODE, e.g. NLRTM", "schema": {"type": "string"}}, {"name": "bbox", "in": "query", "required": false, "description": "lat_min,lon_min,lat_max,lon_max", "schema": {"type": "string"}}, {"name": "port_id", "in": "query", "required": false, "description": "Up to 100 port ids, comma separated", "schema": {"type": "string"}}, {"name": "limit", "in": "query", "required": false, "description": "1-500", "schema": {"type": "integer", "default": 50}}, {"name": "offset", "in": "query", "required": false, "description": "0-10000; use next_offset from the previous page", "schema": {"type": "integer", "default": 0}}, {"name": "format", "in": "query", "required": false, "description": "json, csv (text/csv) or xlsx (Excel workbook); csv and xlsx columns id, name, alternate_names (| separated), country, locode, lat, lon, harbor_size, harbor_type, radius_km, with X-Count, X-Total and X-Attribution headers", "schema": {"type": "string", "enum": ["json", "csv", "xlsx"], "default": "json"}}], "responses": {"200": {"description": "ok", "headers": {"X-Credits-Used": {"description": "Credits this response used (0 for empty results and errors)", "schema": {"type": "integer"}}, "X-Credits-Remaining": {"description": "Credits left after this response: monthly credits plus credit packs", "schema": {"type": "integer"}}, "X-Notice": {"description": "Not-for-navigation notice (same text as meta.notice)", "schema": {"type": "string"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"ports": {"type": "array", "items": {"$ref": "#/components/schemas/Port"}}}}}, "text/csv": {"schema": {"type": "string"}}, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {"schema": {"type": "string", "format": "binary"}}}}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}}}}, "/v1/ports/{port_id}": {"get": {"summary": "One port: name, country, UN/LOCODE, position, harbor size and type, port area radius", "description": "Uses no credits.", "security": [{"bearer": []}], "parameters": [{"name": "port_id", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"description": "A Port with meta", "headers": {"X-Credits-Used": {"description": "Credits this response used (0 for empty results and errors)", "schema": {"type": "integer"}}, "X-Credits-Remaining": {"description": "Credits left after this response: monthly credits plus credit packs", "schema": {"type": "integer"}}, "X-Notice": {"description": "Not-for-navigation notice (same text as meta.notice)", "schema": {"type": "string"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Port"}}}}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}}}}, "/v1/vessels/{mmsi}/position": {"get": {"summary": "Latest live position (Pro and Business plans; sources: `aisstream`, `barentswatch`, `digitraffic`, `openwaters`)", "security": [{"bearer": []}], "description": "404 when the vessel has no live position in your plan's live sources, with the same detail for a private or withdrawn vessel. 503 while the live view is starting.", "parameters": [{"name": "mmsi", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"description": "ok", "headers": {"X-Credits-Used": {"description": "Credits this response used (0 for empty results and errors)", "schema": {"type": "integer"}}, "X-Credits-Remaining": {"description": "Credits left after this response: monthly credits plus credit packs", "schema": {"type": "integer"}}, "X-Notice": {"description": "Not-for-navigation notice (same text as meta.notice)", "schema": {"type": "string"}}, "X-Live-Status": {"description": "Absent when the live view is current; stale: the last known state is served", "schema": {"type": "string", "enum": ["stale"]}}, "X-Live-Stale-S": {"description": "With X-Live-Status: stale, seconds since the live view was last current", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"allOf": [{"$ref": "#/components/schemas/LivePosition"}, {"type": "object", "properties": {"meta": {"$ref": "#/components/schemas/LiveMeta"}}}]}}}}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}}}, "/v1/positions": {"get": {"summary": "Latest live positions in a box (Pro and Business plans; sources: `aisstream`, `barentswatch`, `digitraffic`, `openwaters`)", "security": [{"bearer": []}], "description": "Up to 2000 vessels; truncated is true when there are more. 503 while the live view is starting.", "parameters": [{"name": "bbox", "in": "query", "required": true, "description": "lat_min,lon_min,lat_max,lon_max; each side at most the plan's max_bbox_deg", "schema": {"type": "string"}}, {"name": "max_age", "in": "query", "required": false, "description": "Only positions newer than this many seconds; default 86400", "schema": {"type": "number", "default": 86400}}], "responses": {"200": {"description": "ok", "headers": {"X-Credits-Used": {"description": "Credits this response used (0 for empty results and errors)", "schema": {"type": "integer"}}, "X-Credits-Remaining": {"description": "Credits left after this response: monthly credits plus credit packs", "schema": {"type": "integer"}}, "X-Notice": {"description": "Not-for-navigation notice (same text as meta.notice)", "schema": {"type": "string"}}, "X-Live-Status": {"description": "Absent when the live view is current; stale: the last known state is served", "schema": {"type": "string", "enum": ["stale"]}}, "X-Live-Stale-S": {"description": "With X-Live-Status: stale, seconds since the live view was last current", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"count": {"type": "integer"}, "truncated": {"type": "boolean"}, "positions": {"type": "array", "items": {"$ref": "#/components/schemas/LivePosition"}}, "meta": {"$ref": "#/components/schemas/LiveMeta"}, "live_stale_s": {"type": "integer", "description": "Present when the live view is stale"}}}}}}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}}}, "/v1/stream": {"get": {"summary": "Live WebSocket stream (Pro and Business plans; sources: `aisstream`, `barentswatch`, `digitraffic`, `openwaters`). ?key= is accepted here only", "description": "Send one subscription message within 5 s: {\"bbox\":[[lat_min,lon_min,lat_max,lon_max],\u2026]} and/or {\"mmsi\":[\u2026]}; at most 10 boxes, each side at most the plan's max_bbox_deg, and 1000 MMSIs. The server answers {\"type\":\"subscribed\"} with bbox, mmsi, sources, private_vessels, attribution and notice, then sends {\"type\":\"position\"} messages (the Position fields with rot and ais_class) and {\"type\":\"status\",\"live\":\"stale\"|\"ok\",\"since\":\u2026} when the live view stops or resumes being current. The stream is included in the plan and uses no credits; concurrent connections are limited per account (429 Too many connections). Close codes: 4000 no subscription in time, 4001 empty subscription, 4002 invalid subscription, 4003 not included in your plan (also after a plan change, when the subscription exceeds the new plan, or for the newest streams beyond the new plan's connection limit), 4004 API key revoked, 1011 server error.", "security": [{"bearer": []}], "responses": {"101": {"description": "switching protocols"}, "401": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}}}}, "/v1/openapi.json": {"get": {"summary": "This document", "responses": {"200": {"description": "ok"}}}}}}