Marine Traffic API Client Python Library

Installation

pip install Marine-Traffic-API

Initialize API

from marinetrafficapi import MarineTrafficApi

api = MarineTrafficApi(api_key="__your_api_key_here__")

Default params

response = api.__api_call_method__(protocol='json'|'jsono'|'csv'|'xml', # default is jsono
                                   msg_type='simple'|'extended',  # default is simple
                                   timeout=10) # default is 5 (5 seconds)

# protocol, msg_type and timeout are call params 
# that could be used in any api call. 
# json protocol is not supported by models, for now.
# extended msg_type returns a lot more data but cost 
# a lot more api credits as well.

response.raw_data  # raw data from api call (json, csv or xml)
response.formatted_data  # data formatted in python's native data types
response.models  # list of model objects representing the data
response.meta # meta data that in some way describes API response

Vessels Positions

(PS01) Vessel History Track

https://www.marinetraffic.com/en/ais-api-services/documentation/api-service:ps01

from marinetrafficapi import MarineTrafficApi

api = MarineTrafficApi(api_key="__your_api_key_here__")

vessel_positions = api.vessel_historical_track(period='daily', 
                                               days=3, 
                                               mmsi=241486000)

# list all possible params with:
MarineTrafficApi.print_params_for('vessel_historical_track')

for position in vessel_positions.models:
	position.mmsi.value
	position.status.value
	position.speed.value
	position.longitude.value
	position.latitude.value
	position.course.value
	position.heading.value
	position.timestamp.value
	position.ship_id.value
	position.wind_angle.value

(PS02) Vessel Positions of a Static Fleet

https://www.marinetraffic.com/en/ais-api-services/documentation/api-service:ps02

from marinetrafficapi import MarineTrafficApi

api = MarineTrafficApi(api_key="__your_api_key_here__")

vessels = api.fleet_vessel_positions(time_span=10)

# list all possible params with:
MarineTrafficApi.print_params_for('fleet_vessel_positions')

for vessel in vessels.models:
	vessel.mmsi.value
	vessel.imo.value
	vessel.ship_id.value
	vessel.longitude.value
	vessel.latitude.value
	vessel.speed.value
	vessel.heading.value
	vessel.status.value
	vessel.course.value
	vessel.timestamp.value
	vessel.dsrc.value
	vessel.utc_seconds.value
	vessel.ship_name.value
	vessel.ship_type.value
	vessel.call_sign.value
	vessel.flag.value
	vessel.length.value
	vessel.width.value
	vessel.grt.value
	vessel.dwt.value
	vessel.draught.value
	vessel.year_built.value
	vessel.rot.value
	vessel.type_name.value
	vessel.ais_type_summary.value
	vessel.destination.value
	vessel.eta.value
	vessel.current_port.value
	vessel.last_port.value
	vessel.last_port_time.value
	vessel.current_port_id.value
	vessel.current_port_unlocode.value
	vessel.current_port_country.value
	vessel.last_port_id.value
	vessel.last_port_unlocode.value
	vessel.last_port_country.value
	vessel.next_port_id.value
	vessel.next_port_unlocode.value
	vessel.next_port_name.value
	vessel.next_port_country.value
	vessel.eta_calc.value
	vessel.eta_updated.value
	vessel.distance_to_go.value
	vessel.distance_travelled.value
	vessel.awg_speed.value
	vessel.max_speed.value

(PS03) Vessel Positions of a Dynamic Fleet

https://www.marinetraffic.com/en/ais-api-services/documentation/api-service:ps03 Same as PS02.

(PS04) Vessel Positions Within a port

https://www.marinetraffic.com/en/ais-api-services/documentation/api-service:ps04 Same as PS02.

(PS05) Vessel Positions in a Predefined Area

https://www.marinetraffic.com/en/ais-api-services/documentation/api-service:ps05 Same as PS02.

(PS06) Vessel Positions in a Predefined Area

https://www.marinetraffic.com/en/ais-api-services/documentation/api-service:ps06

from marinetrafficapi import MarineTrafficApi

api = MarineTrafficApi(api_key="__your_api_key_here__")

vessels = api.fleet_vessel_positions(min_latitude=38.20882,
                                     max_latitude=40.24562,
                                     min_longitude=-6.7749,
                                     max_longitude=-4.13721,
                                     time_span=10)

