vortexasdk.endpoints.voyages_timeseries

Try me out in your browser:

Binder

VoyagesTimeseries

VoyagesTimeseries(self)

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

search

VoyagesTimeseries.search(self, breakdown_frequency: str = None, breakdown_property: str = None, breakdown_split_property: str = None, breakdown_unit_operator: 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, congestion_target_location: Union[str, List[str]] = None, congestion_target_location_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, vessel_tags: Union[vortexasdk.api.shared_types.Tag, List[vortexasdk.api.shared_types.Tag]] = None, vessel_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, intra_movements: str = None, voyage_date_range_activity: vortexasdk.api.shared_types.VoyageDateRangeActivity = None, origin_behaviour: vortexasdk.api.shared_types.OriginBehaviour = None, destination_behaviour: vortexasdk.api.shared_types.DestinationBehaviour = None) -> vortexasdk.endpoints.timeseries_result.TimeSeriesResult

Returns a count of voyages per record for the requested date period

Arguments

  • breakdown_frequency: Frequency denoting the granularity of the time series. Must be one of the following: 'day', 'week', 'doe_week', 'month', 'quarter', 'year'.

  • breakdown_property: Property to aggregate upon. Can be one of: 'vessel_count', 'utilisation', 'cargo_quantity', 'avg_wait_time','dwt', 'cubic_capacity', 'tonne_miles', 'avg_distance', 'avg_speed'.

  • 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', 'charterer', 'effective_controller', 'none' or not provided.

  • breakdown_unit_operator: Denotes the type of the aggregation calculation. Can be one of 'sum' or 'avg'.

  • 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 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

BreakdownResult

Example

Sum of vessels departing from Ukraine between 1th-3rd Febuary 2024, split by location country.

>>> from vortexasdk import VoyagesTimeseries
>>> from datetime import datetime
>>> search_result = VoyagesTimeseries().search(
...    origins=["c4b606ff15bd9b86"],
...    time_min=datetime(2024, 2, 1),
...    time_max=datetime(2024, 2, 3, 23, 59),
...    breakdown_frequency="day",
...    breakdown_property="vessel_count",
...    breakdown_split_property="location_country",
...    ).to_df()

Gives the following result:

