vortexasdk.endpoints.voyages_top_hits

Try me out in your browser:

VoyagesTopHits

VoyagesTopHits(self)

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

search

VoyagesTopHits.search(
    breakdown_property: typing.Optional[str] = None,
    breakdown_split_property: typing.Optional[str] = None,
    breakdown_size: typing.Optional[int] = None,
    time_min: datetime = datetime.datetime(2022, 1, 1, 0, 0),
    time_max: datetime = datetime.datetime(2022, 1, 1, 1, 0),
    voyage_id: typing.Union[str, typing.List[str], NoneType] = None,
    cargo_movement_id: typing.Union[str, typing.List[str], NoneType] = None,
    voyage_status: typing.Union[str, typing.List[str], NoneType] = None,
    voyage_status_excluded:
    typing.Union[str, typing.List[str], NoneType] = None,
    movement_status: typing.Union[str, typing.List[str], NoneType] = None,
    movement_status_excluded:
    typing.Union[str, typing.List[str], NoneType] = None,
    cargo_status: typing.Union[str, typing.List[str], NoneType] = None,
    cargo_status_excluded: typing.Union[str, typing.List[str], NoneType] = None,
    location_status: typing.Union[str, typing.List[str], NoneType] = None,
    location_status_excluded:
    typing.Union[str, typing.List[str], NoneType] = None,
    commitment_status: typing.Union[str, typing.List[str], NoneType] = None,
    commitment_status_excluded:
    typing.Union[str, typing.List[str], NoneType] = None,
    exclude_overlapping_entries: typing.Optional[bool] = None,
    products: typing.Union[str, typing.List[str], NoneType] = None,
    products_excluded: typing.Union[str, typing.List[str], NoneType] = None,
    latest_products: typing.Union[str, typing.List[str], NoneType] = None,
    latest_products_excluded:
    typing.Union[str, typing.List[str], NoneType] = None,
    charterers: typing.Union[str, typing.List[str], NoneType] = None,
    charterers_excluded: typing.Union[str, typing.List[str], NoneType] = None,
    effective_controllers: typing.Union[str, typing.List[str], NoneType] = None,
    effective_controllers_excluded:
    typing.Union[str, typing.List[str], NoneType] = None,
    origins: typing.Union[str, typing.List[str], NoneType] = None,
    origins_excluded: typing.Union[str, typing.List[str], NoneType] = None,
    destinations: typing.Union[str, typing.List[str], NoneType] = None,
    destinations_excluded: typing.Union[str, typing.List[str], NoneType] = None,
    locations: typing.Union[str, typing.List[str], NoneType] = None,
    locations_excluded: typing.Union[str, typing.List[str], NoneType] = None,
    congestion_target_location:
    typing.Union[str, typing.List[str], NoneType] = None,
    congestion_target_location_excluded:
    typing.Union[str, typing.List[str], NoneType] = None,
    vessels: typing.Union[str, typing.List[str], NoneType] = None,
    vessels_excluded: typing.Union[str, typing.List[str], NoneType] = None,
    flags: typing.Union[str, typing.List[str], NoneType] = None,
    flags_excluded: typing.Union[str, typing.List[str], NoneType] = None,
    ice_class: typing.Union[str, typing.List[str], NoneType] = None,
    ice_class_excluded: typing.Union[str, typing.List[str], NoneType] = None,
    vessel_propulsion: typing.Union[str, typing.List[str], NoneType] = None,
    vessel_propulsion_excluded:
    typing.Union[str, typing.List[str], NoneType] = None,
    vessel_age_min: typing.Optional[int] = None,
    vessel_age_max: typing.Optional[int] = None,
    vessel_dwt_min: typing.Optional[int] = None,
    vessel_dwt_max: typing.Optional[int] = None,
    vessel_cbm_min: typing.Optional[int] = None,
    vessel_cbm_max: typing.Optional[int] = None,
    vessel_wait_time_min: typing.Optional[int] = None,
    vessel_wait_time_max: typing.Optional[int] = None,
    vessel_scrubbers: typing.Optional[str] = None,
    vessel_tags:
    typing.Union[typing.List[vortexasdk.api.shared_types.Tag], vortexasdk.api.shared_types.Tag, NoneType] = None,
    vessel_tags_excluded:
    typing.Union[typing.List[vortexasdk.api.shared_types.Tag], vortexasdk.api.shared_types.Tag, NoneType] = None,
    vessel_risk_level: typing.Union[str, typing.List[str], NoneType] = None,
    vessel_risk_level_excluded:
    typing.Union[str, typing.List[str], NoneType] = None,
    has_ship_to_ship: typing.Optional[str] = None,
    has_charterer: typing.Optional[str] = None,
    intra_movements: typing.Optional[str] = None,
    voyage_date_range_activity:
    typing.Optional[vortexasdk.api.shared_types.VoyageDateRangeActivity] = None,
    origin_behaviour:
    typing.Optional[vortexasdk.api.shared_types.OriginBehaviour] = None,
    destination_behaviour:
    typing.Optional[vortexasdk.api.shared_types.DestinationBehaviour] = None)

