Port calls, berth calls, and event timelines — surfaces every arrival, departure, and berth touch detected by the MarineTraffic AIS network. Scope by vessel (`/portcalls`, `/vesselevents`, `/berth-calls` with MMSI/IMO/SHIP_ID) or by port (same endpoints scoped with port_id / UNLOCODE / berth_id / terminal_id). Returns voyage duration, time-in-port, draught, market segment, and full vessel/port keys for downstream joining.
openapi: 3.0.2
info:
title: MarineTraffic Events API
version: 1.0.0
description: Port calls, berth calls, and event timelines for single vessels and entire ports — surfacing every arrival,
departure, and berth touch detected by the global AIS network.
contact:
name: MarineTraffic
url: https://www.marinetraffic.com/
servers:
- url: https://services.marinetraffic.com/api
tags:
- name: Single Vessel Events
- name: Port Events
paths:
/portcalls/{api_key}:
get:
tags:
- Single Vessel Events
summary: Single Vessel Port Calls
description: "Retrieve arrival and departure information of a vessel for a specific period of time. </br></br> <b>Notes</b>\
\ <ul>\n <li>Data is available for dates **after** 2015-01-16</li>\n <li>Information about <a href=\"https://support.marinetraffic.com/en/articles/9552860-what-kind-of-information-is-ais-transmitted\"\
>AIS-transmitted data</a></li>\n <li>**MOVE_TYPE** values: 1=Departure, 0=Arrival</li>\n <li>The <b>frequency\
\ of allowed API calls</b> is specific to your API key and is detailed in your contract as a number of successful\
\ calls per time period. For example “2 calls per minute”. </br>Regardless of this agreed limit, each API key is technically\
\ restricted to a maximum of 100 total (including successful and unsuccessful) requests per minute to ensure system\
\ stability.</li>\n</ul>"
operationId: portcalls
parameters:
- $ref: '#/components/parameters/api_key'
- $ref: '#/components/parameters/v_EV01'
- $ref: '#/components/parameters/shipid_EV01'
- $ref: '#/components/parameters/mmsi_EV01'
- $ref: '#/components/parameters/imo_EV01'
- $ref: '#/components/parameters/timespan_EV01'
- $ref: '#/components/parameters/movetype_EV01'
- $ref: '#/components/parameters/exclude_intransit_EV01'
- $ref: '#/components/parameters/fromdate_EV01'
- $ref: '#/components/parameters/todate_EV01'
- $ref: '#/components/parameters/dwt_min_EV01'
- $ref: '#/components/parameters/dwt_max_EV01'
- $ref: '#/components/parameters/gt_min_EV01'
- $ref: '#/components/parameters/gt_max_EV01'
- $ref: '#/components/parameters/market_EV01'
- $ref: '#/components/parameters/msgtype_EV01'
- $ref: '#/components/parameters/protocol_new'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/200_ev01_default'
- $ref: '#/components/schemas/200_ev01_extended'
application/xml:
schema:
oneOf:
- $ref: '#/components/schemas/200_ev01_default'
- $ref: '#/components/schemas/200_ev01_extended'
examples:
Default:
summary: Simple
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<PORTCALLS>\n <PORTCALL SHIP_ID=\"\
3726902\" IMO=\"9320556\" MMSI=\"310624000\" SHIPNAME=\"QUEEN VICTORIA\" TIMESTAMP_LT=\"2020-10-19T20:56:00\"\
\ TIMESTAMP_UTC=\"2020-10-19T19:56:00\" MOVE_TYPE=\"1\" TYPE_NAME=\"Passenger Ship\" PORT_ID=\"22541\"\
\ PORT_NAME=\"PORTLAND UK ANCH\" PORT_COUNTRY_CODE=\"\" PORT_UNLOCODE=\"\" MARKET=\"\"/>\n <PORTCALL\
\ SHIP_ID=\"3726902\" IMO=\"9320556\" MMSI=\"310624000\" SHIPNAME=\"QUEEN VICTORIA\" TIMESTAMP_LT=\"2020-10-19T04:11:00\"\
\ TIMESTAMP_UTC=\"2020-10-19T03:11:00\" MOVE_TYPE=\"0\" TYPE_NAME=\"Passenger Ship\" PORT_ID=\"22541\"\
\ PORT_NAME=\"PORTLAND UK ANCH\" PORT_COUNTRY_CODE=\"\" PORT_UNLOCODE=\"\" MARKET=\"\"/>\n</PORTCALLS>"
Extended:
summary: Extended
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<PORTCALLS>\n <PORTCALL SHIP_ID=\"\
3726902\" IMO=\"9320556\" MMSI=\"310624000\" SHIPNAME=\"QUEEN VICTORIA\" MOVE_TYPE=\"1\" TYPE_NAME=\"\
Passenger Ship\" DRAUGHT=\"80\" INTRANSIT=\"0\" DISTANCE_TRAVELLED=\"121\" VOYAGE_SPEED_AVG=\"\" VOYAGE_SPEED_MAX=\"\
\" VOYAGE_IDLE_TIME_MINS=\"\" ELAPSED_NOANCH=\"4444\" PORT_ID=\"22541\" PORT_NAME=\"PORTLAND UK ANCH\"\
\ PORT_COUNTRY_CODE=\"\" PORT_LAT=\"\" PORT_LON=\"\" PORT_UNLOCODE=\"\" TIMESTAMP_LT=\"2020-10-19T20:56:00\"\
\ TIMESTAMP_UTC=\"2020-10-19T19:56:00\" MARKET=\"\"/>\n <PORTCALL SHIP_ID=\"3726902\" IMO=\"9320556\"\
\ MMSI=\"310624000\" SHIPNAME=\"QUEEN VICTORIA\" MOVE_TYPE=\"0\" TYPE_NAME=\"Passenger Ship\" DRAUGHT=\"\
80\" INTRANSIT=\"0\" DISTANCE_TRAVELLED=\"121\" VOYAGE_SPEED_AVG=\"105\" VOYAGE_SPEED_MAX=\"197\" VOYAGE_IDLE_TIME_MINS=\"\
2754\" ELAPSED_NOANCH=\"3439\" PORT_ID=\"22541\" PORT_NAME=\"PORTLAND UK ANCH\" PORT_COUNTRY_CODE=\"\"\
\ PORT_LAT=\"\" PORT_LON=\"\" PORT_UNLOCODE=\"\" TIMESTAMP_LT=\"2020-10-19T04:11:00\" TIMESTAMP_UTC=\"\
2020-10-19T03:11:00\" MARKET=\"\"/>\n</PORTCALLS>"
'400':
description: Bad Request
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/400_ev01_date_range_out_of_bounds'
- $ref: '#/components/schemas/400_ev01_missing_ship_identifier'
- $ref: '#/components/schemas/400_ev01_polling_range_out_of_limit'
application/xml:
schema:
oneOf:
- $ref: '#/components/schemas/400_ev01_date_range_out_of_bounds'
- $ref: '#/components/schemas/400_ev01_missing_ship_identifier'
- $ref: '#/components/schemas/400_ev01_polling_range_out_of_limit'
examples:
Date range out of bounds:
summary: Date range out of bounds
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<RESPONSE>\n <STATUS>\n \
\ <ERROR CODE=\"1g\" DESCRIPTION=\"DATE RANGE OUT OF BOUNDS\"/>\n </STATUS>\n</RESPONSE>"
Missing ship identifier:
summary: Missing ship identifier
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<RESPONSE>\n <STATUS>\n \
\ <ERROR CODE=\"2a\" DESCRIPTION=\"VESSEL MMSI OR IMO OR SHIPID OR PORTID OR UNLOCODE MISSING\"/>\n \
\ </STATUS>\n</RESPONSE>"
Polling range out of limit:
summary: Polling range out of limit
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<RESPONSE>\n <STATUS>\n \
\ <ERROR CODE=\"1f\" DESCRIPTION=\"POLLING RANGE MAXIMUM IS 190 DAYS\"/>\n </STATUS>\n</RESPONSE>"
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/429_too_many_requests'
application/xml:
schema:
$ref: '#/components/schemas/429_too_many_requests'
examples:
Area out of bound:
summary: Too Many Requests
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<RESPONSE>\n <STATUS>\n \
\ <ERROR CODE=\"1r\" DESCRIPTION=\"TOO MANY REQUESTS\"/>\n </STATUS>\n</RESPONSE>"
/vesselevents/{api_key}:
get:
tags:
- Single Vessel Events
summary: Single Vessel Events
description: "Get event based intelligence for a vessel. </br></br> <b>Notes</b> <ul>\n <li>Here is a <a href=\"\
https://support.marinetraffic.com/en/articles/9552887-what-is-the-significance-of-the-marinetraffic-events\">COMPLETE\
\ LIST OF EVENT TYPES</a> available for this endpoint. You can use these as values for the **event_type** query parameter.\
\ </li>\n <li>Information about <a href=\"https://support.marinetraffic.com/en/articles/9552860-what-kind-of-information-is-ais-transmitted\"\
>AIS-transmitted data</a></li>\n <li>The <b>frequency of allowed API calls</b> is specific to your API key and\
\ is detailed in your contract as a number of successful calls per time period. For example “2 calls per minute”.\
\ </br>Regardless of this agreed limit, each API key is technically restricted to a maximum of 100 total (including\
\ successful and unsuccessful) requests per minute to ensure system stability.</li>"
operationId: vesselevents
parameters:
- $ref: '#/components/parameters/api_key'
- $ref: '#/components/parameters/v_EV02'
- $ref: '#/components/parameters/shipid_EV02'
- $ref: '#/components/parameters/mmsi_EV02'
- $ref: '#/components/parameters/imo_EV02'
- $ref: '#/components/parameters/timespan_EV02'
- $ref: '#/components/parameters/fromdate_EV02'
- $ref: '#/components/parameters/todate_EV02'
- $ref: '#/components/parameters/event_type_EV02'
- $ref: '#/components/parameters/limit_events_EV02'
- $ref: '#/components/parameters/protocol_new'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/200_ev02_default'
application/xml:
schema:
$ref: '#/components/schemas/200_ev02_default'
examples:
Default:
summary: Simple
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<EVENTS>\n <EVENT SHIPNAME=\"QUEEN\
\ VICTORIA\" MMSI=\"310624000\" IMO=\"\" SHIP_ID=\"\" EVENT_ID=\"1\" EVENT_NAME=\"FIRST_DAILY_POS\" EVENT_CONTENT=\"\
At N 50° 12' 06.53'' - W 002° 41' 31.37''\" TIMESTAMP=\"2020-10-20T00:13:00\"/>\n <EVENT SHIPNAME=\"\
QUEEN VICTORIA\" MMSI=\"310624000\" IMO=\"\" SHIP_ID=\"\" EVENT_ID=\"6\" EVENT_NAME=\"UNDERWAY\" EVENT_CONTENT=\"\
At N 50° 35' 15.59'' - W 002° 21' 27.11''\" TIMESTAMP=\"2020-10-19T19:56:00\"/>\n <EVENT SHIPNAME=\"\
QUEEN VICTORIA\" MMSI=\"310624000\" IMO=\"\" SHIP_ID=\"\" EVENT_ID=\"16\" EVENT_NAME=\"STATUS_CHANGED\"\
\ EVENT_CONTENT=\"From [At Anchor] To [Underway using Engine]\" TIMESTAMP=\"2020-10-19T19:51:00\"/>\n\
\ <EVENT SHIPNAME=\"QUEEN VICTORIA\" MMSI=\"310624000\" IMO=\"\" SHIP_ID=\"\" EVENT_ID=\"13\" EVENT_NAME=\"\
DESTINATION_CHANGED\" EVENT_CONTENT=\"From [GB WEYMOUTH BAY] To [GBSOU]\" TIMESTAMP=\"2020-10-19T18:57:00\"\
/>\n <EVENT SHIPNAME=\"QUEEN VICTORIA\" MMSI=\"310624000\" IMO=\"\" SHIP_ID=\"\" EVENT_ID=\"15\" EVENT_NAME=\"\
ETA_CHANGED\" EVENT_CONTENT=\"From [2020-10-17 05:00] To [2020-10-20 21:00]\" TIMESTAMP=\"2020-10-19T18:57:00\"\
/>\n</EVENTS>"
'400':
description: Bad Request
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/400_ev02_invalid_date_range'
- $ref: '#/components/schemas/400_ev02_missing_ship_identifier'
- $ref: '#/components/schemas/400_ev02_polling_range_out_of_limit'
application/xml:
schema:
oneOf:
- $ref: '#/components/schemas/400_ev02_invalid_date_range'
- $ref: '#/components/schemas/400_ev02_missing_ship_identifier'
- $ref: '#/components/schemas/400_ev02_polling_range_out_of_limit'
examples:
Invalid date range:
summary: Invalid date range
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<RESPONSE>\n <STATUS>\n \
\ <ERROR CODE=\"1g\" DESCRIPTION=\"DATE RANGE OUT OF BOUNDS\"/>\n </STATUS>\n</RESPONSE>"
Missing ship identifier:
summary: Missing ship identifier
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<RESPONSE>\n <STATUS>\n \
\ <ERROR CODE=\"2a\" DESCRIPTION=\"VESSEL MMSI OR IMO OR SHIPID OR PORTID OR UNLOCODE MISSING\"/>\n \
\ </STATUS>\n</RESPONSE>"
Polling range out of limit:
summary: Polling range out of limit
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<RESPONSE>\n <STATUS>\n \
\ <ERROR CODE=\"1f\" DESCRIPTION=\"POLLING RANGE MAXIMUM IS 190 DAYS\"/>\n </STATUS>\n</RESPONSE>"
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/429_too_many_requests'
application/xml:
schema:
$ref: '#/components/schemas/429_too_many_requests'
examples:
Area out of bound:
summary: Too Many Requests
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<RESPONSE>\n <STATUS>\n \
\ <ERROR CODE=\"1r\" DESCRIPTION=\"TOO MANY REQUESTS\"/>\n </STATUS>\n</RESPONSE>"
/berth-calls/{api_key}:
get:
tags:
- Single Vessel Events
summary: Single Vessel Berth Calls
description: "Get berth arrival and departure information for a specific vessel. </br></br> <b>Notes</b> <ul>\n <li>Data\
\ is available for dates **after** 2017-07-03</li>\n <li>Information about <a href=\"https://support.marinetraffic.com/en/articles/9552860-what-kind-of-information-is-ais-transmitted\"\
>AIS-transmitted data</a></li>\n <li>More information about input parameters: <a href=\"https://support.marinetraffic.com/en/articles/9552918-how-does-marinetraffic-categorise-commercial-market-and-commercial-size-class\"\
>MARKET</a>, <a href=\"https://support.marinetraffic.com/en/articles/9552918-how-does-marinetraffic-categorise-commercial-market-and-commercial-size-class\"\
>SHIPCLASS</a></li>\n <li>The <b>frequency of allowed API calls</b> is specific to your API key and is detailed\
\ in your contract as a number of successful calls per time period. For example “2 calls per minute”. </br>Regardless\
\ of this agreed limit, each API key is technically restricted to a maximum of 100 total (including successful and\
\ unsuccessful) requests per minute to ensure system stability.</li>\n</ul>"
operationId: berth-calls
parameters:
- $ref: '#/components/parameters/api_key'
- $ref: '#/components/parameters/v_EV03'
- $ref: '#/components/parameters/shipid_EV03'
- $ref: '#/components/parameters/mmsi_EV03'
- $ref: '#/components/parameters/imo_EV03'
- $ref: '#/components/parameters/timespan_EV03'
- $ref: '#/components/parameters/fromdate_EV03'
- $ref: '#/components/parameters/todate_EV03'
- $ref: '#/components/parameters/market_EV03'
- $ref: '#/components/parameters/shipclass_EV03'
- $ref: '#/components/parameters/dwt_min_EV03'
- $ref: '#/components/parameters/dwt_max_EV03'
- $ref: '#/components/parameters/gt_min_EV03'
- $ref: '#/components/parameters/gt_max_EV03'
- $ref: '#/components/parameters/movetype_EV03'
- $ref: '#/components/parameters/protocol_new'
- $ref: '#/components/parameters/msgtype_EV03'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/200_ev03_default'
- $ref: '#/components/schemas/200_ev03_extended'
application/xml:
schema:
oneOf:
- $ref: '#/components/schemas/200_ev03_default'
- $ref: '#/components/schemas/200_ev03_extended'
examples:
Default:
summary: Simple
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<BERTHCALLS>\n <BERTHCALL SHIP_ID=\"\
371681\" MMSI=\"310627000\" IMO=\"9241061\" DOCK_TIMESTAMP_LT=\"2020-10-14 07:18:00\" DOCK_TIMESTAMP_UTC=\"\
2020-10-14 06:18:00\" DOCK_TIMESTAMP_OFFSET=\"1.000000\" UNDOCK_TIMESTAMP_LT=\"2020-10-14 17:46:00\" UNDOCK_TIMESTAMP_UTC=\"\
2020-10-14 16:46:00\" UNDOCK_TIMESTAMP_OFFSET=\"1.000000\" SHIPNAME=\"QUEEN MARY 2\" TYPE_NAME=\"Passenger\
\ Ship\" DWT=\"19189\" GRT=\"149215\" FLAG=\"BM\" YEAR_BUILT=\"2003\" BERTH_ID=\"923\" BERTH_NAME=\"Berth\
\ 101\" TERMINAL_ID=\"1288\" TERMINAL_NAME=\"City Cruise Terminal\" PORT_ID=\"106\" PORT_NAME=\"SOUTHAMPTON\"\
\ PORT_UNLOCODE=\"GBSOU\" PORT_COUNTRY_CODE=\"GB\" DESTINATION_ID=\"\" DESTINATION=\"\" MARKET=\"\"/>\n\
</BERTHCALLS>"
Extended:
summary: Extended
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<BERTHCALLS>\n <BERTHCALL SHIP_ID=\"\
371681\" MMSI=\"310627000\" IMO=\"9241061\" DOCK_TIMESTAMP_LT=\"2020-10-14 07:18:00\" DOCK_TIMESTAMP_UTC=\"\
2020-10-14 06:18:00\" DOCK_TIMESTAMP_OFFSET=\"1.000000\" UNDOCK_TIMESTAMP_LT=\"2020-10-14 17:46:00\" UNDOCK_TIMESTAMP_UTC=\"\
2020-10-14 16:46:00\" UNDOCK_TIMESTAMP_OFFSET=\"1.000000\" SHIPNAME=\"QUEEN MARY 2\" TYPE_NAME=\"Passenger\
\ Ship\" DWT=\"19189\" GRT=\"149215\" FLAG=\"BM\" YEAR_BUILT=\"2003\" BERTH_ID=\"923\" BERTH_NAME=\"Berth\
\ 101\" TERMINAL_ID=\"1288\" TERMINAL_NAME=\"City Cruise Terminal\" PORT_ID=\"106\" PORT_NAME=\"SOUTHAMPTON\"\
\ PORT_UNLOCODE=\"GBSOU\" PORT_COUNTRY_CODE=\"GB\" DESTINATION_ID=\"\" DESTINATION=\"\" ARR_TIMESTAMP_LT=\"\
2020-10-14 06:26:00\" ARR_TIMESTAMP_UTC=\"2020-10-14 05:26:00\" ARR_DRAUGHT=\"101\" ARR_LOAD_STATUS=\"\
0\" DISTANCE_TRAVELLED=\"439\" VOYAGE_SPEED_AVG=\"106\" VOYAGE_SPEED_MAX=\"155\" VOYAGE_IDLE_TIME_MINS=\"\
37120\" PREVIOUS_NOANCH_ID=\"106\" PREVIOUS_NOANCH_TIMESTAMP=\"2020-09-16 17:22:00\" MARKET=\"\" PREVIOUS_NOANCH_NAME=\"\
SOUTHAMPTON\" ELAPSED_NOANCH=\"39604\" DEP_TIMESTAMP_LT=\"2020-10-14 18:00:00\" DEP_TIMESTAMP_UTC=\"2020-10-14\
\ 17:00:00\" DEP_DRAUGHT=\"101\" DEP_LOAD_STATUS=\"0\" PORT_OPERATION=\"0\" TIME_AT_BERTH=\"628\" TIME_AT_PORT=\"\
694\"/>\n</BERTHCALLS>"
'400':
description: Bad Request
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/400_ev03_date_range_out_of_bounds'
- $ref: '#/components/schemas/400_ev03_missing_ship_identifier'
- $ref: '#/components/schemas/400_ev03_polling_range_out_of_limit'
application/xml:
schema:
oneOf:
- $ref: '#/components/schemas/400_ev03_date_range_out_of_bounds'
- $ref: '#/components/schemas/400_ev03_missing_ship_identifier'
- $ref: '#/components/schemas/400_ev03_polling_range_out_of_limit'
examples:
Date range out of bounds:
summary: Date range out of bounds
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<RESPONSE>\n <STATUS>\n \
\ <ERROR CODE=\"1g\" DESCRIPTION=\"DATE RANGE OUT OF BOUNDS\"/>\n </STATUS>\n</RESPONSE>"
Missing ship identifier:
summary: Missing ship identifier
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<RESPONSE>\n <STATUS>\n \
\ <ERROR CODE=\"2a8\" DESCRIPTION=\"VESSEL MMSI OR IMO OR SHIPID OR PORTID OR UNLOCODE OR BERTHID OR TERMINALID\
\ MISSING\"/>\n </STATUS>\n</RESPONSE>"
Polling range out of limit:
summary: Polling range out of limit
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<RESPONSE>\n <STATUS>\n \
\ <ERROR CODE=\"1m\" DESCRIPTION=\"POLLING RANGE EXCEEDED BY 15 DAYS\"/>\n </STATUS>\n</RESPONSE>"
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/429_too_many_requests'
application/xml:
schema:
$ref: '#/components/schemas/429_too_many_requests'
examples:
Area out of bound:
summary: Too Many Requests
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<RESPONSE>\n <STATUS>\n \
\ <ERROR CODE=\"1r\" DESCRIPTION=\"TOO MANY REQUESTS\"/>\n </STATUS>\n</RESPONSE>"
'/portcalls/{api_key} ':
get:
tags:
- Port Events
summary: Port Calls
description: "Retrieve arrival and departure information at a specific port for a specific period of time. </br></br>\
\ <b>Notes</b> <ul>\n <li>Data is available for dates **after** 2015-01-16</li>\n <li>Information about <a href=\"\
https://support.marinetraffic.com/en/articles/9552860-what-kind-of-information-is-ais-transmitted\">AIS-transmitted\
\ data</a></li>\n <li>**MOVE_TYPE** values: 1=Departure, 0=Arrival</li>\n <li>The <b>frequency of allowed API\
\ calls</b> is specific to your API key and is detailed in your contract as a number of successful calls per time\
\ period. For example “2 calls per minute”. </br>Regardless of this agreed limit, each API key is technically restricted\
\ to a maximum of 100 total (including successful and unsuccessful) requests per minute to ensure system stability.</li>\n\
</ul>"
operationId: portcalls_
parameters:
- $ref: '#/components/parameters/api_key'
- $ref: '#/components/parameters/v_EV01'
- $ref: '#/components/parameters/portid_EV01'
- $ref: '#/components/parameters/timespan_EV01'
- $ref: '#/components/parameters/movetype_EV01'
- $ref: '#/components/parameters/exclude_intransit_EV01'
- $ref: '#/components/parameters/fromdate_EV01'
- $ref: '#/components/parameters/todate_EV01'
- $ref: '#/components/parameters/dwt_min_EV01'
- $ref: '#/components/parameters/dwt_max_EV01'
- $ref: '#/components/parameters/gt_min_EV01'
- $ref: '#/components/parameters/gt_max_EV01'
- $ref: '#/components/parameters/market_EV01'
- $ref: '#/components/parameters/msgtype_EV01'
- $ref: '#/components/parameters/protocol_new'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/200_ev01_default'
- $ref: '#/components/schemas/200_ev01_extended'
application/xml:
schema:
oneOf:
- $ref: '#/components/schemas/200_ev01_default'
- $ref: '#/components/schemas/200_ev01_extended'
examples:
Default:
summary: Simple
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<PORTCALLS>\n <PORTCALL SHIP_ID=\"\
3351323\" IMO=\"0\" MMSI=\"244770588\" SHIPNAME=\"PIETERNELLA\" TIMESTAMP_LT=\"2020-10-20T12:15:00\" TIMESTAMP_UTC=\"\
2020-10-20T10:15:00\" MOVE_TYPE=\"0\" TYPE_NAME=\"Inland, Unknown\" PORT_ID=\"1766\" PORT_NAME=\"AMSTERDAM\"\
\ PORT_COUNTRY_CODE=\"\" PORT_UNLOCODE=\"\" MARKET=\"\"/>\n <PORTCALL SHIP_ID=\"241767\" IMO=\"0\"\
\ MMSI=\"244690666\" SHIPNAME=\"BRABANT\" TIMESTAMP_LT=\"2020-10-20T12:14:00\" TIMESTAMP_UTC=\"2020-10-20T10:14:00\"\
\ MOVE_TYPE=\"1\" TYPE_NAME=\"Inland, Motor Freighter\" PORT_ID=\"1766\" PORT_NAME=\"AMSTERDAM\" PORT_COUNTRY_CODE=\"\
\" PORT_UNLOCODE=\"\" MARKET=\"\"/>\n <PORTCALL SHIP_ID=\"239646\" IMO=\"9553658\" MMSI=\"244670642\"\
\ SHIPNAME=\"WESSEL\" TIMESTAMP_LT=\"2020-10-20T12:13:00\" TIMESTAMP_UTC=\"2020-10-20T10:13:00\" MOVE_TYPE=\"\
0\" TYPE_NAME=\"Inland, Motor Freighter\" PORT_ID=\"1766\" PORT_NAME=\"AMSTERDAM\" PORT_COUNTRY_CODE=\"\
\" PORT_UNLOCODE=\"\" MARKET=\"\"/>\n <PORTCALL SHIP_ID=\"5866042\" IMO=\"0\" MMSI=\"244184725\" SHIPNAME=\"\
AMSTEL\" TIMESTAMP_LT=\"2020-10-20T12:11:00\" TIMESTAMP_UTC=\"2020-10-20T10:11:00\" MOVE_TYPE=\"0\" TYPE_NAME=\"\
Inland, Motor Tanker, liquid cargo, type C\" PORT_ID=\"1766\" PORT_NAME=\"AMSTERDAM\" PORT_COUNTRY_CODE=\"\
\" PORT_UNLOCODE=\"\" MARKET=\"\"/>\n</PORTCALLS>"
Extended:
summary: Extended
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<PORTCALLS>\n <PORTCALL SHIP_ID=\"\
213996\" IMO=\"9038232\" MMSI=\"240897000\" SHIPNAME=\"AEGEAN ACE\" MOVE_TYPE=\"1\" TYPE_NAME=\"Bunkering\
\ Tanker\" DRAUGHT=\"59\" INTRANSIT=\"0\" DISTANCE_TRAVELLED=\"0\" VOYAGE_SPEED_AVG=\"\" VOYAGE_SPEED_MAX=\"\
\" VOYAGE_IDLE_TIME_MINS=\"\" ELAPSED_NOANCH=\"672\" PORT_ID=\"1\" PORT_NAME=\"PIRAEUS\" PORT_COUNTRY_CODE=\"\
\" PORT_LAT=\"\" PORT_LON=\"\" PORT_UNLOCODE=\"GRPIR\" TIMESTAMP_LT=\"2020-10-20T13:24:00\" TIMESTAMP_UTC=\"\
2020-10-20T10:24:00\" MARKET=\"\"/>\n <PORTCALL SHIP_ID=\"233849\" IMO=\"0\" MMSI=\"244630019\" SHIPNAME=\"\
EEMSTROOM\" MOVE_TYPE=\"0\" TYPE_NAME=\"Inland, Motor Tanker, liquid cargo, type N\" DRAUGHT=\"18\" INTRANSIT=\"\
0\" DISTANCE_TRAVELLED=\"76\" VOYAGE_SPEED_AVG=\"86\" VOYAGE_SPEED_MAX=\"102\" VOYAGE_IDLE_TIME_MINS=\"\
525\" ELAPSED_NOANCH=\"1057\" PORT_ID=\"1766\" PORT_NAME=\"AMSTERDAM\" PORT_COUNTRY_CODE=\"\" PORT_LAT=\"\
\" PORT_LON=\"\" PORT_UNLOCODE=\"NLAMS\" TIMESTAMP_LT=\"2020-10-20T12:23:00\" TIMESTAMP_UTC=\"2020-10-20T10:23:00\"\
\ MARKET=\"\"/>\n <PORTCALL SHIP_ID=\"5567750\" IMO=\"0\" MMSI=\"237710500\" SHIPNAME=\"PILOT BOAT\
\ PY56\" MOVE_TYPE=\"1\" TYPE_NAME=\"Pilot Vessel\" DRAUGHT=\"0\" INTRANSIT=\"0\" DISTANCE_TRAVELLED=\"\
0\" VOYAGE_SPEED_AVG=\"\" VOYAGE_SPEED_MAX=\"\" VOYAGE_IDLE_TIME_MINS=\"\" ELAPSED_NOANCH=\"72\" PORT_ID=\"\
1\" PORT_NAME=\"PIRAEUS\" PORT_COUNTRY_CODE=\"\" PORT_LAT=\"\" PORT_LON=\"\" PORT_UNLOCODE=\"GRPIR\" TIMESTAMP_LT=\"\
2020-10-20T13:22:00\" TIMESTAMP_UTC=\"2020-10-20T10:22:00\" MARKET=\"\"/>\n</PORTCALLS>"
'400':
description: Bad Request
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/400_ev01_date_range_out_of_bounds'
- $ref: '#/components/schemas/400_ev01_missing_port_identifier'
- $ref: '#/components/schemas/400_ev01_polling_range_out_of_limit'
application/xml:
schema:
oneOf:
- $ref: '#/components/schemas/400_ev01_date_range_out_of_bounds'
- $ref: '#/components/schemas/400_ev01_missing_port_identifier'
- $ref: '#/components/schemas/400_ev01_polling_range_out_of_limit'
examples:
Date range out of bounds:
summary: Date range out of bounds
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<RESPONSE>\n <STATUS>\n \
\ <ERROR CODE=\"1g\" DESCRIPTION=\"DATE RANGE OUT OF BOUNDS\"/>\n </STATUS>\n</RESPONSE>"
Missing port identifier:
summary: Missing port identifier
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<RESPONSE>\n <STATUS>\n \
\ <ERROR CODE=\"2a\" DESCRIPTION=\"VESSEL MMSI OR IMO OR SHIPID OR PORTID OR UNLOCODE MISSING\"/>\n \
\ </STATUS>\n</RESPONSE>"
Polling range out of limit:
summary: Polling range out of limit
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<RESPONSE>\n <STATUS>\n \
\ <ERROR CODE=\"1f\" DESCRIPTION=\"POLLING RANGE MAXIMUM IS 190 DAYS\"/>\n </STATUS>\n</RESPONSE>"
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/429_too_many_requests'
application/xml:
schema:
$ref: '#/components/schemas/429_too_many_requests'
examples:
Area out of bound:
summary: Too Many Requests
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<RESPONSE>\n <STATUS>\n \
\ <ERROR CODE=\"1r\" DESCRIPTION=\"TOO MANY REQUESTS\"/>\n </STATUS>\n</RESPONSE>"
'/berth-calls/{api_key} ':
get:
tags:
- Port Events
summary: Berth Calls
description: "Retrieve arrival and departure information at a specific port, berth or terminal, for a specific period\
\ of time. </br></br> <b>Notes</b> <ul>\n <li>Data is available for dates **after** 2017-07-03</li>\n <li>Information\
\ about <a href=\"https://support.marinetraffic.com/en/articles/9552860-what-kind-of-information-is-ais-transmitted\"\
>AIS-transmitted data</a></li>\n <li>More information about input parameters: <a href=\"https://support.marinetraffic.com/en/articles/9552918-how-does-marinetraffic-categorise-commercial-market-and-commercial-size-class\"\
>MARKET</a>, <a href=\"https://support.marinetraffic.com/en/articles/9552918-how-does-marinetraffic-categorise-commercial-market-and-commercial-size-class\"\
>SHIPCLASS</a></li>\n <li>The <b>frequency of allowed API calls</b> is specific to your API key and is detailed\
\ in your contract as a number of successful calls per time period. For example “2 calls per minute”. </br>Regardless\
\ of this agreed limit, each API key is technically restricted to a maximum of 100 total (including successful and\
\ unsuccessful) requests per minute to ensure system stability.</li>\n</ul>"
operationId: berth-calls_
parameters:
- $ref: '#/components/parameters/api_key'
- $ref: '#/components/parameters/v_EV03'
- $ref: '#/components/parameters/portid_EV03'
- $ref: '#/components/parameters/port_unlocode_EV03'
- $ref: '#/components/parameters/berthid_EV03'
- $ref: '#/components/parameters/terminalid_EV03'
- $ref: '#/components/parameters/timespan_EV03'
- $ref: '#/components/parameters/fromdate_EV03'
- $ref: '#/components/parameters/todate_EV03'
- $ref: '#/components/parameters/market_EV03'
- $ref: '#/components/parameters/shipclass_EV03'
- $ref: '#/components/parameters/dwt_min_EV03'
- $ref: '#/components/parameters/dwt_max_EV03'
- $ref: '#/components/parameters/gt_min_EV03'
- $ref: '#/components/parameters/gt_max_EV03'
- $ref: '#/components/parameters/movetype_EV03'
- $ref: '#/components/parameters/protocol_new'
- $ref: '#/components/parameters/msgtype_EV03'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/200_ev03_default'
- $ref:
# --- truncated at 32 KB (134 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/marine-traffic/refs/heads/main/openapi/marine-traffic-events-openapi.yml