|    | key                       |   value |   count | breakdown.0.id   | breakdown.0.label   |   breakdown.0.count |   breakdown.0.value | breakdown.1.id   | breakdown.1.label   | breakdown.1.count   | breakdown.1.value   | breakdown.2.id   | breakdown.2.label   |   breakdown.2.count |   breakdown.2.value | breakdown.3.id   | breakdown.3.label   |   breakdown.3.count |   breakdown.3.value | breakdown.4.id   | breakdown.4.label   |   breakdown.4.count |   breakdown.4.value | breakdown.5.id   | breakdown.5.label   |   breakdown.5.count |   breakdown.5.value | breakdown.6.id   | breakdown.6.label   |   breakdown.6.count |   breakdown.6.value | breakdown.7.id   | breakdown.7.label   |   breakdown.7.count |   breakdown.7.value | breakdown.8.id   | breakdown.8.label   |   breakdown.8.count |   breakdown.8.value | breakdown.9.id   | breakdown.9.label   |   breakdown.9.count |   breakdown.9.value | breakdown.10.id   | breakdown.10.label   |   breakdown.10.count |   breakdown.10.value | breakdown.11.id   | breakdown.11.label   |   breakdown.11.count |   breakdown.11.value | breakdown.12.id   | breakdown.12.label   |   breakdown.12.count |   breakdown.12.value | breakdown.13.id   | breakdown.13.label   |   breakdown.13.count |   breakdown.13.value |
|---:|:--------------------------|--------:|--------:|:-----------------|:--------------------|--------------------:|--------------------:|:-----------------|:--------------------|:--------------------|:--------------------|:-----------------|:--------------------|--------------------:|--------------------:|:-----------------|:--------------------|--------------------:|--------------------:|:-----------------|:--------------------|--------------------:|--------------------:|:-----------------|:--------------------|--------------------:|--------------------:|:-----------------|:--------------------|--------------------:|--------------------:|:-----------------|:--------------------|--------------------:|--------------------:|:-----------------|:--------------------|--------------------:|--------------------:|:-----------------|:--------------------|--------------------:|--------------------:|:------------------|:---------------------|---------------------:|---------------------:|:------------------|:---------------------|---------------------:|---------------------:|:------------------|:---------------------|---------------------:|---------------------:|:------------------|:---------------------|---------------------:|---------------------:|
|  0 | 2024-02-01 00:00:00+00:00 |      16 |      16 | a398152fa8e559b0 | Bulgaria            |                   2 |                   2 | 3eac69e760d9ec57 | Egypt               | 2                   | 1                   | e9e556620469f46a | France              |                   1 |                   1 | b6be463f6999751d | Greece              |                   8 |                   3 | ee1de4914cc26e8f | Italy               |                   4 |                   2 | 82a6dd5bf8dfb66a | Libya               |                   1 |                   1 | 80dd61da7ce1edcc | Malta               |                   5 |                   3 | 8c6dfac15afa6dca | Portugal            |                   1 |                   1 | 65ab749279c8fbe6 | Romania             |                   6 |                   4 | c1698979b983b265 | Spain               |                   2 |                   2 | 03b07ca887edb311  | Tunisia              |                    5 |                    2 | 69c53542ac9ee1fc  | Turkey               |                   17 |                    7 | c4b606ff15bd9b86  | Ukraine              |                   12 |                    3 | 2aaad41b89dfad19  | United Kingdom       |                    1 |                    1 |
|  1 | 2024-02-02 00:00:00+00:00 |      16 |      16 | a398152fa8e559b0 | Bulgaria            |                   2 |                   2 | 3eac69e760d9ec57 | Egypt               | 2                   | 1                   | e9e556620469f46a | France              |                   1 |                   1 | b6be463f6999751d | Greece              |                   8 |                   3 | ee1de4914cc26e8f | Italy               |                   4 |                   2 | 82a6dd5bf8dfb66a | Libya               |                   1 |                   1 | 80dd61da7ce1edcc | Malta               |                   5 |                   3 | 8c6dfac15afa6dca | Portugal            |                   1 |                   1 | 65ab749279c8fbe6 | Romania             |                   6 |                   4 | c1698979b983b265 | Spain               |                   2 |                   2 | 03b07ca887edb311  | Tunisia              |                    5 |                    2 | 69c53542ac9ee1fc  | Turkey               |                   17 |                    7 | c4b606ff15bd9b86  | Ukraine              |                   12 |                    3 | 2aaad41b89dfad19  | United Kingdom       |                    1 |                    1 |
|  2 | 2024-02-03 00:00:00+00:00 |      13 |      13 | a398152fa8e559b0 | Bulgaria            |                   2 |                   2 | 3eac69e760d9ec57 | Egypt               |                     |                     | e9e556620469f46a | France              |                   1 |                   1 | b6be463f6999751d | Greece              |                   5 |                   2 | ee1de4914cc26e8f | Italy               |                   4 |                   2 | 82a6dd5bf8dfb66a | Libya               |                   1 |                   1 | 80dd61da7ce1edcc | Malta               |                   5 |                   3 | 8c6dfac15afa6dca | Portugal            |                   1 |                   1 | 65ab749279c8fbe6 | Romania             |                   6 |                   4 | c1698979b983b265 | Spain               |                   2 |                   2 | 03b07ca887edb311  | Tunisia              |                    5 |                    2 | 69c53542ac9ee1fc  | Turkey               |                    8 |                    4 | c4b606ff15bd9b86  | Ukraine              |                   16 |                    4 | 2aaad41b89dfad19  | United Kingdom       |                    1 |                    1 |