Try me out in your browser:




Vessels endpoint.


VesselSummary.search(self, vessel_id: Union[str, List[str]] = None, vessel_class: Union[str, List[str]] = None, timestamp: str = None) -> vortexasdk.endpoints.vessel_summary_result.VesselSummaryResult

Find all latest summary of vessels matching given search arguments. Search arguments are combined in an AND manner.


  • timestamp: The earliest timestamp before which you'd like your summaries sourced from

  • vessel_id: ID or IDs of vessels we'd like to search

  • vessel_class: vessel_class (or list of vessel classes) we'd like to search. This will give you summaries for all vessels within this class. Each vessel class must be one of "oil_coastal", "oil_intermediate", "oil_flexi", "oil_handysize", "oil_mr1","oil_handymax", "oil_mr2", "oil_panamax", "oil_lr1", "oil_aframax", "oil_lr2", "oil_suezmax","oil_lr3", "oil_vlcc","lpg_coasters", "lpg_handysize", "lpg_mgc", "lpg_lgc", "lpg_vlgc", "lpg_vlec", "lng_small_scale_lng", "lng_mid_scale_lng", "lng_two_stroke", "lng_tfde_dfde", "lng_steam", "lng_ssd", "lng_q_flex", "lng_q_max", "oil_coastal", "oil_specialised", "oil_handysize_mr1", "oil_handymax_mr2", "oil_panamax_lr1", "oil_aframax_lr2", "oil_suezmax_lr3", "oil_vlcc","lpg_sgc", "lpg_mgc", "lpg_lgc", "lpg_vlgc_vlec","lng_small_scale_lng", "lng_mid_scale_lng","lng_conventional_lng", "lng_q_fleet", "oil", "lpg", "lng",. Refer to VortexaAPI Vessel Entities for the most up-to-date list of vessel classes.


List of vessel summaries matching the search arguments.


  • Let's find all summaries for all Aframax and VLCC_PLUS vessels, from the week prior to October 31st, 2023.
>>> from vortexasdk import VesselSummary
>>> vessel_summary_df = VesselSummary().search(vessel_class=['oil_aframax', 'oil_vlcc'], timestamp='2023-10-31T23:59:59.000Z').to_df(columns=['vessel_id', 'timestamp', 'lat', 'lon', 'speed', 'heading', 'declared_destination', 'draught'])

vessel_id lat lon timestamp speed heading declared_destination draught
0 bc49bed3d600b394 17.36560 -161.39080 2023-10-31T23:57:11.000Z 19.299 308 >JP KZU XX 11
...to >800 results

Note that we will show you all fields by default if you don't set the columns argument.

- Now let's find summaries for vessels carrying crude, using the Vessels and Product Reference endpoints

>>> from vortexasdk import Vessels, Products
>>> crude = [p.id for p in Products().search(term="crude").to_list() if 'group' in p.layer]
>>> vessels_list = Vessels().search(vessel_product_types=crude).to_list()
>>> vessel_ids = [v.id for v in vessels_list]
>>> crude_summaries = VesselSummary().search(vessel_id=vessel_ids).to_df()

Further Documentation

VortexaAPI Vessel Summary Reference



VesselSummaryResult(__pydantic_self__, **data: Any) -> None

Container class that holds the result obtained from calling the Vessel-Summary endpoint.


VesselSummaryResult.to_list(self) -> List[vortexasdk.api.vessel_summary.VesselSummary]

Represent vessel summaries as a list.


VesselSummaryResult.to_df(self, columns=['vessel_id', 'timestamp', 'lat', 'lon', 'speed', 'draught', 'declared_destination', 'declared_eta']) -> pandas.core.frame.DataFrame

Represent vessel summaries as a pd.DataFrame.


  • columns: The vessel summaries we want in the dataframe. Enter columns='all' to include all features. Defaults to columns = ['vessel_id', 'timestamp', 'lat', 'lon', 'speed', 'draught', 'declared_destination', 'declared_eta'].


pd.DataFrame of vessel summaries.