openapi: 3.0.2
info:
title: MarineTraffic Events AIS API Routing Information 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: Routing Information
paths:
/exportroutes/{api_key}:
get:
tags:
- Routing Information
summary: Vessel Route to Port
description: "<b>A newer version of this endpoint is available here: https://developers.kpler.com/spec/c78f79cf-4169-4a59-987d-e5970ea170f9</b></br></br>\nReceive a list of available routes and distances from a vessel to a port.</br></br> <b>Notes</b> <ul>\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: exportroutes
parameters:
- $ref: '#/components/parameters/api_key'
- $ref: '#/components/parameters/mmsi_VI03'
- $ref: '#/components/parameters/imo_VI03'
- $ref: '#/components/parameters/shipid_VI03'
- $ref: '#/components/parameters/port_target_id_VI03'
- $ref: '#/components/parameters/includealternatives_VI03'
- $ref: '#/components/parameters/includeinland_VI03'
- $ref: '#/components/parameters/msgtype_VI03'
- $ref: '#/components/parameters/protocol'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/200_vi03_default'
- $ref: '#/components/schemas/200_vi03_extended'
application/xml:
schema:
oneOf:
- $ref: '#/components/schemas/200_vi03_default'
- $ref: '#/components/schemas/200_vi03_extended'
examples:
Default:
summary: Simple
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<ROUTES>\n <route DISTANCE=\"805\" PANAMA=\"0\" SUEZ=\"0\"/>\n</ROUTES>"
Extended:
summary: Extended
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<ROUTES>\n <route DISTANCE=\"805\" PANAMA=\"0\" SUEZ=\"0\" FINAL_PATH=\"LINESTRING (23.6107 37.894, 23.6096 37.3631, 23.6088 37.3566, 23.499 36.9011, 23.4958 36.8932, 23.2212 36.4084, 23.2122 36.398, 23.198 36.3904, 23.1812 36.3877, 23.1763 36.3879, 23.0774 36.3967, 23.0753 36.397, 22.9465 36.4138, 22.9395 36.4142, 22.9285 36.4142, 22.9211 36.4137, 22.4744 36.3528, 22.467 36.3523, 22.4502 36.355, 22.4457 36.3568, 21.7536 36.6658, 21.7463 36.6699, 21.6694 36.7227, 21.6638 36.7273, 20.5872 37.7853, 20.5847 37.788, 18.5047 40.2326, 18.503 40.2344, 18.2613 40.4772, 18.2613 40.4772, 13.7529 44.8308, 13.7497 44.8342, 13.5739 45.0519, 13.5702 45.0579, 13.4989 45.2161)\"/>\n</ROUTES>"
'400':
description: Bad Request
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/400_vi03_invalid_ship_identifier'
- $ref: '#/components/schemas/400_vi03_missing_or_invalid_port_identifier'
application/xml:
schema:
oneOf:
- $ref: '#/components/schemas/400_vi03_invalid_ship_identifier'
- $ref: '#/components/schemas/400_vi03_missing_or_invalid_port_identifier'
examples:
Invalid ship identifier:
summary: Invalid ship identifier
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<RESPONSE>\n <STATUS>\n <ERROR CODE=\"2\" DESCRIPTION=\"VESSEL MMSI OR IMO OR SHIPID MISSING\"/>\n </STATUS>\n</RESPONSE>"
Missing or invalid port identifier:
summary: Missing or invalid port identifier
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<RESPONSE>\n <STATUS>\n <ERROR CODE=\"2a6\" DESCRIPTION=\"PORT IS MISSING\"/>\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>"
'/exportroutes/{api_key} ':
get:
tags:
- Routing Information
summary: Distance to Port
description: "<b>A newer version of this endpoint is available here: https://developers.kpler.com/spec/c78f79cf-4169-4a59-987d-e5970ea170f9</b></br></br>\nReceive a list of available routes and distances from point or port to a specific port.</br></br> <b>Notes</b> <ul>\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: exportroutes_
parameters:
- $ref: '#/components/parameters/api_key'
- $ref: '#/components/parameters/port_start_id_VI03'
- $ref: '#/components/parameters/LAT_VI03'
- $ref: '#/components/parameters/LON_VI03'
- $ref: '#/components/parameters/port_target_id_VI03'
- $ref: '#/components/parameters/includealternatives_VI03'
- $ref: '#/components/parameters/includeinland_VI03'
- $ref: '#/components/parameters/msgtype_VI03'
- $ref: '#/components/parameters/protocol'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/200_vi03_default'
- $ref: '#/components/schemas/200_vi03_extended'
application/xml:
schema:
oneOf:
- $ref: '#/components/schemas/200_vi03_default'
- $ref: '#/components/schemas/200_vi03_extended'
examples:
Default:
summary: Simple
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<ROUTES>\n <route DISTANCE=\"2938\" PANAMA=\"0\" SUEZ=\"0\"/>\n</ROUTES>"
Extended:
summary: Extended
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<ROUTES>\n <route DISTANCE=\"2938\" PANAMA=\"0\" SUEZ=\"0\" FINAL_PATH=\"LINESTRING (23.6031 37.9345, 23.6022 37.8302, 23.7127 37.6496, 23.7056 37.6035, 23.6234 37.3639, 23.4216 36.9451, 23.229 36.4224, 23.1209 36.4007, 22.9908 36.4161, 22.8799 36.4056, 22.5453 36.3436, 22.0771 36.3505, 19.8853 36.3859, 17.0453 36.4213, 16.0126 36.4389, 14.5459 36.461, 12.2835 37.0352, 11.0962 37.4966, 10.2338 37.6534, 9.5746 37.6577, 8.8824 37.6447, 7.8552 37.5924, 6.2292 37.4225, 4.3781 37.2391, 3.5815 37.1472, 2.2467 37.0245, 0.1648 36.7609, -1.9391 36.4655, -2.9718 36.3328, -4.021 36.2132, -5.3448 36.0269, -5.5563 35.9713, -5.8612 35.9625, -6.1963 35.9558, -9.0088 36.6948, -9.1681 36.7609, -9.3109 36.884, -9.3713 37.1341, -9.657 38.1043, -9.8602 38.7455, -9.8492 39.0491, -9.8492 39.6818, -9.8383 40.1873, -9.7998 42.3829, -9.7943 42.9444, -9.7778 43.2091, -6.861 47.1486, -5.9876 48.3051, -5.6195 48.7562, -5.1691 48.9442, -4.5428 49.1781, -3.3893 49.6214, -2.9169 49.8026, -2.439 49.8911, -1.5491 50.0501, -0.3571 50.2612, 0.9668 50.4889, 1.3528 50.7125, 1.4177 50.8727, 1.4687 50.906, 1.7071 51.0776, 2.0596 51.2246, 2.2412 51.4745, 3.1406 52.1546, 3.5788 52.4091, 4.1803 52.4844, 4.5456 52.4644, 4.6609 52.4627, 4.6788 52.4526, 4.7173 52.4351, 4.7392 52.4301, 4.7763 52.4251, 4.7955 52.4234, 4.8225 52.4197, 4.8581 52.4147, 4.8793 52.4083, 4.8985 52.389)\"/>\n</ROUTES>"
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/400_vi03_missing_or_invalid_port_identifier'
application/xml:
schema:
$ref: '#/components/schemas/400_vi03_missing_or_invalid_port_identifier'
examples:
Missing or invalid port identifier:
summary: Missing or invalid port identifier
value: "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>\n<RESPONSE>\n <STATUS>\n <ERROR CODE=\"2a6\" DESCRIPTION=\"PORT IS MISSING\"/>\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>"
components:
parameters:
mmsi_VI03:
name: mmsi
in: query
description: The Maritime Mobile Service Identity (MMSI) of the vessel you wish to track </br></br> You can <b>instead</b> use imo or shipid
required: true
schema:
type: integer
LAT_VI03:
name: LAT
in: query
description: The latitude of the starting point </br></br> It can be used together with LON <b>instead</b> of port_start_id
required: false
schema:
type: number
shipid_VI03:
name: shipid
in: query
description: A uniquely assigned ID by MarineTraffic for the subject vessel
required: false
schema:
type: integer
msgtype_VI03:
name: msgtype
in: query
description: "Resolution of the response. Available values: <ul>\n <li>simple</li>\n <li>extended</li>\n</ul> If used with the value <b>extended</b>, the response includes also route/waypoints as Linestring Geometry in WKT - Well-Known Text"
required: false
schema:
type: string
default: simple
includealternatives_VI03:
name: includealternatives
in: query
description: Use 1 to search for all available routes regarding the specific journey or 0 to not include alternative routes
required: false
schema:
type: integer
includeinland_VI03:
name: includeinland
in: query
description: Use 1 in order to receive routes which include inland waterways or 0 to not include alternative routes
required: false
schema:
type: integer
protocol:
name: protocol
in: query
description: "Response type. Use one of the following: <ul>\n <li>xml</li>\n <li>csv</li>\n <li>json</li>\n <li>jsono</li>"
required: false
schema:
type: string
default: xml
port_target_id_VI03:
name: port_target_id
in: query
description: The MarineTraffic ID of the port you wish to put as target port (found on the URL of the respective Port page) or port UN/LOCODE
required: true
schema:
type: integer
imo_VI03:
name: imo
in: query
description: The International Maritime Organization (IMO) number of the vessel you wish to track
required: false
schema:
type: integer
api_key:
name: api_key
in: path
description: 'API key: 40-character hexadecimal number'
required: true
schema:
type: string
LON_VI03:
name: LON
in: query
description: The longitude of the starting point </br></br> It can be used together with LAT <b>instead</b> of port_start_id
required: false
schema:
type: integer
port_start_id_VI03:
name: port_start_id
in: query
description: The MarineTraffic ID of the port you wish to put as starting point (found on the URL of the respective Port page) or port UN/LOCODE
required: true
schema:
type: integer
schemas:
200_vi03_default:
title: Simple
type: array
items:
type: object
properties:
DISTANCE:
type: string
description: The Distance (in NM) between the specified point or port to the destination port
PANAMA:
type: string
description: Flag to indicate whether the vessel route passes via the Panama canal (0:no, 1:yes)
SUEZ:
type: string
description: Flag to indicate whether the vessel route passes via the Suez canal (0:no, 1:yes)
example:
- DISTANCE: '2938'
PANAMA: '0'
SUEZ: '0'
400_vi03_invalid_ship_identifier:
title: Invalid ship identifier
type: object
properties:
errors:
type: array
items:
type: object
properties:
code:
type: string
description: Error code
detail:
type: string
description: Error message
example:
errors:
- code: '2'
detail: VESSEL MMSI OR IMO OR SHIPID MISSING
400_vi03_missing_or_invalid_port_identifier:
title: Missing or invalid port identifier
type: object
properties:
errors:
type: array
items:
type: object
properties:
code:
type: string
description: Error code
detail:
type: string
description: Error message
example:
errors:
- code: 2a6
detail: PORT IS MISSING
429_too_many_requests:
title: Too many requests
type: object
properties:
errors:
type: array
items:
type: object
properties:
code:
type: string
description: Error code
detail:
type: string
description: Error message
example:
errors:
- code: 1r
detail: TOO MANY REQUESTS
200_vi03_extended:
title: Extended
type: array
items:
type: object
properties:
DISTANCE:
type: string
description: The Distance (in NM) between the specified point or port to the destination port
PANAMA:
type: string
description: Flag to indicate whether the vessel route passes via the Panama canal (0:no, 1:yes)
SUEZ:
type: string
description: Flag to indicate whether the vessel route passes via the Suez canal (0:no, 1:yes)
FINAL_PATH:
type: string
description: Route/Waypoints as Linestring Geometry in WKT - Well-Known Text
example:
- DISTANCE: '2938'
PANAMA: '0'
SUEZ: '0'
FINAL_PATH: LINESTRING (23.6031 37.9345, 23.6022 37.8302, 23.7127 37.6496, 23.7056 37.6035, 23.6234 37.3639, 23.4216 36.9451, 23.229 36.4224, 23.1209 36.4007, 22.9908 36.4161, 22.8799 36.4056, 22.5453 36.3436, 22.0771 36.3505, 19.8853 36.3859, 17.0453 36.4213, 16.0126 36.4389, 14.5459 36.461, 12.2835 37.0352, 11.0962 37.4966, 10.2338 37.6534, 9.5746 37.6577, 8.8824 37.6447, 7.8552 37.5924, 6.2292 37.4225, 4.3781 37.2391, 3.5815 37.1472, 2.2467 37.0245, 0.1648 36.7609, -1.9391 36.4655, -2.9718 36.3328, -4.021 36.2132, -5.3448 36.0269, -5.5563 35.9713, -5.8612 35.9625, -6.1963 35.9558, -9.0088 36.6948, -9.1681 36.7609, -9.3109 36.884, -9.3713 37.1341, -9.657 38.1043, -9.8602 38.7455, -9.8492 39.0491, -9.8492 39.6818, -9.8383 40.1873, -9.7998 42.3829, -9.7943 42.9444, -9.7778 43.2091, -6.861 47.1486, -5.9876 48.3051, -5.6195 48.7562, -5.1691 48.9442, -4.5428 49.1781, -3.3893 49.6214, -2.9169 49.8026, -2.439 49.8911, -1.5491 50.0501, -0.3571 50.2612, 0.9668 50.4889, 1.3528 50.7125, 1.4177 50.8727, 1.4687 50.906, 1.7071 51.0776, 2.0596 51.2246, 2.2412 51.4745, 3.1406 52.1546, 3.5788 52.4091, 4.1803 52.4844, 4.5456 52.4644, 4.6609 52.4627, 4.6788 52.4526, 4.7173 52.4351, 4.7392 52.4301, 4.7763 52.4251, 4.7955 52.4234, 4.8225 52.4197, 4.8581 52.4147, 4.8793 52.4083, 4.8985 52.389)