Returns a count of voyages aggregated by a chosen breakdown_property.

Arguments

breakdown_size: Number of top records to return.

breakdown_property: Property to aggregate upon. Must be vessel_count or not provided.

breakdown_split_property: Property to split results by. Can be one of: 'vessel_status', 'vessel_class_group', 'vessel_class_coarse', 'vessel_class_granular', 'vessel_flag','fixture_status', 'origin_region', 'origin_shipping_region','origin_trading_region','origin_trading_sub_region','origin_trading_block','origin_country','origin_port', 'origin_terminal','destination_region','destination_shipping_region','destination_trading_region','destination_trading_sub_region','destination_trading_block', 'destination_country','destination_port','destination_terminal','location_port','location_country','location_shipping_region', 'congestion_location_port','congestion_location_country','congestion_location_shipping_region','product_group','product_group_product','product_category', 'product_grade'.

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 vessel effective controller ID, or list of vessel effective controller IDs to exclude.

origins: An origin ID, or list of origin IDs for all the cargoes of a voyage to filter on.

origins_excluded: An origin ID, or list of origin IDs for all the cargoes of a voyage to exclude.

destinations: A destination ID, or list of destination IDs for all the cargoes of a voyage to filter on.

destinations_excluded: A destination ID, or list of destination IDs for all the cargoes of a voyage 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.

congestion_target_location: A congestion location ID, or list of congestion location IDs to filter on.

congestion_target_location_excluded: A congestion location ID, or list of congestion 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_cbm_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'.

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

vessel_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.

intra_movements: Filter movements based on whether the vessel started and ended in the same country, or geographical layer.

voyage_date_range_activity: Filter to determine how the voyages should be counted. Must be one of [active, departures, arrivals]

origin_behaviour: The origin behaviour determines which departure mode the voyage_date_range_activity should count, must be one of [first_load, any_load].

destination_behaviour: The destination behaviour determines which arrival mode the voyage_date_range_activity should count, must be one of [last_discharge, any_discharge].

Returns

AggregationBreakdownResult

Example

Top oritin countries for crude imports to Rotterdam on 8th August 2021.

>>> from vortexasdk import VoyagesTopHits, Geographies, Products
>>> from datetime import datetime
>>> rotterdam = [g.id for g in Geographies().search("rotterdam").to_list() if "port" in g.layer]
>>> crude = [p.id for p in Products().search("crude").to_list() if "Crude" == p.name]
>>> start = datetime(2021, 8, 1)
>>> end = datetime(2021, 8, 1, 23, 59)
>>> search_result = VoyagesTopHits().search(
...    time_min=start,
...    time_max=end,
...    destinations=rotterdam,
...    products=crude,
...    breakdown_size=5,
...    breakdown_split_property="origin_country"
... ).to_list()

Gives the following result:

[
    AggregationBreakdownItem(
        id='b996521be9c996db',
        count=8,
        value=8.0,
        label='Russia'
    ),
    AggregationBreakdownItem(
        id='2d92cc08f22524db',
        count=7,
        value=7.0,
        label='United States'
    ),
    AggregationBreakdownItem(
        id='2aaad41b89dfad19',
        count=4,
        value=4.0,
        label='United Kingdom'
    ),
    AggregationBreakdownItem(
        id='430f0e467f3a408f',
        count=2,
        value=2.0,
        label='Nigeria'
    ),
    AggregationBreakdownItem(
        id='3eac69e760d9ec57',
        count=1,
        value=1.0,
        label='Egypt'
    )
]