vortexasdk.endpoints.voyages_timeseries
Try me out in your browser:
VoyagesTimeseries
VoyagesTimeseries(self)
Please note: you will require a subscription to our Freight module to access this endpoint.
search
VoyagesTimeseries.search(
breakdown_frequency: typing.Optional[str] = None,
breakdown_property: typing.Optional[str] = None,
breakdown_split_property: typing.Optional[str] = None,
breakdown_unit_operator: typing.Optional[str] = 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 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_activityshould 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 |