Marine Traffic Client Api
Project description
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/
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Filename, size | File type | Python version | Upload date | Hashes |
---|---|---|---|---|
Filename, size Marine_Traffic_API-0.20.1-py3-none-any.whl (59.8 kB) | File type Wheel | Python version py3 | Upload date | Hashes View |
Filename, size Marine Traffic API-0.20.1.tar.gz (38.2 kB) | File type Source | Python version None | Upload date | Hashes View |
Hashes for Marine_Traffic_API-0.20.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c4e107926ad4d06d502374425b3de82009df06ce5128487b2440d2cdd951bfef |
|
MD5 | 4fa6d1cb1bd6628c69131dd5cd6ecd97 |
|
BLAKE2-256 | 0cc5023bd018f687a01dd32a587c032761932d466ac35af82d3a299c3d1d6ddf |
Hashes for Marine Traffic API-0.20.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3f1444e0ddb0d953bab55f8e905be5649f6f0cfe6138d0dcfebe5e36736c1332 |
|
MD5 | 79f9a99a5a77d9ee966b25db936db481 |
|
BLAKE2-256 | 7b65bf3aa4b5ce696eaa4d6ff0aad1bb2232a6d8e6c19371ebeda25c46124bc9 |