# list all possible params with:
MarineTrafficApi.print_params_for('fleet_vessel_positions')

for vessel in vessels.models:
	# same as PS02

(PS07) Single Vessel Positions

https://www.marinetraffic.com/en/ais-api-services/documentation/api-service:ps07

from marinetrafficapi import MarineTrafficApi

api = MarineTrafficApi(api_key="__your_api_key_here__")

vessel = api.single_vessel_positions(time_span=20,
                                     mmsi=310627)

# list all possible params with:
MarineTrafficApi.print_params_for('single_vessel_positions')

vessel = vessel.models[0]

vessel.mmsi.value
vessel.imo.value
vessel.longitude.value
vessel.latitude.value
vessel.speed.value
vessel.heading.value
vessel.status.value
vessel.course.value
vessel.timestamp.value
vessel.dsrc.value
vessel.ship_name.value
vessel.ship_type.value
vessel.call_sign.value
vessel.flag.value
vessel.length.value
vessel.width.value
vessel.grt.value
vessel.dwt.value
vessel.draught.value
vessel.year_built.value
vessel.type_name.value
vessel.ais_type_summary.value
vessel.destination.value
vessel.eta.value
vessel.eta_calc.value
vessel.current_port.value
vessel.current_port_id.value
vessel.current_port_unlocode.value
vessel.last_port.value
vessel.last_port_time.value
vessel.last_port_id.value
vessel.last_port_unlocode.value
vessel.next_port_id.value
vessel.next_port_unlocode.value
vessel.next_port_name.value
vessel.next_port_country.value

Events

(EV01) Port Calls

https://www.marinetraffic.com/en/ais-api-services/documentation/api-service:ev01

from marinetrafficapi import MarineTrafficApi

api = MarineTrafficApi(api_key="__your_api_key_here__")

events = api.port_calls(port_id=1,
                        gt_min=4000,
                        dwt_min=9000,
                        timespan=60)

# list all possible params with:
MarineTrafficApi.print_params_for('port_calls')

for event in events.models:
    event.mmsi.value
    event.ship_name.value
    event.ship_id.value
    event.local_timestamp.value
    event.utc_timestamp.value
    event.move_type.value
    event.type_name.value
    event.unlocode.value
    event.draught.value
    event.load_status.value
    event.port_operation.value
    event.in_transit.value
    event.voyage_avg_speed.value
    event.voyage_max_speed.value
    event.voyage_idle_time.value
    event.elapsed_noanch.value

(EV02) Vessel Events

https://www.marinetraffic.com/en/ais-api-services/documentation/api-service:ev02

from marinetrafficapi import MarineTrafficApi

api = MarineTrafficApi(api_key="__your_api_key_here__")

events = api.vessel_events(mmsi=355906000,
                           event_type=19,
                           timespan=160)

# list all possible params with:
MarineTrafficApi.print_params_for('vessel_events')

for event in events.models:
    event.mmsi.value
    event.ship_name.value
    event.timestamp.value
    event.event_id.value
    event.event_name.value
    event.event_content.value

(EV03) Berth Calls

https://www.marinetraffic.com/en/ais-api-services/documentation/api-service:ev03

from marinetrafficapi import MarineTrafficApi

api = MarineTrafficApi(api_key="__your_api_key_here__")

berth_calls = api.berth_calls(dwt_min=2000,
                              dwt_max=70000,
                              timespan=20)

# list all possible params with:
MarineTrafficApi.print_params_for('berth_calls')

for berth_call in berth_calls.models:
    berth_call.ship_id.value
    berth_call.mmsi.value
    berth_call.imo.value
    berth_call.dock_local_time.value
    berth_call.dock_utc_time.value
    berth_call.dock_offset_time.value
    berth_call.undock_local_time.value
    berth_call.undock_utc_time.value
    berth_call.undock_offset_time.value
    berth_call.ship_name.value
    berth_call.type_name.value
    berth_call.grt.value
    berth_call.dwt.value
    berth_call.flag.value
    berth_call.year_built.value
    berth_call.berth_id.value
    berth_call.berth_name.value
    berth_call.terminal_id.value
    berth_call.terminal_name.value
    berth_call.port_name.value
    berth_call.port_id.value
    berth_call.unlocode.value
    berth_call.country_code.value
    berth_call.destination_id.value
    berth_call.destination.value
    berth_call.arrival_local_time.value
    berth_call.arrival_utc_time.value
    berth_call.arrival_draught.value
    berth_call.arrival_load_status.value
    berth_call.distance_travelled.value
    berth_call.voyage_average_speed.value
    berth_call.voyage_max_speed.value
    berth_call.voyage_idle_time.value
    berth_call.origin_name.value
    berth_call.origin_port_id.value
    berth_call.origin_departure_time.value
    berth_call.total_voyage_time.value
    berth_call.departure_local_time.value
    berth_call.departure_utc_time.value
    berth_call.departure_draught.value
    berth_call.departure_load_status.value
    berth_call.port_operation.value
    berth_call.time_at_berth.value
    berth_call.time_at_port.value

