vortexasdk.endpoints.voyages_search_enriched

Try me out in your browser:

Binder

VoyagesSearchEnriched

VoyagesSearchEnriched(self)

Please note: you will require a subscription to our Freight module to access this endpoint.

search

VoyagesSearchEnriched.search(self, order: str = None, order_direction: str = None, offset: int = None, unit: str = None, columns: Union[str, List[str]] = None, time_min: datetime.datetime = datetime.datetime(2022, 1, 1, 0, 0), time_max: datetime.datetime = datetime.datetime(2022, 1, 1, 1, 0), voyage_id: Union[str, List[str]] = None, cargo_movement_id: Union[str, List[str]] = None, voyage_status: Union[str, List[str]] = None, voyage_status_excluded: Union[str, List[str]] = None, movement_status: Union[str, List[str]] = None, movement_status_excluded: Union[str, List[str]] = None, cargo_status: Union[str, List[str]] = None, cargo_status_excluded: Union[str, List[str]] = None, location_status: Union[str, List[str]] = None, location_status_excluded: Union[str, List[str]] = None, commitment_status: Union[str, List[str]] = None, commitment_status_excluded: Union[str, List[str]] = None, exclude_overlapping_entries: bool = None, products: Union[str, List[str]] = None, products_excluded: Union[str, List[str]] = None, latest_products: Union[str, List[str]] = None, latest_products_excluded: Union[str, List[str]] = None, charterers: Union[str, List[str]] = None, charterers_excluded: Union[str, List[str]] = None, effective_controllers: Union[str, List[str]] = None, effective_controllers_excluded: Union[str, List[str]] = None, origins: Union[str, List[str]] = None, origins_excluded: Union[str, List[str]] = None, destinations: Union[str, List[str]] = None, destinations_excluded: Union[str, List[str]] = None, locations: Union[str, List[str]] = None, locations_excluded: Union[str, List[str]] = None, vessels: Union[str, List[str]] = None, vessels_excluded: Union[str, List[str]] = None, flags: Union[str, List[str]] = None, flags_excluded: Union[str, List[str]] = None, ice_class: Union[str, List[str]] = None, ice_class_excluded: Union[str, List[str]] = None, vessel_propulsion: Union[str, List[str]] = None, vessel_propulsion_excluded: Union[str, List[str]] = None, vessel_age_min: int = None, vessel_age_max: int = None, vessel_dwt_min: int = None, vessel_dwt_max: int = None, vessel_cbm_min: int = None, vessel_cbm_max: int = None, vessel_wait_time_min: int = None, vessel_wait_time_max: int = None, vessel_scrubbers: str = None, vessels_tags: Union[vortexasdk.api.shared_types.Tag, List[vortexasdk.api.shared_types.Tag]] = None, vessels_tags_excluded: Union[vortexasdk.api.shared_types.Tag, List[vortexasdk.api.shared_types.Tag]] = None, vessel_risk_level: Union[str, List[str]] = None, vessel_risk_level_excluded: Union[str, List[str]] = None, has_ship_to_ship: str = None, has_charterer: str = None) -> Union[vortexasdk.endpoints.voyages_search_enriched_result.VoyagesSearchEnrichedFlattenedResult, vortexasdk.endpoints.voyages_search_enriched_result.VoyagesSearchEnrichedListResult]

Returns one record per voyage, containing a selection of information about the voyage.

NOTE: To display results as a list (to_list()), please set the columns parameter to None. To display results as dataframe (to_df()), please set the columns parameter to all or a list of selected columns.

