Try me out in your browser:




Vessel Positions endpoint.


VesselPositions.search(self, vessel_id: Union[str, List[str]] = None, vessel_class: Union[str, List[str]] = None, time_max: str = None, time_min: str = None, interval: str = '1d') -> vortexasdk.endpoints.vessel_positions_result.VesselPositionsResult

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


  • time_max: The earliest timestamp before which you'd like your positions 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 positions for all vessels within this class, if no IDs are set. 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 positions matching the search arguments.


  • Let's find a position for all Aframax vessels, from the day of March 12th, 2024
>>> from vortexasdk import VesselPositions
>>> vessel_positions_df = VesselPositions().search(vessel_class=['oil_aframax'], time_max='2024-03-12T23:59:59.000Z', time_min='2024-03-12T00:00:00.000Z', interval='1d').to_df(columns=['vessel_id', 'timestsamp', 'lat', 'lon', 'speed', 'heading'])

vessel_id lat lon timestamp speed heading
0 bc49bed3d600b394 17.36560 -161.39080 2023-10-31T23:57:11.000Z 19.299 308
...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 positions 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_positions = VesselPositions().search(vessel_id=vessel_ids).to_df()

Further Documentation

VortexaAPI Vessel Positions Reference



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

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


VesselPositionsResult.to_list(self) -> List[vortexasdk.api.vessel_positions.VesselPositions]

Represent vessel positions as a list.


VesselPositionsResult.to_df(self, columns=['vessel_id', 'timestamp', 'lat', 'lon', 'speed', 'heading']) -> pandas.core.frame.DataFrame

Represent vessel positions as a pd.DataFrame.


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


pd.DataFrame of vessel positions.