Vessels Data

(VD01) Vessel Photos

https://www.marinetraffic.com/en/ais-api-services/documentation/api-service:vd01

from marinetrafficapi import MarineTrafficApi

api = MarineTrafficApi(api_key="__your_api_key_here__")

vessel_photos = api.vessel_photos(vessel_id=310627000)

# list all possible params with:
MarineTrafficApi.print_params_for('vessel_photos')

for vessel_photo in vessel_photos.models:
	vessel_photo.url.value

(VD02) Vessel Particulars

https://www.marinetraffic.com/en/ais-api-services/documentation/api-service:vd02

from marinetrafficapi import MarineTrafficApi

api = MarineTrafficApi(api_key="__your_api_key_here__")

vessel_particulars = api.vessel_particulars(imo=9375783)

# list all possible params with:
MarineTrafficApi.print_params_for('vessel_particulars')

for vessel_particular in vessel_particulars.models:
    vessel_particular.mmsi.value
    vessel_particular.imo.value
    vessel_particular.name.value
    vessel_particular.build_place.value
    vessel_particular.build_year.value
    vessel_particular.breadth_extreme.value
    vessel_particular.summer_dwt.value
    vessel_particular.displacement_summer.value
    vessel_particular.call_sign.value
    vessel_particular.flag.value
    vessel_particular.draught.value
    vessel_particular.overall_length.value
    vessel_particular.fuel_consumption.value
    vessel_particular.max_speed.value
    vessel_particular.condition_speed.value
    vessel_particular.wet_cargo_capacity.value
    vessel_particular.owner.value
    vessel_particular.manager.value
    vessel_particular.vessel_type.value
    vessel_particular.manager_owner.value

(VD03) Search Vessel

https://www.marinetraffic.com/en/ais-api-services/documentation/api-service:vd03

from marinetrafficapi import MarineTrafficApi

api = MarineTrafficApi(api_key="__your_api_key_here__")

vessel = api.search_vessel(imo=9375783)

# list all possible params with:
MarineTrafficApi.print_params_for('search_vessel')

vessel = vessel.models[0]

vessel.id.value
vessel.name.value
vessel.mmsi.value
vessel.imo.value
vessel.call_sign.value
vessel.type_name.value
vessel.dwt.value
vessel.flag.value
vessel.country.value
vessel.build_year.value
vessel.details_page_url.value

Voyage Info

(VI01) Voyage Forecasts

https://www.marinetraffic.com/en/ais-api-services/documentation/api-service:vi01

from marinetrafficapi import MarineTrafficApi

api = MarineTrafficApi(api_key="__your_api_key_here__")

forecasts = api.voyage_forecasts(mmsi=355906000)

# list all possible params with:
MarineTrafficApi.print_params_for('voyage_forecasts')

for forecast in forecasts.models:
	forecast.mmsi.value
    forecast.destination.value
    forecast.last_port_id.value
    forecast.last_port.value
    forecast.last_port_unlocode.value
    forecast.last_port_time.value
    forecast.next_port_id.value
    forecast.next_port_name.value
    forecast.next_port_unlocode.value
    forecast.eta.value
    forecast.eta_calc.value
    forecast.distance_travelled.value
    forecast.distance_to_go.value
    forecast.speed.value
    forecast.draught.value
    forecast.draught_max.value
    forecast.load_status_name.value
    forecast.route.value

(VI02) Expected Arrivals

https://www.marinetraffic.com/en/ais-api-services/documentation/api-service:vi02

from marinetrafficapi import MarineTrafficApi

api = MarineTrafficApi(api_key="__your_api_key_here__")

expected_arrivals = api.expected_arrivals(timespan=2,
                                          country='US',
                                          dwt_min=10000,
                                          dwt_max=160000,
                                          shiptype=7)