Arguments

  • time_min: The UTC start date of the time filter.

  • time_max: The UTC end date of the time filter.

  • voyage_id: An array of unique voyage ID(s) to filter on.

  • cargo_movement_id: An array of unique cargo movement ID(s) to filter on.

  • voyage_status: A voyage status, or list of voyage statuses to filter on. Can be one of: 'ballast', 'laden'.

  • voyage_status_excluded: A voyage status, or list of voyage statuses to exclude.

  • movement_status: A movement status, or list of movement statuses to filter on. Can be one of: 'moving', 'stationary', 'waiting', 'congestion', 'slow'.

  • movement_status_excluded: A movement status, or list of movement statuses to exclude.

  • cargo_status: A cargo status, or list of cargo statuses to filter on. Can be one of: 'in-transit', 'floating-storage', 'loading', 'discharging'.

  • cargo_status_excluded: A cargo status, or list of cargo statuses to exclude.

  • location_status: A location status, or list of location statuses to filter on. Can be one of: 'berth', 'anchorage-zone', 'dry-dock', 'on-the-sea'.

  • location_status_excluded: A location status, or list of location statuses to exclude.

  • commitment_status: A commitment status, or list of commitment statuses to filter on. Can be one of: 'committed', 'uncommitted', 'open', 'unknown'.

  • commitment_status_excluded: A commitment status, or list of commitment statuses to exclude.

  • exclude_overlapping_entries: A boolean to only consider the latest voyage in days where two or more Voyages overlap.

  • products: A product ID, or list of product IDs to filter on.

  • products_excluded: A product ID, or list of product IDs to exclude.

  • latest_products: A product ID, or list of product IDs of the latest cargo on board to filter on.

  • latest_products_excluded: A product ID, or list of product IDs of the latest cargo on board to exclude.

  • charterers: A charterer ID, or list of charterer IDs to filter on.

  • charterers_excluded: A charterer ID, or list of charterer IDs to exclude.

  • effective_controllers: A vessel effective controller ID, or list of vessel effective controller IDs to filter on.

  • effective_controllers_excluded: A effective controller ID, or list of effective controller IDs to exclude.

  • origins: An origin ID, or list of origin IDs to filter on.

  • origins_excluded: An origin ID, or list of origin IDs to exclude.

  • destinations: A destination ID, or list of destination IDs to filter on.

  • destinations_excluded: A destination ID, or list of destination IDs to exclude.

  • locations: A location ID, or list of location IDs to filter on.

  • locations_excluded: A location ID, or list of location IDs to exclude.

  • vessels: A vessel ID or vessel class, or list of vessel IDs/vessel classes to filter on.

  • vessels_excluded: A vessel ID or vessel class, or list of vessel IDs/vessel classes to exclude.

  • flags: A flag, or list of flags to filter on.

  • flags_excluded: A flag, or list of flags to exclude.

  • ice_class: An ice class, or list of ice classes to filter on.

  • ice_class_excluded: An ice class, or list of ice classes to ęxclude.

  • vessel_propulsion: A propulsion method, or list of propulsion methods to filter on.

  • vessel_propulsion_excluded: A propulsion method, or list of propulsion methods to ęxclude.

  • vessel_age_min: A number between 1 and 100 (representing years).

  • vessel_age_max: A number between 1 and 100 (representing years).

  • vessel_dwt_min: A number representing minimum deadweight tonnage of a vessel.

  • vessel_dwt_max: A number representing maximum deadweight tonnage of a vessel.

  • vessel_cdm_min: A number representing minimum cubic capacity of a vessel.

  • vessel_cbm_max: A number representing maximum cubic capacity of a vessel.

  • vessel_wait_time_min: A number representing a minimum number of days until a vessel becomes available.

  • vessel_wait_time_max: A number representing a maximum number of days until a vessel becomes available.

  • vessel_scrubbers: Either inactive 'disabled', or included 'inc' or excluded 'exc'.

  • vessels_tags: A time bound vessel tag, or list of time bound vessel tags to filter on.

  • vessels_tags_excluded: A time bound vessel tag, or list of time bound vessel tags to exclude.

  • vessel_risk_level: A vessel risk level, or list of vessel risk levels to filter on.

  • vessel_risk_level_excluded: A vessel risk level, or list of vessel risk levels to exclude.

  • has_ship_to_ship: Filter data where at least one STS transfer occurs, or none. - one of disabled, inc, exc. Passing disabled means the filter is not active.

  • has_charterer: Filter data where at least one charterer is specified, or none. - one of disabled, inc, exc. Passing disabled means the filter is not active.

  • order: Used to sort the returned results. Can be one of:'vessel_name','dwt','vessel_class', 'start_date','end_date'.

  • order_direction: Determines the direction of sorting. ‘asc’ for ascending, ‘desc’ for descending.

  • offset: Used to page results. The offset from which records should be returned.

  • unit: Unit of measurement. Enter 'b' for barrels or 't' for tonnes or 'cbm' for cubic metres.

  • columns: Determines what columns are visible in the output. Enter "all" for all columns, or any of: 'vessel_name','imo','dwt','capacity','vessel_class','voyage_status','cargo_status', 'origin','origin_shipping_region','origin_region','origin_country','origin_port','origin_terminal', 'destination','destination_shipping_region','destination_region','destination_country','destination_port','destination_terminal','destination_eta', 'charterer','effective_controller','voyage_type','quantity','latest_product','latest_product_group','latest_product_category','latest_product_grade', 'time_charterer','flag','scrubber','build_year','risk_rating','coating','start_date','end_date','tonne_miles','distance', 'voyage_id','previous_voyage_id','next_voyage_id','duration','location','waiting_time','waiting_commence','waiting_finished'.

Returns

VoyagesSearchEnrichedListResult or VoyagesSearchEnrichedFlattenedResult

Example

Voyages as of 26th April 2022 for vessels carrying crude departing from Rotterdam.

>>> from vortexasdk import VoyagesSearchEnriched, Geographies
>>> from datetime import datetime
>>> rotterdam = [g.id for g in Geographies().search("rotterdam").to_list() if "port" in g.layer]
>>> start = datetime(2021, 8, 1)
>>> end = datetime(2021, 8, 1, 23, 59)
>>> search_result = VoyagesSearchEnriched().search(
... time_min=start,
... time_max=end,
... origins=rotterdam,
... columns="all",
... ).to_df().head()

Gives the following result:

|    | VESSEL NAME     |     IMO | VESSEL CLASS   | VOYAGE STATUS   | ORIGIN                         | DESTINATION             | START DATE   | END DATE    | LATEST PRODUCT   |   QUANTITY (bbl) | CHARTERER   | EFFECTIVE CONTROLLER   | TIME CHARTERER   |   BUILD YEAR | FLAG   | RISK RATING   | SCRUBBERS   | COATING   | TONNE-MILES   |   DURATION |   DISTANCE |
|---:|:----------------|--------:|:---------------|:----------------|:-------------------------------|:------------------------|:-------------|:------------|:-----------------|-----------------:|:------------|:-----------------------|:-----------------|-------------:|:-------|:--------------|:------------|:----------|:--------------|-----------:|-----------:|
|  0 | YURIY KUCHIEV   | 9804033 | Handymax / MR  | Ballast         | Rotterdam [NL]                 | Sabetta [RU]            | 23 Apr 2022  | 09 May 2022 | Condensates      |                0 |             | Yamal LNG              |                  |         2019 | CY     | Low           |             | Coated    |               |         16 |       2931 |
|  1 | YASA SWAN       | 9857248 | Handymax / MR  | Ballast         | Rotterdam [NL]                 | Corpus Christi, TX [US] | 02 Apr 2022  | 03 May 2022 | Naphtha          |                0 |             | Equinor                |                  |         2019 | MH     | Low           | Installed   | Coated    |               |         31 |       5775 |
|  2 | WONDER MIMOSA   | 9312901 | Handysize      | Laden           | Rotterdam [NL]                 | Kalamata STS [GR]       | 20 Apr 2022  | 18 May 2022 | Fuel Oil         |           144496 | Gunvor      | HAFNIA                 |                  |         2006 | MH     | Low           |             | Coated    | 72034459      |         28 |       3221 |
|  3 | WINE TRADER     | 8808707 | Tiny tanker    | Ballast         | Rotterdam [NL]                 | Cape Town [ZA]          | 17 Mar 2022  | 02 Jun 2022 | Biodiesel        |                0 |             |                        |                  |         1989 | PA     | Low           |             | Coated    |               |         74 |       7674 |
|  4 | WHISTLER SPIRIT | 9417323 | Aframax / LR2  | Laden           | Rotterdam [NL], Rotterdam [NL] | Aruba STS [NL]          | 17 Apr 2022  | 09 May 2022 | Fuel Oil         |           175712 |             | TEEKAY                 |                  |         2010 | BS     | Low           |             |           | 470203453     |         22 |       4649 |