# list all possible params with:
MarineTrafficApi.print_params_for('expected_arrivals')

for expected_arrival in expected_arrivals.models:
	expected_arrival.imo.value
    expected_arrival.mmsi.value
    expected_arrival.ship_name.value
    expected_arrival.type_name.value
    expected_arrival.ship_type.value
    expected_arrival.call_sign.value
    expected_arrival.flag.value
    expected_arrival.length.value
    expected_arrival.width.value
    expected_arrival.draught.value
    expected_arrival.grt.value
    expected_arrival.dwt.value
    expected_arrival.year_built.value
    expected_arrival.latitude.value
    expected_arrival.longitude.value
    expected_arrival.speed.value
    expected_arrival.course.value
    expected_arrival.status.value
    expected_arrival.eta.value
    expected_arrival.eta_calc.value
    expected_arrival.eta_updated.value
    expected_arrival.last_port_id.value
    expected_arrival.last_port.value
    expected_arrival.last_port_unlocode.value
    expected_arrival.last_port_country.value
    expected_arrival.last_port_time.value
    expected_arrival.port_id.value
    expected_arrival.port_unlocode.value
    expected_arrival.current_port.value
    expected_arrival.current_port_country.value
    expected_arrival.next_port_id.value
    expected_arrival.next_port_unlocode.value
    expected_arrival.next_port_name.value
    expected_arrival.next_port_country.value
    expected_arrival.timestamp.value

(VI03) Port Distance and Routes

https://www.marinetraffic.com/en/ais-api-services/documentation/api-service:vi03

from marinetrafficapi import MarineTrafficApi

api = MarineTrafficApi(api_key="__your_api_key_here__")

routes = api.port_distances_and_routes(port_start_id=1, 
                                       port_target_id=10, 
                                       include_alternatives=True, 
                                       include_in_land=True)

# list all possible params with:
MarineTrafficApi.print_params_for('port_distances_and_routes')

for route in routes.models:
	route.distance.value
	route.panama.value
	route.suez.value
	route.final_path.value

(VI04) Predictive Destinations

https://www.marinetraffic.com/en/ais-api-services/documentation/api-service:vi04

from marinetrafficapi import MarineTrafficApi

api = MarineTrafficApi(api_key="__your_api_key_here__")

destinations = api.predictive_destinations(imo=8105088,
                                           fromportid=1)

# list all possible params with:
MarineTrafficApi.print_params_for('predictive_destinations')

for destination in destinations.models:
    destination.imo.value
    destination.ship_id.value
    destination.mmsi.value
    destination.ship_id.value
    destination.ship_class.value
    destination.manager.value
    destination.owner.value
    destination.from_port_id.value
    destination.from_port.value
    destination.next_port_1_id.value
    destination.next_port_1.value
    destination.next_port_1_prob.value
    destination.next_area_1.value
    destination.next_area_1_prob.value
    destination.next_port_2_id.value
    destination.next_port_2.value
    destination.next_port_2_prob.value
    destination.next_area_2.value
    destination.next_area_2_prob.value
    destination.next_port_3_id.value
    destination.next_port_3.value
    destination.next_port_3_prob.value
    destination.next_area_3.value
    destination.next_area_3_prob.value
    destination.next_port_4_id.value
    destination.next_port_4.value
    destination.next_port_4_prob.value
    destination.next_area_4.value
    destination.next_area_4_prob.value
    destination.next_port_5_id.value
    destination.next_port_5.value
    destination.next_port_5_prob.value
    destination.next_area_5.value
    destination.next_area_5_prob.value

(VI05) Predictive Arrivals

https://www.marinetraffic.com/en/ais-api-services/documentation/api-service:vi05

from marinetrafficapi import MarineTrafficApi

api = MarineTrafficApi(api_key="__your_api_key_here__")

arrivals = api.predictive_arrivals(port_id=51)

# list all possible params with:
MarineTrafficApi.print_params_for('predictive_arrivals')

for arrival in arrivals.models:
    arrival.imo.value
    arrival.ship_id.value
    arrival.mmsi.value
    arrival.ship_class.value
    arrival.ship_name.value
    arrival.market.value
    arrival.from_port_id.value
    arrival.from_port.value
    arrival.next_port_id.value
    arrival.next_port.value
    arrival.next_area.value
    arrival.next_port_prob.value
    arrival.next_area_prob.value

(VI06) Predictive Arrivals

https://www.marinetraffic.com/en/ais-api-services/documentation/api-service:vi06

from marinetrafficapi import MarineTrafficApi

api = MarineTrafficApi(api_key="__your_api_key_here__")

ports = api.port_congestion(year=2018,
                            market='wet bulk',
                            ship_class='handysize',
                            week=15,
                            port_id=1)

# list all possible params with:
MarineTrafficApi.print_params_for('port_congestion')

for port in ports.models:
    port.port_id.value
    port.year.value 
    port.week.value
    port.market.value
    port.ship_class.value
    port.time_anch.value
    port.time_port.value
    port.vessels.value
    port.calls.value
    port.time_anch_stdev.value
    port.time_anch_diff.value
    port.time_anch_diff_perc.value
    port.time_port_stdev.value
    port.time_port_diff.value
    port.time_port_diff_perc.value

(VI07) ETA To Port

https://www.marinetraffic.com/en/ais-api-services/documentation/api-service:vi06

from marinetrafficapi import MarineTrafficApi

api = MarineTrafficApi(api_key="__your_api_key_here__")
etas = api.eta_to_port(portid=2036,
                       shipid=292,
                       speed_calc=18.8)

# list all possible params with:
MarineTrafficApi.print_params_for('eta_to_port')

for eta in etas.models:
    eta.ship_id.value
    eta.mmsi.value
    eta.imo.value
    eta.last_port_id.value
    eta.last_port.value
    eta.last_port_unlocode.value
    eta.last_port_time.value
    eta.next_port_name.value
    eta.next_port_unlocode.value
    eta.eta_calc.value
    eta.distance_travelled.value
    eta.distance_to_go.value
    eta.speed.value
    eta.draught.value
    eta.draught_max.value
    eta.load_status_name.value
    eta.route.value
    eta.etd_calc.value
    eta.time_anch.value 
    eta.time_port.value 

Exception Handling

from marinetrafficapi import MarineTrafficApi
from marinetrafficapi import (MarineTrafficRequestApiException,
                              MarineTrafficClientApiException,
                              MarineTrafficFormatterException,
                              MarineTrafficException)

api = MarineTrafficApi(api_key="__your_api_key_here__")

try:
    routes = api.vessel_historical_track(...)
    
except MarineTrafficRequestApiException:
    """Handle Request Exceptions"""
    
except MarineTrafficClientApiException:
    """Handle Client Exceptions"""
    
except MarineTrafficFormatterException:
    """Handle Formatter Exceptions"""
    
except MarineTrafficException:
    """Handle All Marine Traffic Exceptions"""
    

List all API call methods

There are quite a few api call methods and it's quite usefull to have a complete list in one place.

There is one very useful python package called dumpit with which you can easily list all methods and descriptions:

https://github.com/arrrlo/dumpit

To list api call methods, do the following:

from dumpit import pdumpit

from marinetrafficapi import Events
from marinetrafficapi import VoyageInfo
from marinetrafficapi import VesselData
from marinetrafficapi import VesselPositions

pdumpit(Events)
pdumpit(VoyageInfo)
pdumpit(VesselData)
pdumpit(VesselPositions)

API call parameter list and descriptions

Every API call has it's own parameters.

To list them and to read description for every one of them, use following code:

from marinetrafficapi import MarineTrafficApi

MarineTrafficApi.print_params_for('vessel_historical_track')

Response Models Descriptions

There are a lot of model fields and every one of them has it's own description which describes the data comming from the API.

from dumpit import pdumpit
from marinetrafficapi import MarineTrafficApi

api = MarineTrafficApi(api_key="__your_api_key_here__")

request = api.vessel_historical_track(period='daily', days=3, mmsi=241486000)

pdumpit(request.models[0])

Debugging

If you want to debug your code using the data regarding the API call.

from marinetrafficapi import MarineTrafficApi

# initialize with debug=True
api = MarineTrafficApi(api_key="__your_api_key_here__", debug=True)

# after every API call the client library will automatically print all the data to standard output
api.vessel_historical_track(period='daily', days=3, mmsi=241486000)

# and you can always have all debug data in your code
debug_data = api.request.debug.show()

Official documentation

For more information visit official documentation: https://www.marinetraffic.com/en/ais-api-services/