diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 2117ab1d..9c6b46c3 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -3,7 +3,7 @@ repos: rev: 22.3.0 hooks: - id: black - language_version: python3.9.0 + language_version: python3.9.19 - repo: https://github.com/pre-commit/pre-commit-hooks rev: v1.2.3 hooks: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 871fe022..bcca56f1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -83,13 +83,7 @@ Now you're ready to create a new branch, add a feature or fix a bug, then send u ### Note about Apple ARM-based chips -To run the SDK on an Apple ARM chip, upgrade your Python version to 3.9 or higher and use the latest version of pip. This works for the SDK version 0.41.0 or higher. - -The set up is almost identical as above except one command; to create a virtual environment for Python 3.8 you should run: - -```bash -python -m venv venv -``` +To run the SDK on an Apple ARM chip, use Python version 3.9.19 and use the latest version of pip. This works for the SDK version 0.41.0 or higher. ## Contributing Code diff --git a/README.md b/README.md index 5739a5fd..a3a4e60f 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,7 @@ pip3 install vortexasdk The SDK requires Python version 3.9. See [Setup FAQ](https://vortechsa.github.io/python-sdk/faq_setup/) for more details. -To install the SDK on an Apple ARM-based machine, use Python versions 3.9 and use the latest version of pip. This is supported in the SDK versions 1.0.0 or higher. +To install the SDK on an Apple ARM-based machine, use Python versions 3.9.19 and use the latest version of pip. This is supported in the SDK versions 1.0.0 or higher. ## Authentication diff --git a/tests/api/examples/cargo_movements.json b/tests/api/examples/cargo_movements.json index 64024a9e..74ea4775 100644 --- a/tests/api/examples/cargo_movements.json +++ b/tests/api/examples/cargo_movements.json @@ -101,6 +101,18 @@ "id": "9d52ede1cff0421a8cd7283b0171afe8d23f519dca5f4e489734522f9cdf804c", "splinter_timestamp": "2019-10-20T16:41:49+0000" } - ] + ], + "trades": [ + { + "type": "shipper", + "id": "c9f70607e743e82428ea24cd32f6e403c6ced09078eacfe3d6c175347a9ab508", + "label": "NAYARA ENERGY" + }, + { + "type": "consignee", + "id": "5b3fcbc1bd2efec8999bd37d128a7e2132ebd9acf5a1a6fd8d6d2ba234c13938", + "label": "RELIANCE" + } + ] } ] diff --git a/tests/api/test_cargo_movement.py b/tests/api/test_cargo_movement.py index ad76c144..671921aa 100644 --- a/tests/api/test_cargo_movement.py +++ b/tests/api/test_cargo_movement.py @@ -95,6 +95,18 @@ class TestCargoMovement(TestCase): "splinter_timestamp": "2019-10-20T16:41:49+0000", } ], + "trades": [ + { + "type": "shipper", + "id": "c9f70607e743e82428ea24cd32f6e403c6ced09078eacfe3d6c175347a9ab508", + "label": "NAYARA ENERGY", + }, + { + "type": "consignee", + "id": "5b3fcbc1bd2efec8999bd37d128a7e2132ebd9acf5a1a6fd8d6d2ba234c13938", + "label": "RELIANCE", + }, + ], } cm = CargoMovement.model_validate(dictionary) @@ -179,6 +191,12 @@ def test_convert_to_flat_dict(self) -> None: "vessels.0.voyage_id": "401f0e74fc42401248a484aca2e9955dea885378796f7f4d0bc8e92c35ea270a", "parent_ids.0.id": "9d52ede1cff0421a8cd7283b0171afe8d23f519dca5f4e489734522f9cdf804c", "parent_ids.0.splinter_timestamp": "2019-10-20T16:41:49+0000", + "trades.0.type": "shipper", + "trades.0.id": "c9f70607e743e82428ea24cd32f6e403c6ced09078eacfe3d6c175347a9ab508", + "trades.0.label": "NAYARA ENERGY", + "trades.1.type": "consignee", + "trades.1.id": "5b3fcbc1bd2efec8999bd37d128a7e2132ebd9acf5a1a6fd8d6d2ba234c13938", + "trades.1.label": "RELIANCE", } assert flat == expected diff --git a/tests/endpoints/test_canal_transit_timeseries_real.py b/tests/endpoints/test_canal_transit_timeseries_real.py index 0afe5fa1..e44e427f 100644 --- a/tests/endpoints/test_canal_transit_timeseries_real.py +++ b/tests/endpoints/test_canal_transit_timeseries_real.py @@ -13,7 +13,7 @@ def test_canal_timeseries_with_filtering(self): nonLng = CanalTransitTimeseries().search( time_min=datetime(2023, 9, 5), time_max=datetime(2023, 9, 7), - exclude_filter_vessel_classes=["lng"], + exclude_vessel_classes=["lng"], metric="count_of_vessels", timeseries_activity="started_waiting", ) diff --git a/tests/endpoints/test_cargo_movements_real.py b/tests/endpoints/test_cargo_movements_real.py index a5431917..157cce83 100644 --- a/tests/endpoints/test_cargo_movements_real.py +++ b/tests/endpoints/test_cargo_movements_real.py @@ -326,3 +326,51 @@ def test_get_single_cargo_movement_with_unit_param(self): assert cmT["quantity"] != cmB["quantity"] assert cmT["quantity"] != cmCBM["quantity"] + + def test_filter_by_shipper_and_consignee(self): + cms = CargoMovements().search( + filter_activity="loading_start", + filter_time_min=datetime(2025, 6, 8), + filter_time_max=datetime(2025, 6, 10), + filter_shipper="7b3c9abe7a56425f27bfcd227426ff6a8bc68357cbbb775d7c6c3d0df9bb2f2c", + filter_consignee="5b3fcbc1bd2efec8999bd37d128a7e2132ebd9acf5a1a6fd8d6d2ba234c13938", + ) + + for i, cm in enumerate(cms): + assert "trades" in cm + assert cm["trades"] + + for trade in cm["trades"]: + if trade["type"] == "shipper": + assert ( + trade["id"] + == "7b3c9abe7a56425f27bfcd227426ff6a8bc68357cbbb775d7c6c3d0df9bb2f2c" + ) + elif trade["type"] == "consignee": + assert ( + trade["id"] + == "5b3fcbc1bd2efec8999bd37d128a7e2132ebd9acf5a1a6fd8d6d2ba234c13938" + ) + + def test_filter_exclude_shipper_and_consignee(self): + cms = CargoMovements().search( + filter_activity="loading_start", + filter_time_min=datetime(2025, 6, 8), + filter_time_max=datetime(2025, 6, 10), + exclude_shipper="7b3c9abe7a56425f27bfcd227426ff6a8bc68357cbbb775d7c6c3d0df9bb2f2c", + exclude_consignee="5b3fcbc1bd2efec8999bd37d128a7e2132ebd9acf5a1a6fd8d6d2ba234c13938", + ) + + for i, cm in enumerate(cms): + if "trades" in cm and cm["trades"]: + for trade in cm["trades"]: + if trade["type"] == "shipper": + assert ( + trade["id"] + != "7b3c9abe7a56425f27bfcd227426ff6a8bc68357cbbb775d7c6c3d0df9bb2f2c" + ) + elif trade["type"] == "consignee": + assert ( + trade["id"] + != "5b3fcbc1bd2efec8999bd37d128a7e2132ebd9acf5a1a6fd8d6d2ba234c13938" + ) diff --git a/vortexasdk/api/cargo_movement.py b/vortexasdk/api/cargo_movement.py index 6805d7fd..f65b91f1 100644 --- a/vortexasdk/api/cargo_movement.py +++ b/vortexasdk/api/cargo_movement.py @@ -135,6 +135,12 @@ class CargoMovementProductEntry(BaseModel): label: Optional[str] = None +class CargoMovementTradeEntry(BaseModel): + type: Literal["load", "discharge", "shipper", "consignee"] + id: Optional[ID] = None + label: Optional[str] = None + + class CargoMovement(BaseModel): """ @@ -171,3 +177,4 @@ class CargoMovement(BaseModel): ] ] ] = None + trades: Optional[List[CargoMovementTradeEntry]] = None diff --git a/vortexasdk/endpoints/canal_transit.py b/vortexasdk/endpoints/canal_transit.py index b6a135e6..c6f3c902 100644 --- a/vortexasdk/endpoints/canal_transit.py +++ b/vortexasdk/endpoints/canal_transit.py @@ -55,15 +55,13 @@ def search( filter_canal: Optional[str] = None, filter_direction: Optional[str] = None, filter_lock: Optional[str] = None, - exclude_filter_vessels: Optional[Union[ID, List[ID]]] = None, - exclude_filter_vessel_classes: Optional[Union[ID, List[ID]]] = None, - exclude_filter_products: Optional[Union[ID, List[ID]]] = None, - exclude_filter_origin: Optional[Union[ID, List[ID]]] = None, - exclude_filter_destination: Optional[Union[ID, List[ID]]] = None, - exclude_filter_charterer: Optional[Union[ID, List[ID]]] = None, - exclude_filter_effective_controller: Optional[ - Union[ID, List[ID]] - ] = None, + exclude_vessels: Optional[Union[ID, List[ID]]] = None, + exclude_vessel_classes: Optional[Union[ID, List[ID]]] = None, + exclude_products: Optional[Union[ID, List[ID]]] = None, + exclude_origin: Optional[Union[ID, List[ID]]] = None, + exclude_destination: Optional[Union[ID, List[ID]]] = None, + exclude_charterer: Optional[Union[ID, List[ID]]] = None, + exclude_effective_controller: Optional[Union[ID, List[ID]]] = None, ) -> CanalTransitResult: """ @@ -121,19 +119,19 @@ def search( updated_since: The UTC date of last record update time, - exclude_filter_vessels: A vessel ID, or list of vessel IDs to exclude, + exclude_vessels: A vessel ID, or list of vessel IDs to exclude, - exclude_filter_vessel_classes: A vessel class, or list of vessel classes to exclude, + exclude_vessel_classes: A vessel class, or list of vessel classes to exclude, - exclude_filter_products: A product ID, or list of product IDs to exclude, + exclude_products: A product ID, or list of product IDs to exclude, - exclude_filter_origin: A geography ID, or list of geography IDs to exclude, + exclude_origin: A geography ID, or list of geography IDs to exclude, - exclude_filter_destination: A geography ID, or list of geography IDs to exclude, + exclude_destination: A geography ID, or list of geography IDs to exclude, - exclude_filter_charterer: A charterer ID, or list of charterer IDs to exclude, + exclude_charterer: A charterer ID, or list of charterer IDs to exclude, - exclude_filter_effective_controller: A effective controller ID, or list of IDs to exclude, + exclude_effective_controller: A effective controller ID, or list of IDs to exclude, # Returns `CanalTransitResults`, containing all the canal transit records matching the given search terms. @@ -141,16 +139,14 @@ def search( """ exclude_params: Dict[str, Any] = { - "filter_origin": convert_to_list(exclude_filter_origin), - "filter_destination": convert_to_list(exclude_filter_destination), - "filter_products": convert_to_list(exclude_filter_products), - "filter_vessels": convert_to_list(exclude_filter_vessels), - "filter_vessel_classes": convert_to_list( - exclude_filter_vessel_classes - ), - "filter_charterers": convert_to_list(exclude_filter_charterer), + "filter_origin": convert_to_list(exclude_origin), + "filter_destination": convert_to_list(exclude_destination), + "filter_products": convert_to_list(exclude_products), + "filter_vessels": convert_to_list(exclude_vessels), + "filter_vessel_classes": convert_to_list(exclude_vessel_classes), + "filter_charterers": convert_to_list(exclude_charterer), "filter_effective_controllers": convert_to_list( - exclude_filter_effective_controller + exclude_effective_controller ), } diff --git a/vortexasdk/endpoints/canal_transit_timeseries.py b/vortexasdk/endpoints/canal_transit_timeseries.py index 255d67a7..31c94131 100644 --- a/vortexasdk/endpoints/canal_transit_timeseries.py +++ b/vortexasdk/endpoints/canal_transit_timeseries.py @@ -56,15 +56,13 @@ def search( timeseries_activity: str = "started_waiting", metric: str = "count_of_vessels", timeseries_frequency: str = "day", - exclude_filter_vessels: Optional[Union[ID, List[ID]]] = None, - exclude_filter_vessel_classes: Optional[Union[ID, List[ID]]] = None, - exclude_filter_products: Optional[Union[ID, List[ID]]] = None, - exclude_filter_origin: Optional[Union[ID, List[ID]]] = None, - exclude_filter_destination: Optional[Union[ID, List[ID]]] = None, - exclude_filter_charterer: Optional[Union[ID, List[ID]]] = None, - exclude_filter_effective_controller: Optional[ - Union[ID, List[ID]] - ] = None, + exclude_vessels: Optional[Union[ID, List[ID]]] = None, + exclude_vessel_classes: Optional[Union[ID, List[ID]]] = None, + exclude_products: Optional[Union[ID, List[ID]]] = None, + exclude_origin: Optional[Union[ID, List[ID]]] = None, + exclude_destination: Optional[Union[ID, List[ID]]] = None, + exclude_charterer: Optional[Union[ID, List[ID]]] = None, + exclude_effective_controller: Optional[Union[ID, List[ID]]] = None, ) -> TimeSeriesResult: """ @@ -132,19 +130,19 @@ def search( timeseries_frequency: Frequency denoting the granularity of the time series. Must be one of [`'day'`, `'week'`] - exclude_filter_vessels: A vessel ID, or list of vessel IDs to exclude, + exclude_vessels: A vessel ID, or list of vessel IDs to exclude, - exclude_filter_vessel_classes: A vessel class, or list of vessel classes to exclude, + exclude_vessel_classes: A vessel class, or list of vessel classes to exclude, - exclude_filter_products: A product ID, or list of product IDs to exclude, + exclude_products: A product ID, or list of product IDs to exclude, - exclude_filter_origin: A geography ID, or list of geography IDs to exclude, + exclude_origin: A geography ID, or list of geography IDs to exclude, - exclude_filter_destination: A geography ID, or list of geography IDs to exclude, + exclude_destination: A geography ID, or list of geography IDs to exclude, - exclude_filter_charterer: A charterer ID, or list of charterer IDs to exclude, + exclude_charterer: A charterer ID, or list of charterer IDs to exclude, - exclude_filter_effective_controller: A effective controller ID, or list of IDs to exclude, + exclude_effective_controller: A effective controller ID, or list of IDs to exclude, # Returns `CanalTransitTimeseries` @@ -152,16 +150,14 @@ def search( """ exclude_params: Dict[str, Any] = { - "filter_origin": convert_to_list(exclude_filter_origin), - "filter_destination": convert_to_list(exclude_filter_destination), - "filter_products": convert_to_list(exclude_filter_products), - "filter_vessels": convert_to_list(exclude_filter_vessels), - "filter_vessel_classes": convert_to_list( - exclude_filter_vessel_classes - ), - "filter_charterers": convert_to_list(exclude_filter_charterer), + "filter_origin": convert_to_list(exclude_origin), + "filter_destination": convert_to_list(exclude_destination), + "filter_products": convert_to_list(exclude_products), + "filter_vessels": convert_to_list(exclude_vessels), + "filter_vessel_classes": convert_to_list(exclude_vessel_classes), + "filter_charterers": convert_to_list(exclude_charterer), "filter_effective_controllers": convert_to_list( - exclude_filter_effective_controller + exclude_effective_controller ), } diff --git a/vortexasdk/endpoints/cargo_movements.py b/vortexasdk/endpoints/cargo_movements.py index afa6ae54..214402b7 100644 --- a/vortexasdk/endpoints/cargo_movements.py +++ b/vortexasdk/endpoints/cargo_movements.py @@ -50,6 +50,8 @@ def search( filter_vessel_owners: Optional[Union[ID, List[ID]]] = None, filter_time_charterers: Optional[Union[ID, List[ID]]] = None, filter_effective_controllers: Optional[Union[ID, List[ID]]] = None, + filter_shipper: Optional[Union[ID, List[ID]]] = None, + filter_consignee: Optional[Union[ID, List[ID]]] = None, filter_products: Optional[Union[ID, List[ID]]] = None, filter_vessels: Optional[Union[ID, List[ID]]] = None, filter_vessel_classes: Optional[Union[str, List[str]]] = None, @@ -70,8 +72,10 @@ def search( exclude_charterers: Optional[Union[ID, List[ID]]] = None, exclude_owners: Optional[Union[ID, List[ID]]] = None, exclude_effective_controllers: Optional[Union[ID, List[ID]]] = None, - exclude_filter_vessel_owners: Optional[Union[ID, List[ID]]] = None, - exclude_filter_time_charterers: Optional[Union[ID, List[ID]]] = None, + exclude_vessel_owners: Optional[Union[ID, List[ID]]] = None, + exclude_time_charterers: Optional[Union[ID, List[ID]]] = None, + exclude_shipper: Optional[Union[ID, List[ID]]] = None, + exclude_consignee: Optional[Union[ID, List[ID]]] = None, exclude_vessel_flags: Optional[Union[ID, List[ID]]] = None, exclude_vessel_ice_class: Optional[Union[ID, List[ID]]] = None, exclude_vessel_propulsion: Optional[Union[ID, List[ID]]] = None, @@ -107,6 +111,10 @@ def search( filter_time_charterers: An time charterer ID, or list of time charterers IDs to filter on. + filter_shipper: A shipper ID, or list of shipper IDs to filter on. + + filter_consignee: A consignee ID, or list of consignee IDs to filter on. + filter_products: A product ID, or list of product IDs to filter on. filter_vessels: A vessel ID, or list of vessel IDs to filter on. @@ -143,11 +151,15 @@ def search( exclude_charterers: A charterer ID, or list of charterer IDs to exclude. - exclude_filter_effective_controllers: An effective controller ID, or list of effective controller IDs to exclude. + exclude_effective_controllers: An effective controller ID, or list of effective controller IDs to exclude. + + exclude_vessel_owners: An vessel owner ID, or list of vessel owners IDs to exclude. - exclude_filter_vessel_owners: An vessel owner ID, or list of vessel owners IDs to filter on. + exclude_time_charterers: An time charterer ID, or list of time charterers IDs to exclude. - exclude_filter_time_charterers: An time charterer ID, or list of time charterers IDs to filter on. + exclude_shipper: A shipper ID, or list of shipper IDs to exclude. + + exclude_consignee: A consignee ID, or list of consignee IDs to exclude. exclude_vessel_flags: A geography ID, or list of geography IDs to exclude. @@ -249,12 +261,10 @@ def search( "filter_effective_controllers": convert_to_list( exclude_effective_controllers ), - "filter_vessel_owners": convert_to_list( - exclude_filter_vessel_owners - ), - "filter_time_charterers": convert_to_list( - exclude_filter_time_charterers - ), + "filter_shipper": convert_to_list(exclude_shipper), + "filter_consignee": convert_to_list(exclude_consignee), + "filter_vessel_owners": convert_to_list(exclude_vessel_owners), + "filter_time_charterers": convert_to_list(exclude_time_charterers), "filter_vessel_flags": convert_to_list(exclude_vessel_flags), "filter_vessel_ice_class": convert_to_list( exclude_vessel_ice_class @@ -276,6 +286,8 @@ def search( ), "filter_vessel_owners": convert_to_list(filter_vessel_owners), "filter_time_charterers": convert_to_list(filter_time_charterers), + "filter_shipper": convert_to_list(filter_shipper), + "filter_consignee": convert_to_list(filter_consignee), "filter_products": convert_to_list(filter_products), "filter_vessels": convert_to_list(filter_vessels), "filter_vessel_classes": convert_to_list(filter_vessel_classes), diff --git a/vortexasdk/endpoints/cargo_movements_result.py b/vortexasdk/endpoints/cargo_movements_result.py index 4a66322a..ac864ce2 100644 --- a/vortexasdk/endpoints/cargo_movements_result.py +++ b/vortexasdk/endpoints/cargo_movements_result.py @@ -553,6 +553,9 @@ def to_df( 'parent_ids.0.splinter_timestamp', 'parent_ids.1.id', 'parent_ids.1.splinter_timestamp', + 'trades.0.type', + 'trades.0.id', + 'trades.0.label' ] ``` diff --git a/vortexasdk/endpoints/cargo_timeseries.py b/vortexasdk/endpoints/cargo_timeseries.py index 19e82d12..4e97258f 100644 --- a/vortexasdk/endpoints/cargo_timeseries.py +++ b/vortexasdk/endpoints/cargo_timeseries.py @@ -42,6 +42,8 @@ def search( filter_vessel_owners: Optional[Union[ID, List[ID]]] = None, filter_time_charterers: Optional[Union[ID, List[ID]]] = None, filter_effective_controllers: Optional[Union[ID, List[ID]]] = None, + filter_shipper: Optional[Union[ID, List[ID]]] = None, + filter_consignee: Optional[Union[ID, List[ID]]] = None, filter_products: Optional[Union[ID, List[ID]]] = None, filter_vessels: Optional[Union[ID, List[ID]]] = None, filter_vessel_classes: Optional[Union[ID, List[ID]]] = None, @@ -56,6 +58,8 @@ def search( exclude_charterers: Optional[Union[ID, List[ID]]] = None, exclude_vessel_owners: Optional[Union[ID, List[ID]]] = None, exclude_time_charterers: Optional[Union[ID, List[ID]]] = None, + exclude_shipper: Optional[Union[ID, List[ID]]] = None, + exclude_consignee: Optional[Union[ID, List[ID]]] = None, exclude_origins: Optional[Union[ID, List[ID]]] = None, exclude_products: Optional[Union[ID, List[ID]]] = None, exclude_vessels: Optional[Union[ID, List[ID]]] = None, @@ -106,6 +110,10 @@ def search( filter_time_charterers: An time charterer ID, or list of time charterers IDs to filter on. + filter_shipper: A shipper ID, or list of shipper IDs to filter on. + + filter_consignee: A consignee ID, or list of consignee IDs to filter on. + filter_products: A product ID, or list of product IDs to filter on. filter_vessels: A vessel ID, or list of vessel IDs to filter on. @@ -146,6 +154,10 @@ def search( exclude_time_charterers: An time charterer ID, or list of time charterers IDs to filter on. + exclude_shipper: A shipper ID, or list of shipper IDs to exclude. + + exclude_consignee: A consignee ID, or list of consignee IDs to exclude. + exclude_vessel_flags: A geography ID, or list of geography IDs to exclude. exclude_vessel_ice_class: An attribute ID, or list of attribute IDs to exclude. @@ -183,7 +195,7 @@ def search( `destination_state_or_province`, `product_category`, `product_grade`, `product_group`, `product_group_product`, `vessel_class_group`, `vessel_class_coarse`, `vessel_class_granular`, `vessel_flag`, `storage_location_country`, `storage_location_region`, `storage_location_shipping_region_v2`, - `storage_location_trading_sub_region`, or not provided. + `storage_location_trading_sub_region`, `shipper`, `consignee`, or not provided. timeseries_unit: A numeric metric to be calculated for each time bucket. Must be one of ['b', 'bpd', 't', 'tpd', 'c', 'cpd'], corresponding to barrels, barrels per day, metric tonnes, metric tonnes per day, @@ -258,6 +270,8 @@ def search( "filter_effective_controllers": convert_to_list( exclude_effective_controllers ), + "filter_shipper": convert_to_list(exclude_shipper), + "filter_consignee": convert_to_list(exclude_consignee), "filter_owners": convert_to_list(exclude_owners), "filter_products": convert_to_list(exclude_products), "filter_ship_to_ship_locations": convert_to_list( @@ -292,6 +306,8 @@ def search( ), "filter_vessel_owners": convert_to_list(filter_vessel_owners), "filter_time_charterers": convert_to_list(filter_time_charterers), + "filter_shipper": convert_to_list(filter_shipper), + "filter_consignee": convert_to_list(filter_consignee), "filter_products": convert_to_list(filter_products), "filter_vessels": convert_to_list(filter_vessels), "filter_vessel_classes": convert_to_list(filter_vessel_classes), diff --git a/vortexasdk/endpoints/destination_breakdown.py b/vortexasdk/endpoints/destination_breakdown.py index 70123402..8add266f 100644 --- a/vortexasdk/endpoints/destination_breakdown.py +++ b/vortexasdk/endpoints/destination_breakdown.py @@ -45,6 +45,8 @@ def search( filter_vessel_classes: Optional[Union[str, List[str]]] = None, filter_owners: Optional[Union[ID, List[ID]]] = None, filter_effective_controllers: Optional[Union[ID, List[ID]]] = None, + filter_shipper: Optional[Union[ID, List[ID]]] = None, + filter_consignee: Optional[Union[ID, List[ID]]] = None, filter_vessel_flags: Optional[Union[ID, List[ID]]] = None, filter_vessel_ice_class: Optional[Union[ID, List[ID]]] = None, filter_vessel_propulsion: Optional[Union[ID, List[ID]]] = None, @@ -63,6 +65,8 @@ def search( exclude_owners: Optional[Union[ID, List[ID]]] = None, exclude_effective_controllers: Optional[Union[ID, List[ID]]] = None, exclude_charterers: Optional[Union[ID, List[ID]]] = None, + exclude_shipper: Optional[Union[ID, List[ID]]] = None, + exclude_consignee: Optional[Union[ID, List[ID]]] = None, exclude_vessel_flags: Optional[Union[ID, List[ID]]] = None, exclude_destinations: Optional[Union[ID, List[ID]]] = None, exclude_origins: Optional[Union[ID, List[ID]]] = None, @@ -75,129 +79,137 @@ def search( intra_movements: Optional[str] = None, ) -> ReferenceBreakdownResult: """ - Destination locations breakdown aggregation by geographic area + Destination locations breakdown aggregation by geographic area - # Arguments + # Arguments - breakdown_unit_average_basis: Per day metrics only - movement activity on which to base the average metric. Can be one of state properties of a cargo movement: `identified_for_loading_state`, `loading_state`, `transiting_state`, `storing_state`, `ship_to_ship`, `unloading_state`, `unloaded_state`, `oil_on_water_state`, `unknown_state`, or one of time properties of a cargo movement: `identified_for_loading_at`, `loading_start`, `loading_end`, `storing_start`, `storing_end`, `ship_to_ship_start`, `ship_to_ship_end`, `unloading_start`, `unloading_end`. + breakdown_unit_average_basis: Per day metrics only - movement activity on which to base the average metric. Can be one of state properties of a cargo movement: `identified_for_loading_state`, `loading_state`, `transiting_state`, `storing_state`, `ship_to_ship`, `unloading_state`, `unloaded_state`, `oil_on_water_state`, `unknown_state`, or one of time properties of a cargo movement: `identified_for_loading_at`, `loading_start`, `loading_end`, `storing_start`, `storing_end`, `ship_to_ship_start`, `ship_to_ship_end`, `unloading_start`, `unloading_end`. - breakdown_unit: Units to aggregate upon. Must be one of the following: `'b'`, `'t'`, `'cbm'`, `'bpd'`, `'tpd'`, `'mpd'`. + breakdown_unit: Units to aggregate upon. Must be one of the following: `'b'`, `'t'`, `'cbm'`, `'bpd'`, `'tpd'`, `'mpd'`. - breakdown_geography: Geography layer of the origin to aggregate upon. Must be one of the following: - `berth`, `terminal`, `port`, `country`, `country_zone`, `shipping_region`, `shipping_region_v2`, - `wider_shipping_region`, `region`, `alternative_region`, `trading_block`, `trading_region`, - `trading_subregion`, `state_or_province`, `sts_zone`, `waypoint`, `storage`, `storage_terminal`, `basin`, - `root`, or not provided. Default is `berth`. + breakdown_geography: Geography layer of the origin to aggregate upon. Must be one of the following: + `berth`, `terminal`, `port`, `country`, `country_zone`, `shipping_region`, `shipping_region_v2`, + `wider_shipping_region`, `region`, `alternative_region`, `trading_block`, `trading_region`, + `trading_subregion`, `state_or_province`, `sts_zone`, `waypoint`, `storage`, `storage_terminal`, `basin`, + `root`, or not provided. Default is `berth`. - breakdown_size: Number of top geographies to return. Default is 5. + breakdown_size: Number of top geographies to return. Default is 5. - disable_geographic_exclusion_rules: A boolean which specifies whether certain movements should be excluded, based on a combination of their origin and destination. + disable_geographic_exclusion_rules: A boolean which specifies whether certain movements should be excluded, based on a combination of their origin and destination. - filter_activity: Cargo movement activity on which to base the time filter. The endpoint only includes cargo - movements matching that match this filter in the aggregations. Must be one of ['loading_state', - 'loading_start', 'loading_end', 'identified_for_loading_state', 'unloading_state', 'unloading_start', - 'unloading_end', 'storing_state', 'storing_start', 'storing_end', 'transiting_state']. + filter_activity: Cargo movement activity on which to base the time filter. The endpoint only includes cargo + movements matching that match this filter in the aggregations. Must be one of ['loading_state', + 'loading_start', 'loading_end', 'identified_for_loading_state', 'unloading_state', 'unloading_start', + 'unloading_end', 'storing_state', 'storing_start', 'storing_end', 'transiting_state']. - filter_time_min: The UTC start date of the time filter. + filter_time_min: The UTC start date of the time filter. - filter_time_max: The UTC end date of the time filter. + filter_time_max: The UTC end date of the time filter. - filter_effective_controllers: An effective controller ID, or list of effective controller IDs to filter on. + filter_effective_controllers: An effective controller ID, or list of effective controller IDs to filter on. - filter_vessel_flags: A vessel flag ID, or list of vessel flag IDs to filter on. + filter_vessel_flags: A vessel flag ID, or list of vessel flag IDs to filter on. - filter_vessel_ice_class: An ice class ID, or list of ice class IDs to filter on. + filter_vessel_ice_class: An ice class ID, or list of ice class IDs to filter on. - filter_vessel_propulsion: An propulsion means ID, or list of propulsion means IDs to filter on. + filter_vessel_propulsion: An propulsion means ID, or list of propulsion means IDs to filter on. - filter_charterers: An commercial entity ID, or list of commercial entity IDs to filter on. + filter_charterers: An commercial entity ID, or list of commercial entity IDs to filter on. - filter_origins: A geography ID, or list of geography IDs to filter on. + filter_shipper: A shipper ID, or list of shipper IDs to filter on. - filter_destinations: A geography ID, or list of geography IDs to filter on. + filter_consignee: A consignee ID, or list of consignee IDs to filter on. - filter_storage_locations: A geography ID, or list of geography IDs to filter on. + filter_origins: A geography ID, or list of geography IDs to filter on. - filter_waypoints: A geography ID, or list of geography IDs to filter on. + filter_destinations: A geography ID, or list of geography IDs to filter on. - filter_ship_to_ship_locations: A geography ID, or list of geography IDs to filter on. + filter_storage_locations: A geography ID, or list of geography IDs to filter on. - filter_products: A product ID, or list of product IDs to filter on. + filter_waypoints: A geography ID, or list of geography IDs to filter on. - filter_vessels: A vessel ID, or list of vessel IDs to filter on. + filter_ship_to_ship_locations: A geography ID, or list of geography IDs to filter on. - filter_vessel_classes: A vessel class, or list of vessel classes to filter on. + filter_products: A product ID, or list of product IDs to filter on. - filter_vessel_age_min: A number between 1 and 100 (representing years). + filter_vessels: A vessel ID, or list of vessel IDs to filter on. - filter_vessel_age_max: A number between 1 and 100 (representing years). + filter_vessel_classes: A vessel class, or list of vessel classes to filter on. - filter_vessel_scrubbers: Either inactive 'disabled', or included 'inc' or excluded 'exc'. + filter_vessel_age_min: A number between 1 and 100 (representing years). - filter_vessel_tags: A time bound vessel tag, or list of time bound vessel tags to filter on. + filter_vessel_age_max: A number between 1 and 100 (representing years). - exclude_products: A product ID, or list of product IDs to exclude. + filter_vessel_scrubbers: Either inactive 'disabled', or included 'inc' or excluded 'exc'. - exclude_vessel_flags: A vessel flag ID, or list of vessel flag IDs to exclude. + filter_vessel_tags: A time bound vessel tag, or list of time bound vessel tags to filter on. - exclude_vessel_ice_class: An ice class ID, or list of ice class IDs to exclude. + exclude_products: A product ID, or list of product IDs to exclude. - exclude_vessel_propulsion: An propulsion means ID, or list of propulsion means IDs to exclude. + exclude_vessel_flags: A vessel flag ID, or list of vessel flag IDs to exclude. - exclude_vessels: A vessel ID, or list of vessel IDs to exclude. + exclude_vessel_ice_class: An ice class ID, or list of ice class IDs to exclude. - exclude_vessel_classes: A vessel class, or list of vessel classes to exclude. + exclude_vessel_propulsion: An propulsion means ID, or list of propulsion means IDs to exclude. - exclude_effective_controllers: An effective controller ID, or list of effective controller IDs to exclude. + exclude_vessels: A vessel ID, or list of vessel IDs to exclude. - exclude_vessel_location: A location ID, or list of location IDs to exclude. + exclude_vessel_classes: A vessel class, or list of vessel classes to exclude. - exclude_destinations: A location ID, or list of location IDs to exclude. + exclude_effective_controllers: An effective controller ID, or list of effective controller IDs to exclude. - exclude_origins: A location ID, or list of location IDs to exclude. + exclude_shipper: A shipper ID, or list of shipper IDs to exclude. - exclude_storage_locations: A location ID, or list of location IDs to exclude. + exclude_consignee: A consignee ID, or list of consignee IDs to exclude. - exclude_waypoints: A location ID, or list of location IDs to exclude. + exclude_vessel_location: A location ID, or list of location IDs to exclude. - exclude_ship_to_ship_locations: A location ID, or list of location IDs to exclude. + exclude_destinations: A location ID, or list of location IDs to exclude. - exclude_vessel_tags: A time bound vessel tag, or list of time bound vessel tags to exclude. + exclude_origins: A location ID, or list of location IDs to exclude. - intra_movements: This enum controls a popular industry term intra-movements and determines the filter behaviour for cargo leaving then entering the same geographic area. - One of `all`, `exclude_intra_country` or `exclude_intra_geography` + exclude_storage_locations: A location ID, or list of location IDs to exclude. - # Returns - `ReferenceBreakdownResult` + exclude_waypoints: A location ID, or list of location IDs to exclude. + exclude_ship_to_ship_locations: A location ID, or list of location IDs to exclude. - # Example + exclude_vessel_tags: A time bound vessel tag, or list of time bound vessel tags to exclude. + + intra_movements: This enum controls a popular industry term intra-movements and determines the filter behaviour for cargo leaving then entering the same geographic area. + One of `all`, `exclude_intra_country` or `exclude_intra_geography` + + # Returns + `ReferenceBreakdownResult` + + + # Example _Breakdown by destination terminal of cargoes departing from the port of origin over the last 5 days, in tonnes. - ```python - >>> from vortexasdk import DestinationBreakdown, Geographies - >>> start = datetime(2019, 11, 10) - >>> end = datetime(2019, 11, 15) - >>> df = DestinationBreakdown().search( - ... filter_activity="loading_end", - ... breakdown_geography="terminal", - ... breakdown_unit="t", - ... breakdown_size=5, - ... filter_time_min=start, - ... filter_time_max=end - ... ).to_df() - - ``` - - Gives the following: - - | | key | label | value | count | - |---:|:----------------------------------------------------------------|--------------------------------------------:|---------:|----------:| - | 0 | 606e73162cfd0492919ef96b04dae1bfddda09d148d03bafc1dc3eab979a9b0a| SPSE - DPF - G.I.E. Petroleum Terminal | 785819 | 12 | - | 1 | 844756c877c680ce0ff582a46b5bb1cf34cc33179df977a609b2c10838d9db5d| SK Energy (Ulsan) | 288529 | 11 | - | 2 | a5269f5a20759b3a120af66a298fa2385a2b81d8b248aec590db73ecd984f8b7| Dongying CNOOC Oil & Petrochemicals Shandong| 201283 | 11 | - | 3 | 78fcabe3bb6a47f2aa019ae9948be43c5ebbe08a2d1cba7b113315c85362cb7c| Kandla Oil Terminal | 121762 | 15 | - | 4 | 15db6ca55a3b13d3c4b135afcaf87f5d605680ac75177412af05be37fc3fec38| Pirpau Island | 62933 | 12 | + ```python + >>> from vortexasdk import DestinationBreakdown, Geographies + >>> start = datetime(2019, 11, 10) + >>> end = datetime(2019, 11, 15) + >>> df = DestinationBreakdown().search( + ... filter_activity="loading_end", + ... breakdown_geography="terminal", + ... breakdown_unit="t", + ... breakdown_size=5, + ... filter_time_min=start, + ... filter_time_max=end + ... ).to_df() + + ``` + + Gives the following: + + | | key | label | value | count | + |---:|:----------------------------------------------------------------|--------------------------------------------:|---------:|----------:| + | 0 | 606e73162cfd0492919ef96b04dae1bfddda09d148d03bafc1dc3eab979a9b0a| SPSE - DPF - G.I.E. Petroleum Terminal | 785819 | 12 | + | 1 | 844756c877c680ce0ff582a46b5bb1cf34cc33179df977a609b2c10838d9db5d| SK Energy (Ulsan) | 288529 | 11 | + | 2 | a5269f5a20759b3a120af66a298fa2385a2b81d8b248aec590db73ecd984f8b7| Dongying CNOOC Oil & Petrochemicals Shandong| 201283 | 11 | + | 3 | 78fcabe3bb6a47f2aa019ae9948be43c5ebbe08a2d1cba7b113315c85362cb7c| Kandla Oil Terminal | 121762 | 15 | + | 4 | 15db6ca55a3b13d3c4b135afcaf87f5d605680ac75177412af05be37fc3fec38| Pirpau Island | 62933 | 12 | """ @@ -216,6 +228,8 @@ def search( "filter_effective_controllers": convert_to_list( exclude_effective_controllers ), + "filter_shipper": convert_to_list(exclude_shipper), + "filter_consignee": convert_to_list(exclude_consignee), "filter_origins": convert_to_list(exclude_origins), "filter_flags": convert_to_list(exclude_vessel_flags), "filter_vessel_ice_class": convert_to_list( @@ -258,6 +272,8 @@ def search( "filter_effective_controllers": convert_to_list( filter_effective_controllers ), + "filter_shipper": convert_to_list(filter_shipper), + "filter_consignee": convert_to_list(filter_consignee), "filter_destinations": convert_to_list(filter_destinations), "filter_origins": convert_to_list(filter_origins), "filter_waypoints": convert_to_list(filter_waypoints), diff --git a/vortexasdk/endpoints/movement_status_breakdown.py b/vortexasdk/endpoints/movement_status_breakdown.py index 6946c545..bab860c0 100644 --- a/vortexasdk/endpoints/movement_status_breakdown.py +++ b/vortexasdk/endpoints/movement_status_breakdown.py @@ -45,6 +45,8 @@ def search( filter_vessel_classes: Optional[Union[str, List[str]]] = None, filter_owners: Optional[Union[ID, List[ID]]] = None, filter_effective_controllers: Optional[Union[ID, List[ID]]] = None, + filter_shipper: Optional[Union[ID, List[ID]]] = None, + filter_consignee: Optional[Union[ID, List[ID]]] = None, filter_vessel_flags: Optional[Union[ID, List[ID]]] = None, filter_vessel_ice_class: Optional[Union[ID, List[ID]]] = None, filter_vessel_propulsion: Optional[Union[ID, List[ID]]] = None, @@ -63,6 +65,8 @@ def search( exclude_owners: Optional[Union[ID, List[ID]]] = None, exclude_effective_controllers: Optional[Union[ID, List[ID]]] = None, exclude_charterers: Optional[Union[ID, List[ID]]] = None, + exclude_shipper: Optional[Union[ID, List[ID]]] = None, + exclude_consignee: Optional[Union[ID, List[ID]]] = None, exclude_vessel_flags: Optional[Union[ID, List[ID]]] = None, exclude_destinations: Optional[Union[ID, List[ID]]] = None, exclude_origins: Optional[Union[ID, List[ID]]] = None, @@ -75,127 +79,135 @@ def search( intra_movements: Optional[str] = None, ) -> ReferenceBreakdownResult: """ - Origin locations breakdown aggregation by geographic area + Origin locations breakdown aggregation by geographic area - # Arguments + # Arguments - breakdown_unit_average_basis: Per day metrics only - movement activity on which to base the average metric. Can be one of state properties of a cargo movement: `identified_for_loading_state`, `loading_state`, `transiting_state`, `storing_state`, `ship_to_ship`, `unloading_state`, `unloaded_state`, `oil_on_water_state`, `unknown_state`, or one of time properties of a cargo movement: `identified_for_loading_at`, `loading_start`, `loading_end`, `storing_start`, `storing_end`, `ship_to_ship_start`, `ship_to_ship_end`, `unloading_start`, `unloading_end`. + breakdown_unit_average_basis: Per day metrics only - movement activity on which to base the average metric. Can be one of state properties of a cargo movement: `identified_for_loading_state`, `loading_state`, `transiting_state`, `storing_state`, `ship_to_ship`, `unloading_state`, `unloaded_state`, `oil_on_water_state`, `unknown_state`, or one of time properties of a cargo movement: `identified_for_loading_at`, `loading_start`, `loading_end`, `storing_start`, `storing_end`, `ship_to_ship_start`, `ship_to_ship_end`, `unloading_start`, `unloading_end`. - breakdown_unit: Units to aggregate upon. Must be one of the following: `'b'`, `'t'`, `'cbm'`, `'bpd'`, `'tpd'`, `'mpd'`. + breakdown_unit: Units to aggregate upon. Must be one of the following: `'b'`, `'t'`, `'cbm'`, `'bpd'`, `'tpd'`, `'mpd'`. - timestamp: The UTC date of the specific movement status to search. + timestamp: The UTC date of the specific movement status to search. - breakdown_size: Number of top geographies to return. Default is 5. + breakdown_size: Number of top geographies to return. Default is 5. - disable_geographic_exclusion_rules: A boolean which specifies whether certain movements should be excluded, based on a combination of their origin and destination. + disable_geographic_exclusion_rules: A boolean which specifies whether certain movements should be excluded, based on a combination of their origin and destination. - intra_movements: This enum controls a popular industry term intra-movements and determines the filter behaviour for cargo leaving then entering the same geographic area. - One of `all`, `exclude_intra_country` or `exclude_intra_geography` + intra_movements: This enum controls a popular industry term intra-movements and determines the filter behaviour for cargo leaving then entering the same geographic area. + One of `all`, `exclude_intra_country` or `exclude_intra_geography` - filter_activity: Cargo movement activity on which to base the time filter. The endpoint only includes cargo - movements matching that match this filter in the aggregations. Must be one of ['loading_state', - 'loading_start', 'loading_end', 'identified_for_loading_state', 'unloading_state', 'unloading_start', - 'unloading_end', 'storing_state', 'storing_start', 'storing_end', 'transiting_state']. + filter_activity: Cargo movement activity on which to base the time filter. The endpoint only includes cargo + movements matching that match this filter in the aggregations. Must be one of ['loading_state', + 'loading_start', 'loading_end', 'identified_for_loading_state', 'unloading_state', 'unloading_start', + 'unloading_end', 'storing_state', 'storing_start', 'storing_end', 'transiting_state']. - filter_time_min: The UTC start date of the time filter. + filter_time_min: The UTC start date of the time filter. - filter_time_max: The UTC end date of the time filter. + filter_time_max: The UTC end date of the time filter. - filter_effective_controllers: An effective controller ID, or list of effective controller IDs to filter on. + filter_effective_controllers: An effective controller ID, or list of effective controller IDs to filter on. - filter_vessel_flags: A vessel flag ID, or list of vessel flag IDs to filter on. + filter_vessel_flags: A vessel flag ID, or list of vessel flag IDs to filter on. - filter_vessel_ice_class: An ice class ID, or list of ice class IDs to filter on. + filter_vessel_ice_class: An ice class ID, or list of ice class IDs to filter on. - filter_vessel_propulsion: An propulsion means ID, or list of propulsion means IDs to filter on. + filter_vessel_propulsion: An propulsion means ID, or list of propulsion means IDs to filter on. - filter_charterers: An commercial entity ID, or list of commercial entity IDs to filter on. + filter_charterers: An commercial entity ID, or list of commercial entity IDs to filter on. - filter_origins: A geography ID, or list of geography IDs to filter on. + filter_shipper: A shipper ID, or list of shipper IDs to filter on. - filter_destinations: A geography ID, or list of geography IDs to filter on. + filter_consignee: A consignee ID, or list of consignee IDs to filter on. - filter_storage_locations: A geography ID, or list of geography IDs to filter on. + filter_origins: A geography ID, or list of geography IDs to filter on. - filter_waypoints: A geography ID, or list of geography IDs to filter on. + filter_destinations: A geography ID, or list of geography IDs to filter on. - filter_ship_to_ship_locations: A geography ID, or list of geography IDs to filter on. + filter_storage_locations: A geography ID, or list of geography IDs to filter on. - filter_products: A product ID, or list of product IDs to filter on. + filter_waypoints: A geography ID, or list of geography IDs to filter on. - filter_vessels: A vessel ID, or list of vessel IDs to filter on. + filter_ship_to_ship_locations: A geography ID, or list of geography IDs to filter on. - filter_vessel_classes: A vessel class, or list of vessel classes to filter on. + filter_products: A product ID, or list of product IDs to filter on. - filter_vessel_age_min: A number between 1 and 100 (representing years). + filter_vessels: A vessel ID, or list of vessel IDs to filter on. - filter_vessel_age_max: A number between 1 and 100 (representing years). + filter_vessel_classes: A vessel class, or list of vessel classes to filter on. - filter_vessel_scrubbers: Either inactive 'disabled', or included 'inc' or excluded 'exc'. + filter_vessel_age_min: A number between 1 and 100 (representing years). - filter_vessel_tags: A time bound vessel tag, or list of time bound vessel tags to filter on. + filter_vessel_age_max: A number between 1 and 100 (representing years). - exclude_products: A product ID, or list of product IDs to exclude. + filter_vessel_scrubbers: Either inactive 'disabled', or included 'inc' or excluded 'exc'. - exclude_vessel_flags: A vessel flag ID, or list of vessel flag IDs to exclude. + filter_vessel_tags: A time bound vessel tag, or list of time bound vessel tags to filter on. - exclude_vessel_ice_class: An ice class ID, or list of ice class IDs to exclude. + exclude_products: A product ID, or list of product IDs to exclude. - exclude_vessel_propulsion: An propulsion means ID, or list of propulsion means IDs to exclude. + exclude_vessel_flags: A vessel flag ID, or list of vessel flag IDs to exclude. - exclude_vessels: A vessel ID, or list of vessel IDs to exclude. + exclude_vessel_ice_class: An ice class ID, or list of ice class IDs to exclude. - exclude_vessel_classes: A vessel class, or list of vessel classes to exclude. + exclude_vessel_propulsion: An propulsion means ID, or list of propulsion means IDs to exclude. - exclude_effective_controllers: An effective controller ID, or list of effective controller IDs to exclude. + exclude_vessels: A vessel ID, or list of vessel IDs to exclude. - exclude_vessel_location: A location ID, or list of location IDs to exclude. + exclude_vessel_classes: A vessel class, or list of vessel classes to exclude. - exclude_destinations: A location ID, or list of location IDs to exclude. + exclude_effective_controllers: An effective controller ID, or list of effective controller IDs to exclude. - exclude_origins: A location ID, or list of location IDs to exclude. + exclude_shipper: A shipper ID, or list of shipper IDs to exclude. - exclude_storage_locations: A location ID, or list of location IDs to exclude. + exclude_consignee: A consignee ID, or list of consignee IDs to exclude. - exclude_waypoints: A location ID, or list of location IDs to exclude. + exclude_vessel_location: A location ID, or list of location IDs to exclude. - exclude_ship_to_ship_locations: A location ID, or list of location IDs to exclude. + exclude_destinations: A location ID, or list of location IDs to exclude. - exclude_vessel_tags: A time bound vessel tag, or list of time bound vessel tags to exclude. + exclude_origins: A location ID, or list of location IDs to exclude. - # Returns - `ReferenceBreakdownResult` + exclude_storage_locations: A location ID, or list of location IDs to exclude. + exclude_waypoints: A location ID, or list of location IDs to exclude. - # Example + exclude_ship_to_ship_locations: A location ID, or list of location IDs to exclude. + + exclude_vessel_tags: A time bound vessel tag, or list of time bound vessel tags to exclude. + + # Returns + `ReferenceBreakdownResult` + + + # Example _Breakdown by movement status of cargoes in tonnes._ - ```python - >>> from vortexasdk import MovementStatusBreakdown - >>> start = datetime(2019, 11, 10) - >>> timestamp = datetime(2019, 1, 19) - >>> end = datetime(2033, 11, 15) - >>> df = MovementStatusBreakdown().search( - ... filter_activity="loading_end", - ... timestamp=timestamp, - ... breakdown_unit="t", - ... breakdown_size=5, - ... filter_time_min=start, - ... filter_time_max=end - ... ).to_df() - - ``` - - Gives the following: - - | | key | value | count | - |---:|:--------------------------------|---------:|----------:| - | 0 | transiting_state | 3009799 | 24 | - | 1 | identified_for_loading_state | 776599 | 17 | - | 2 | loading_state | 381359 | 24 | - | 3 | unloading_state | 238723 | 21 | - | 4 | storing_state | 118285 | 18 | - | 4 | ship_to_ship | 118285 | 18 | + ```python + >>> from vortexasdk import MovementStatusBreakdown + >>> start = datetime(2019, 11, 10) + >>> timestamp = datetime(2019, 1, 19) + >>> end = datetime(2033, 11, 15) + >>> df = MovementStatusBreakdown().search( + ... filter_activity="loading_end", + ... timestamp=timestamp, + ... breakdown_unit="t", + ... breakdown_size=5, + ... filter_time_min=start, + ... filter_time_max=end + ... ).to_df() + + ``` + + Gives the following: + + | | key | value | count | + |---:|:--------------------------------|---------:|----------:| + | 0 | transiting_state | 3009799 | 24 | + | 1 | identified_for_loading_state | 776599 | 17 | + | 2 | loading_state | 381359 | 24 | + | 3 | unloading_state | 238723 | 21 | + | 4 | storing_state | 118285 | 18 | + | 4 | ship_to_ship | 118285 | 18 | """ @@ -214,6 +226,8 @@ def search( "filter_effective_controllers": convert_to_list( exclude_effective_controllers ), + "filter_shipper": convert_to_list(exclude_shipper), + "filter_consignee": convert_to_list(exclude_consignee), "filter_origins": convert_to_list(exclude_origins), "filter_flags": convert_to_list(exclude_vessel_flags), "filter_vessel_ice_class": convert_to_list( @@ -255,6 +269,8 @@ def search( "filter_effective_controllers": convert_to_list( filter_effective_controllers ), + "filter_shipper": convert_to_list(filter_shipper), + "filter_consignee": convert_to_list(filter_consignee), "filter_destinations": convert_to_list(filter_destinations), "filter_origins": convert_to_list(filter_origins), "filter_waypoints": convert_to_list(filter_waypoints), diff --git a/vortexasdk/endpoints/origin_breakdown.py b/vortexasdk/endpoints/origin_breakdown.py index d957ddb3..2902ce81 100644 --- a/vortexasdk/endpoints/origin_breakdown.py +++ b/vortexasdk/endpoints/origin_breakdown.py @@ -45,6 +45,8 @@ def search( filter_vessel_classes: Optional[Union[str, List[str]]] = None, filter_owners: Optional[Union[ID, List[ID]]] = None, filter_effective_controllers: Optional[Union[ID, List[ID]]] = None, + filter_shipper: Optional[Union[ID, List[ID]]] = None, + filter_consignee: Optional[Union[ID, List[ID]]] = None, filter_vessel_flags: Optional[Union[ID, List[ID]]] = None, filter_vessel_ice_class: Optional[Union[ID, List[ID]]] = None, filter_vessel_propulsion: Optional[Union[ID, List[ID]]] = None, @@ -63,6 +65,8 @@ def search( exclude_owners: Optional[Union[ID, List[ID]]] = None, exclude_effective_controllers: Optional[Union[ID, List[ID]]] = None, exclude_charterers: Optional[Union[ID, List[ID]]] = None, + exclude_shipper: Optional[Union[ID, List[ID]]] = None, + exclude_consignee: Optional[Union[ID, List[ID]]] = None, exclude_vessel_flags: Optional[Union[ID, List[ID]]] = None, exclude_destinations: Optional[Union[ID, List[ID]]] = None, exclude_origins: Optional[Union[ID, List[ID]]] = None, @@ -75,129 +79,137 @@ def search( intra_movements: Optional[str] = None, ) -> ReferenceBreakdownResult: """ - Origin locations breakdown aggregation by geographic area + Origin locations breakdown aggregation by geographic area - # Arguments + # Arguments - breakdown_unit_average_basis: Per day metrics only - movement activity on which to base the average metric. Can be one of state properties of a cargo movement: `identified_for_loading_state`, `loading_state`, `transiting_state`, `storing_state`, `ship_to_ship`, `unloading_state`, `unloaded_state`, `oil_on_water_state`, `unknown_state`, or one of time properties of a cargo movement: `identified_for_loading_at`, `loading_start`, `loading_end`, `storing_start`, `storing_end`, `ship_to_ship_start`, `ship_to_ship_end`, `unloading_start`, `unloading_end`. + breakdown_unit_average_basis: Per day metrics only - movement activity on which to base the average metric. Can be one of state properties of a cargo movement: `identified_for_loading_state`, `loading_state`, `transiting_state`, `storing_state`, `ship_to_ship`, `unloading_state`, `unloaded_state`, `oil_on_water_state`, `unknown_state`, or one of time properties of a cargo movement: `identified_for_loading_at`, `loading_start`, `loading_end`, `storing_start`, `storing_end`, `ship_to_ship_start`, `ship_to_ship_end`, `unloading_start`, `unloading_end`. - breakdown_unit: Units to aggregate upon. Must be one of the following: `'b'`, `'t'`, `'cbm'`, `'bpd'`, `'tpd'`, `'mpd'`. + breakdown_unit: Units to aggregate upon. Must be one of the following: `'b'`, `'t'`, `'cbm'`, `'bpd'`, `'tpd'`, `'mpd'`. - breakdown_geography: Geography layer of the origin to aggregate upon. Must be one of the following: - `berth`, `terminal`, `port`, `country`, `country_zone`, `shipping_region`, `shipping_region_v2`, - `wider_shipping_region`, `region`, `alternative_region`, `trading_block`, `trading_region`, - `trading_subregion`, `state_or_province`, `sts_zone`, `waypoint`, `storage`, `storage_terminal`, `basin`, - `root`, or not provided. Default is `berth`. + breakdown_geography: Geography layer of the origin to aggregate upon. Must be one of the following: + `berth`, `terminal`, `port`, `country`, `country_zone`, `shipping_region`, `shipping_region_v2`, + `wider_shipping_region`, `region`, `alternative_region`, `trading_block`, `trading_region`, + `trading_subregion`, `state_or_province`, `sts_zone`, `waypoint`, `storage`, `storage_terminal`, `basin`, + `root`, or not provided. Default is `berth`. - breakdown_size: Number of top geographies to return. Default is 5. + breakdown_size: Number of top geographies to return. Default is 5. - disable_geographic_exclusion_rules: A boolean which specifies whether certain movements should be excluded, based on a combination of their origin and destination. + disable_geographic_exclusion_rules: A boolean which specifies whether certain movements should be excluded, based on a combination of their origin and destination. - intra_movements: This enum controls a popular industry term intra-movements and determines the filter behaviour for cargo leaving then entering the same geographic area. - One of `all`, `exclude_intra_country` or `exclude_intra_geography` + intra_movements: This enum controls a popular industry term intra-movements and determines the filter behaviour for cargo leaving then entering the same geographic area. + One of `all`, `exclude_intra_country` or `exclude_intra_geography` - filter_activity: Cargo movement activity on which to base the time filter. The endpoint only includes cargo - movements matching that match this filter in the aggregations. Must be one of ['loading_state', - 'loading_start', 'loading_end', 'identified_for_loading_state', 'unloading_state', 'unloading_start', - 'unloading_end', 'storing_state', 'storing_start', 'storing_end', 'transiting_state']. + filter_activity: Cargo movement activity on which to base the time filter. The endpoint only includes cargo + movements matching that match this filter in the aggregations. Must be one of ['loading_state', + 'loading_start', 'loading_end', 'identified_for_loading_state', 'unloading_state', 'unloading_start', + 'unloading_end', 'storing_state', 'storing_start', 'storing_end', 'transiting_state']. - filter_time_min: The UTC start date of the time filter. + filter_time_min: The UTC start date of the time filter. - filter_time_max: The UTC end date of the time filter. + filter_time_max: The UTC end date of the time filter. - filter_effective_controllers: An effective controller ID, or list of effective controller IDs to filter on. + filter_effective_controllers: An effective controller ID, or list of effective controller IDs to filter on. - filter_vessel_flags: A vessel flag ID, or list of vessel flag IDs to filter on. + filter_vessel_flags: A vessel flag ID, or list of vessel flag IDs to filter on. - filter_vessel_ice_class: An ice class ID, or list of ice class IDs to filter on. + filter_vessel_ice_class: An ice class ID, or list of ice class IDs to filter on. - filter_vessel_propulsion: An propulsion means ID, or list of propulsion means IDs to filter on. + filter_vessel_propulsion: An propulsion means ID, or list of propulsion means IDs to filter on. - filter_charterers: An commercial entity ID, or list of commercial entity IDs to filter on. + filter_charterers: An commercial entity ID, or list of commercial entity IDs to filter on. - filter_origins: A geography ID, or list of geography IDs to filter on. + filter_shipper: A shipper ID, or list of shipper IDs to filter on. - filter_destinations: A geography ID, or list of geography IDs to filter on. + filter_consignee: A consignee ID, or list of consignee IDs to filter on. - filter_storage_locations: A geography ID, or list of geography IDs to filter on. + filter_origins: A geography ID, or list of geography IDs to filter on. - filter_waypoints: A geography ID, or list of geography IDs to filter on. + filter_destinations: A geography ID, or list of geography IDs to filter on. - filter_ship_to_ship_locations: A geography ID, or list of geography IDs to filter on. + filter_storage_locations: A geography ID, or list of geography IDs to filter on. - filter_products: A product ID, or list of product IDs to filter on. + filter_waypoints: A geography ID, or list of geography IDs to filter on. - filter_vessels: A vessel ID, or list of vessel IDs to filter on. + filter_ship_to_ship_locations: A geography ID, or list of geography IDs to filter on. - filter_vessel_classes: A vessel class, or list of vessel classes to filter on. + filter_products: A product ID, or list of product IDs to filter on. - filter_vessel_age_min: A number between 1 and 100 (representing years). + filter_vessels: A vessel ID, or list of vessel IDs to filter on. - filter_vessel_age_max: A number between 1 and 100 (representing years). + filter_vessel_classes: A vessel class, or list of vessel classes to filter on. - filter_vessel_scrubbers: Either inactive 'disabled', or included 'inc' or excluded 'exc'. + filter_vessel_age_min: A number between 1 and 100 (representing years). - filter_vessel_tags: A time bound vessel tag, or list of time bound vessel tags to filter on. + filter_vessel_age_max: A number between 1 and 100 (representing years). - exclude_products: A product ID, or list of product IDs to exclude. + filter_vessel_scrubbers: Either inactive 'disabled', or included 'inc' or excluded 'exc'. - exclude_vessel_flags: A vessel flag ID, or list of vessel flag IDs to exclude. + filter_vessel_tags: A time bound vessel tag, or list of time bound vessel tags to filter on. - exclude_vessel_ice_class: An ice class ID, or list of ice class IDs to exclude. + exclude_products: A product ID, or list of product IDs to exclude. - exclude_vessel_propulsion: An propulsion means ID, or list of propulsion means IDs to exclude. + exclude_vessel_flags: A vessel flag ID, or list of vessel flag IDs to exclude. - exclude_vessels: A vessel ID, or list of vessel IDs to exclude. + exclude_vessel_ice_class: An ice class ID, or list of ice class IDs to exclude. - exclude_vessel_classes: A vessel class, or list of vessel classes to exclude. + exclude_vessel_propulsion: An propulsion means ID, or list of propulsion means IDs to exclude. - exclude_effective_controllers: An effective controller ID, or list of effective controller IDs to exclude. + exclude_vessels: A vessel ID, or list of vessel IDs to exclude. - exclude_vessel_location: A location ID, or list of location IDs to exclude. + exclude_vessel_classes: A vessel class, or list of vessel classes to exclude. - exclude_destinations: A location ID, or list of location IDs to exclude. + exclude_effective_controllers: An effective controller ID, or list of effective controller IDs to exclude. - exclude_origins: A location ID, or list of location IDs to exclude. + exclude_shipper: A shipper ID, or list of shipper IDs to exclude. - exclude_storage_locations: A location ID, or list of location IDs to exclude. + exclude_consignee: A consignee ID, or list of consignee IDs to exclude. - exclude_waypoints: A location ID, or list of location IDs to exclude. + exclude_vessel_location: A location ID, or list of location IDs to exclude. - exclude_ship_to_ship_locations: A location ID, or list of location IDs to exclude. + exclude_destinations: A location ID, or list of location IDs to exclude. - exclude_vessel_tags: A time bound vessel tag, or list of time bound vessel tags to exclude. + exclude_origins: A location ID, or list of location IDs to exclude. - # Returns - `ReferenceBreakdownResult` + exclude_storage_locations: A location ID, or list of location IDs to exclude. + exclude_waypoints: A location ID, or list of location IDs to exclude. - # Example + exclude_ship_to_ship_locations: A location ID, or list of location IDs to exclude. + + exclude_vessel_tags: A time bound vessel tag, or list of time bound vessel tags to exclude. + + # Returns + `ReferenceBreakdownResult` + + + # Example _Breakdown by origin terminal of cargoes departing from the port of origin over the last 5 days, in tonnes._ - ```python - >>> from vortexasdk import OriginBreakdown, Geographies - >>> start = datetime(2019, 11, 10) - >>> end = datetime(2019, 11, 15) - >>> df = OriginBreakdown().search( - ... filter_activity="loading_end", - ... breakdown_geography="terminal", - ... breakdown_unit="t", - ... breakdown_size=5, - ... filter_time_min=start, - ... filter_time_max=end - ... ).to_df() - - ``` - - Gives the following: - - | | key | label | value | count | - |---:|:----------------------------------------------------------------|-----------------------------------------:|---------:|----------:| - | 0 | c3daea3cc9c5b3bd91c90882d42c2a418c4cf17b90ff12da3ac78444282a238a| Juaymah Crude Oil Terminal | 3009799 | 24 | - | 1 | 3a39cf841ece0c7cb879f72af01cb634191142e0de8010d5ef877fd66c2e8605| Houston Enterprise Terminal | 776599 | 17 | - | 2 | 345b7661310bc82a04e0a4edffd02c286c410c023b53edfb90ed3386640c0476| Arzew GL1Z/GL2Z LNG Terminal | 381359 | 24 | - | 3 | 9dfa3be1b42d1f5e80361b6f442b5217b486876ad0c25e382055887c9e231ad2| SabTank (PCQ-1) Al Jubail | 238723 | 21 | - | 4 | 4813dd7209e85b128cc2fbc7c08fef08d26259550210f28a5c7ff3ccd7b2ba61| Mailiao Industrial Park-Formosa Plastics | 118285 | 18 | + ```python + >>> from vortexasdk import OriginBreakdown, Geographies + >>> start = datetime(2019, 11, 10) + >>> end = datetime(2019, 11, 15) + >>> df = OriginBreakdown().search( + ... filter_activity="loading_end", + ... breakdown_geography="terminal", + ... breakdown_unit="t", + ... breakdown_size=5, + ... filter_time_min=start, + ... filter_time_max=end + ... ).to_df() + + ``` + + Gives the following: + + | | key | label | value | count | + |---:|:----------------------------------------------------------------|-----------------------------------------:|---------:|----------:| + | 0 | c3daea3cc9c5b3bd91c90882d42c2a418c4cf17b90ff12da3ac78444282a238a| Juaymah Crude Oil Terminal | 3009799 | 24 | + | 1 | 3a39cf841ece0c7cb879f72af01cb634191142e0de8010d5ef877fd66c2e8605| Houston Enterprise Terminal | 776599 | 17 | + | 2 | 345b7661310bc82a04e0a4edffd02c286c410c023b53edfb90ed3386640c0476| Arzew GL1Z/GL2Z LNG Terminal | 381359 | 24 | + | 3 | 9dfa3be1b42d1f5e80361b6f442b5217b486876ad0c25e382055887c9e231ad2| SabTank (PCQ-1) Al Jubail | 238723 | 21 | + | 4 | 4813dd7209e85b128cc2fbc7c08fef08d26259550210f28a5c7ff3ccd7b2ba61| Mailiao Industrial Park-Formosa Plastics | 118285 | 18 | """ @@ -216,6 +228,8 @@ def search( "filter_effective_controllers": convert_to_list( exclude_effective_controllers ), + "filter_shipper": convert_to_list(exclude_shipper), + "filter_consignee": convert_to_list(exclude_consignee), "filter_origins": convert_to_list(exclude_origins), "filter_flags": convert_to_list(exclude_vessel_flags), "filter_vessel_ice_class": convert_to_list( @@ -257,6 +271,8 @@ def search( "filter_effective_controllers": convert_to_list( filter_effective_controllers ), + "filter_shipper": convert_to_list(filter_shipper), + "filter_consignee": convert_to_list(filter_consignee), "filter_destinations": convert_to_list(filter_destinations), "filter_origins": convert_to_list(filter_origins), "filter_waypoints": convert_to_list(filter_waypoints), diff --git a/vortexasdk/endpoints/parent_product_breakdown.py b/vortexasdk/endpoints/parent_product_breakdown.py index 9c2a0622..6ea016b3 100644 --- a/vortexasdk/endpoints/parent_product_breakdown.py +++ b/vortexasdk/endpoints/parent_product_breakdown.py @@ -44,6 +44,8 @@ def search( filter_vessel_classes: Optional[Union[str, List[str]]] = None, filter_owners: Optional[Union[ID, List[ID]]] = None, filter_effective_controllers: Optional[Union[ID, List[ID]]] = None, + filter_shipper: Optional[Union[ID, List[ID]]] = None, + filter_consignee: Optional[Union[ID, List[ID]]] = None, filter_vessel_flags: Optional[Union[ID, List[ID]]] = None, filter_vessel_ice_class: Optional[Union[ID, List[ID]]] = None, filter_vessel_propulsion: Optional[Union[ID, List[ID]]] = None, @@ -62,6 +64,8 @@ def search( exclude_owners: Optional[Union[ID, List[ID]]] = None, exclude_effective_controllers: Optional[Union[ID, List[ID]]] = None, exclude_charterers: Optional[Union[ID, List[ID]]] = None, + exclude_shipper: Optional[Union[ID, List[ID]]] = None, + exclude_consignee: Optional[Union[ID, List[ID]]] = None, exclude_vessel_flags: Optional[Union[ID, List[ID]]] = None, exclude_destinations: Optional[Union[ID, List[ID]]] = None, exclude_origins: Optional[Union[ID, List[ID]]] = None, @@ -74,122 +78,130 @@ def search( intra_movements: Optional[str] = None, ) -> ReferenceBreakdownResult: """ - Origin locations breakdown aggregation by geographic area + Origin locations breakdown aggregation by geographic area - # Arguments + # Arguments - breakdown_unit_average_basis: Per day metrics only - movement activity on which to base the average metric. Can be one of state properties of a cargo movement: `identified_for_loading_state`, `loading_state`, `transiting_state`, `storing_state`, `ship_to_ship`, `unloading_state`, `unloaded_state`, `oil_on_water_state`, `unknown_state`, or one of time properties of a cargo movement: `identified_for_loading_at`, `loading_start`, `loading_end`, `storing_start`, `storing_end`, `ship_to_ship_start`, `ship_to_ship_end`, `unloading_start`, `unloading_end`. + breakdown_unit_average_basis: Per day metrics only - movement activity on which to base the average metric. Can be one of state properties of a cargo movement: `identified_for_loading_state`, `loading_state`, `transiting_state`, `storing_state`, `ship_to_ship`, `unloading_state`, `unloaded_state`, `oil_on_water_state`, `unknown_state`, or one of time properties of a cargo movement: `identified_for_loading_at`, `loading_start`, `loading_end`, `storing_start`, `storing_end`, `ship_to_ship_start`, `ship_to_ship_end`, `unloading_start`, `unloading_end`. - breakdown_unit: Units to aggregate upon. Must be one of the following: `'b'`, `'t'`, `'cbm'`, `'bpd'`, `'tpd'`, `'mpd'`. + breakdown_unit: Units to aggregate upon. Must be one of the following: `'b'`, `'t'`, `'cbm'`, `'bpd'`, `'tpd'`, `'mpd'`. - breakdown_size: Number of top geographies to return. Default is 5. + breakdown_size: Number of top geographies to return. Default is 5. - disable_geographic_exclusion_rules: A boolean which specifies whether certain movements should be excluded, based on a combination of their origin and destination. + disable_geographic_exclusion_rules: A boolean which specifies whether certain movements should be excluded, based on a combination of their origin and destination. - intra_movements: This enum controls a popular industry term intra-movements and determines the filter behaviour for cargo leaving then entering the same geographic area. - One of `all`, `exclude_intra_country` or `exclude_intra_geography` + intra_movements: This enum controls a popular industry term intra-movements and determines the filter behaviour for cargo leaving then entering the same geographic area. + One of `all`, `exclude_intra_country` or `exclude_intra_geography` - filter_activity: Cargo movement activity on which to base the time filter. The endpoint only includes cargo - movements matching that match this filter in the aggregations. Must be one of ['loading_state', - 'loading_start', 'loading_end', 'identified_for_loading_state', 'unloading_state', 'unloading_start', - 'unloading_end', 'storing_state', 'storing_start', 'storing_end', 'transiting_state']. + filter_activity: Cargo movement activity on which to base the time filter. The endpoint only includes cargo + movements matching that match this filter in the aggregations. Must be one of ['loading_state', + 'loading_start', 'loading_end', 'identified_for_loading_state', 'unloading_state', 'unloading_start', + 'unloading_end', 'storing_state', 'storing_start', 'storing_end', 'transiting_state']. - filter_time_min: The UTC start date of the time filter. + filter_time_min: The UTC start date of the time filter. - filter_time_max: The UTC end date of the time filter. + filter_time_max: The UTC end date of the time filter. - filter_effective_controllers: An effective controller ID, or list of effective controller IDs to filter on. + filter_effective_controllers: An effective controller ID, or list of effective controller IDs to filter on. - filter_vessel_flags: A vessel flag ID, or list of vessel flag IDs to filter on. + filter_vessel_flags: A vessel flag ID, or list of vessel flag IDs to filter on. - filter_vessel_ice_class: An ice class ID, or list of ice class IDs to filter on. + filter_vessel_ice_class: An ice class ID, or list of ice class IDs to filter on. - filter_vessel_propulsion: An propulsion means ID, or list of propulsion means IDs to filter on. + filter_vessel_propulsion: An propulsion means ID, or list of propulsion means IDs to filter on. - filter_charterers: An commercial entity ID, or list of commercial entity IDs to filter on. + filter_charterers: An commercial entity ID, or list of commercial entity IDs to filter on. - filter_origins: A geography ID, or list of geography IDs to filter on. + filter_shipper: A shipper ID, or list of shipper IDs to filter on. - filter_destinations: A geography ID, or list of geography IDs to filter on. + filter_consignee: A consignee ID, or list of consignee IDs to filter on. - filter_storage_locations: A geography ID, or list of geography IDs to filter on. + filter_origins: A geography ID, or list of geography IDs to filter on. - filter_waypoints: A geography ID, or list of geography IDs to filter on. + filter_destinations: A geography ID, or list of geography IDs to filter on. - filter_ship_to_ship_locations: A geography ID, or list of geography IDs to filter on. + filter_storage_locations: A geography ID, or list of geography IDs to filter on. - filter_products: A product ID, or list of product IDs to filter on. + filter_waypoints: A geography ID, or list of geography IDs to filter on. - filter_vessels: A vessel ID, or list of vessel IDs to filter on. + filter_ship_to_ship_locations: A geography ID, or list of geography IDs to filter on. - filter_vessel_classes: A vessel class, or list of vessel classes to filter on. + filter_products: A product ID, or list of product IDs to filter on. - filter_vessel_age_min: A number between 1 and 100 (representing years). + filter_vessels: A vessel ID, or list of vessel IDs to filter on. - filter_vessel_age_max: A number between 1 and 100 (representing years). + filter_vessel_classes: A vessel class, or list of vessel classes to filter on. - filter_vessel_scrubbers: Either inactive 'disabled', or included 'inc' or excluded 'exc'. + filter_vessel_age_min: A number between 1 and 100 (representing years). - filter_vessel_tags: A time bound vessel tag, or list of time bound vessel tags to filter on. + filter_vessel_age_max: A number between 1 and 100 (representing years). - exclude_products: A product ID, or list of product IDs to exclude. + filter_vessel_scrubbers: Either inactive 'disabled', or included 'inc' or excluded 'exc'. - exclude_vessel_flags: A vessel flag ID, or list of vessel flag IDs to exclude. + filter_vessel_tags: A time bound vessel tag, or list of time bound vessel tags to filter on. - exclude_vessel_ice_class: An ice class ID, or list of ice class IDs to exclude. + exclude_products: A product ID, or list of product IDs to exclude. - exclude_vessel_propulsion: An propulsion means ID, or list of propulsion means IDs to exclude. + exclude_vessel_flags: A vessel flag ID, or list of vessel flag IDs to exclude. - exclude_vessels: A vessel ID, or list of vessel IDs to exclude. + exclude_vessel_ice_class: An ice class ID, or list of ice class IDs to exclude. - exclude_vessel_classes: A vessel class, or list of vessel classes to exclude. + exclude_vessel_propulsion: An propulsion means ID, or list of propulsion means IDs to exclude. - exclude_effective_controllers: An effective controller ID, or list of effective controller IDs to exclude. + exclude_vessels: A vessel ID, or list of vessel IDs to exclude. - exclude_vessel_location: A location ID, or list of location IDs to exclude. + exclude_vessel_classes: A vessel class, or list of vessel classes to exclude. - exclude_destinations: A location ID, or list of location IDs to exclude. + exclude_effective_controllers: An effective controller ID, or list of effective controller IDs to exclude. - exclude_origins: A location ID, or list of location IDs to exclude. + exclude_shipper: A shipper ID, or list of shipper IDs to exclude. - exclude_storage_locations: A location ID, or list of location IDs to exclude. + exclude_consignee: A consignee ID, or list of consignee IDs to exclude. - exclude_waypoints: A location ID, or list of location IDs to exclude. + exclude_vessel_location: A location ID, or list of location IDs to exclude. - exclude_ship_to_ship_locations: A location ID, or list of location IDs to exclude. + exclude_destinations: A location ID, or list of location IDs to exclude. - exclude_vessel_tags: A time bound vessel tag, or list of time bound vessel tags to exclude. + exclude_origins: A location ID, or list of location IDs to exclude. - # Returns - `ReferenceBreakdownResult` + exclude_storage_locations: A location ID, or list of location IDs to exclude. + exclude_waypoints: A location ID, or list of location IDs to exclude. - # Example + exclude_ship_to_ship_locations: A location ID, or list of location IDs to exclude. + + exclude_vessel_tags: A time bound vessel tag, or list of time bound vessel tags to exclude. + + # Returns + `ReferenceBreakdownResult` + + + # Example _Breakdown by product of the cargoes in tonnes._ - ```python - >>> from vortexasdk import ParentProductBreakdown - >>> start = datetime(2019, 11, 10) - >>> end = datetime(2019, 11, 15) - >>> df = ParentProductBreakdown().search( - ... filter_activity="loading_end", - ... breakdown_unit="t", - ... breakdown_size=5, - ... filter_time_min=start, - ... filter_time_max=end - ... ).to_df() - - ``` - - Gives the following: - - | | key | label | value | count | - |---:|:----------------------------------------------------------------|-----------------------------------------:|---------:|----------:| - | 0 | c3daea3cc9c5b3bd91c90882d42c2a418c4cf17b90ff12da3ac78444282a238a| Juaymah Crude Oil Terminal | 3009799 | 24 | - | 1 | 3a39cf841ece0c7cb879f72af01cb634191142e0de8010d5ef877fd66c2e8605| Houston Enterprise Terminal | 776599 | 17 | - | 2 | 345b7661310bc82a04e0a4edffd02c286c410c023b53edfb90ed3386640c0476| Arzew GL1Z/GL2Z LNG Terminal | 381359 | 24 | - | 3 | 9dfa3be1b42d1f5e80361b6f442b5217b486876ad0c25e382055887c9e231ad2| SabTank (PCQ-1) Al Jubail | 238723 | 21 | - | 4 | 4813dd7209e85b128cc2fbc7c08fef08d26259550210f28a5c7ff3ccd7b2ba61| Mailiao Industrial Park-Formosa Plastics | 118285 | 18 | + ```python + >>> from vortexasdk import ParentProductBreakdown + >>> start = datetime(2019, 11, 10) + >>> end = datetime(2019, 11, 15) + >>> df = ParentProductBreakdown().search( + ... filter_activity="loading_end", + ... breakdown_unit="t", + ... breakdown_size=5, + ... filter_time_min=start, + ... filter_time_max=end + ... ).to_df() + + ``` + + Gives the following: + + | | key | label | value | count | + |---:|:----------------------------------------------------------------|-----------------------------------------:|---------:|----------:| + | 0 | c3daea3cc9c5b3bd91c90882d42c2a418c4cf17b90ff12da3ac78444282a238a| Juaymah Crude Oil Terminal | 3009799 | 24 | + | 1 | 3a39cf841ece0c7cb879f72af01cb634191142e0de8010d5ef877fd66c2e8605| Houston Enterprise Terminal | 776599 | 17 | + | 2 | 345b7661310bc82a04e0a4edffd02c286c410c023b53edfb90ed3386640c0476| Arzew GL1Z/GL2Z LNG Terminal | 381359 | 24 | + | 3 | 9dfa3be1b42d1f5e80361b6f442b5217b486876ad0c25e382055887c9e231ad2| SabTank (PCQ-1) Al Jubail | 238723 | 21 | + | 4 | 4813dd7209e85b128cc2fbc7c08fef08d26259550210f28a5c7ff3ccd7b2ba61| Mailiao Industrial Park-Formosa Plastics | 118285 | 18 | """ @@ -208,6 +220,8 @@ def search( "filter_effective_controllers": convert_to_list( exclude_effective_controllers ), + "filter_shipper": convert_to_list(exclude_shipper), + "filter_consignee": convert_to_list(exclude_consignee), "filter_origins": convert_to_list(exclude_origins), "filter_flags": convert_to_list(exclude_vessel_flags), "filter_vessel_ice_class": convert_to_list( @@ -248,6 +262,8 @@ def search( "filter_effective_controllers": convert_to_list( filter_effective_controllers ), + "filter_shipper": convert_to_list(filter_shipper), + "filter_consignee": convert_to_list(filter_consignee), "filter_destinations": convert_to_list(filter_destinations), "filter_origins": convert_to_list(filter_origins), "filter_waypoints": convert_to_list(filter_waypoints), diff --git a/vortexasdk/endpoints/product_breakdown.py b/vortexasdk/endpoints/product_breakdown.py index 9e433b5e..d20a7aff 100644 --- a/vortexasdk/endpoints/product_breakdown.py +++ b/vortexasdk/endpoints/product_breakdown.py @@ -45,6 +45,8 @@ def search( filter_vessel_classes: Optional[Union[str, List[str]]] = None, filter_owners: Optional[Union[ID, List[ID]]] = None, filter_effective_controllers: Optional[Union[ID, List[ID]]] = None, + filter_shipper: Optional[Union[ID, List[ID]]] = None, + filter_consignee: Optional[Union[ID, List[ID]]] = None, filter_vessel_flags: Optional[Union[ID, List[ID]]] = None, filter_vessel_ice_class: Optional[Union[ID, List[ID]]] = None, filter_vessel_propulsion: Optional[Union[ID, List[ID]]] = None, @@ -63,6 +65,8 @@ def search( exclude_owners: Optional[Union[ID, List[ID]]] = None, exclude_effective_controllers: Optional[Union[ID, List[ID]]] = None, exclude_charterers: Optional[Union[ID, List[ID]]] = None, + exclude_shipper: Optional[Union[ID, List[ID]]] = None, + exclude_consignee: Optional[Union[ID, List[ID]]] = None, exclude_vessel_flags: Optional[Union[ID, List[ID]]] = None, exclude_destinations: Optional[Union[ID, List[ID]]] = None, exclude_origins: Optional[Union[ID, List[ID]]] = None, @@ -75,126 +79,134 @@ def search( intra_movements: Optional[str] = None, ) -> ReferenceBreakdownResult: """ - Origin locations breakdown aggregation by geographic area + Origin locations breakdown aggregation by geographic area - # Arguments + # Arguments - breakdown_unit_average_basis: Per day metrics only - movement activity on which to base the average metric. Can be one of state properties of a cargo movement: `identified_for_loading_state`, `loading_state`, `transiting_state`, `storing_state`, `ship_to_ship`, `unloading_state`, `unloaded_state`, `oil_on_water_state`, `unknown_state`, or one of time properties of a cargo movement: `identified_for_loading_at`, `loading_start`, `loading_end`, `storing_start`, `storing_end`, `ship_to_ship_start`, `ship_to_ship_end`, `unloading_start`, `unloading_end`. + breakdown_unit_average_basis: Per day metrics only - movement activity on which to base the average metric. Can be one of state properties of a cargo movement: `identified_for_loading_state`, `loading_state`, `transiting_state`, `storing_state`, `ship_to_ship`, `unloading_state`, `unloaded_state`, `oil_on_water_state`, `unknown_state`, or one of time properties of a cargo movement: `identified_for_loading_at`, `loading_start`, `loading_end`, `storing_start`, `storing_end`, `ship_to_ship_start`, `ship_to_ship_end`, `unloading_start`, `unloading_end`. - breakdown_unit: Units to aggregate upon. Must be one of the following: `'b'`, `'t'`, `'cbm'`, `'bpd'`, `'tpd'`, `'mpd'`. + breakdown_unit: Units to aggregate upon. Must be one of the following: `'b'`, `'t'`, `'cbm'`, `'bpd'`, `'tpd'`, `'mpd'`. - breakdown_product: This represents the different levels of the product hierarchy. With 'group' being the top level, and grade being the lowest - or most accurate. + breakdown_product: This represents the different levels of the product hierarchy. With 'group' being the top level, and grade being the lowest - or most accurate. 'group', 'group_product', 'category', 'grade' - breakdown_size: Number of top geographies to return. Default is 5. + breakdown_size: Number of top geographies to return. Default is 5. - disable_geographic_exclusion_rules: A boolean which specifies whether certain movements should be excluded, based on a combination of their origin and destination. + disable_geographic_exclusion_rules: A boolean which specifies whether certain movements should be excluded, based on a combination of their origin and destination. - intra_movements: This enum controls a popular industry term intra-movements and determines the filter behaviour for cargo leaving then entering the same geographic area. - One of `all`, `exclude_intra_country` or `exclude_intra_geography` + intra_movements: This enum controls a popular industry term intra-movements and determines the filter behaviour for cargo leaving then entering the same geographic area. + One of `all`, `exclude_intra_country` or `exclude_intra_geography` - filter_activity: Cargo movement activity on which to base the time filter. The endpoint only includes cargo - movements matching that match this filter in the aggregations. Must be one of ['loading_state', - 'loading_start', 'loading_end', 'identified_for_loading_state', 'unloading_state', 'unloading_start', - 'unloading_end', 'storing_state', 'storing_start', 'storing_end', 'transiting_state']. + filter_activity: Cargo movement activity on which to base the time filter. The endpoint only includes cargo + movements matching that match this filter in the aggregations. Must be one of ['loading_state', + 'loading_start', 'loading_end', 'identified_for_loading_state', 'unloading_state', 'unloading_start', + 'unloading_end', 'storing_state', 'storing_start', 'storing_end', 'transiting_state']. - filter_time_min: The UTC start date of the time filter. + filter_time_min: The UTC start date of the time filter. - filter_time_max: The UTC end date of the time filter. + filter_time_max: The UTC end date of the time filter. - filter_effective_controllers: An effective controller ID, or list of effective controller IDs to filter on. + filter_effective_controllers: An effective controller ID, or list of effective controller IDs to filter on. - filter_vessel_flags: A vessel flag ID, or list of vessel flag IDs to filter on. + filter_vessel_flags: A vessel flag ID, or list of vessel flag IDs to filter on. - filter_vessel_ice_class: An ice class ID, or list of ice class IDs to filter on. + filter_vessel_ice_class: An ice class ID, or list of ice class IDs to filter on. - filter_vessel_propulsion: An propulsion means ID, or list of propulsion means IDs to filter on. + filter_vessel_propulsion: An propulsion means ID, or list of propulsion means IDs to filter on. - filter_charterers: An commercial entity ID, or list of commercial entity IDs to filter on. + filter_charterers: An commercial entity ID, or list of commercial entity IDs to filter on. - filter_origins: A geography ID, or list of geography IDs to filter on. + filter_shipper: A shipper ID, or list of shipper IDs to filter on. - filter_destinations: A geography ID, or list of geography IDs to filter on. + filter_consignee: A consignee ID, or list of consignee IDs to filter on. - filter_storage_locations: A geography ID, or list of geography IDs to filter on. + filter_origins: A geography ID, or list of geography IDs to filter on. - filter_waypoints: A geography ID, or list of geography IDs to filter on. + filter_destinations: A geography ID, or list of geography IDs to filter on. - filter_ship_to_ship_locations: A geography ID, or list of geography IDs to filter on. + filter_storage_locations: A geography ID, or list of geography IDs to filter on. - filter_products: A product ID, or list of product IDs to filter on. + filter_waypoints: A geography ID, or list of geography IDs to filter on. - filter_vessels: A vessel ID, or list of vessel IDs to filter on. + filter_ship_to_ship_locations: A geography ID, or list of geography IDs to filter on. - filter_vessel_classes: A vessel class, or list of vessel classes to filter on. + filter_products: A product ID, or list of product IDs to filter on. - filter_vessel_age_min: A number between 1 and 100 (representing years). + filter_vessels: A vessel ID, or list of vessel IDs to filter on. - filter_vessel_age_max: A number between 1 and 100 (representing years). + filter_vessel_classes: A vessel class, or list of vessel classes to filter on. - filter_vessel_scrubbers: Either inactive 'disabled', or included 'inc' or excluded 'exc'. + filter_vessel_age_min: A number between 1 and 100 (representing years). - filter_vessel_tags: A time bound vessel tag, or list of time bound vessel tags to filter on. + filter_vessel_age_max: A number between 1 and 100 (representing years). - exclude_products: A product ID, or list of product IDs to exclude. + filter_vessel_scrubbers: Either inactive 'disabled', or included 'inc' or excluded 'exc'. - exclude_vessel_flags: A vessel flag ID, or list of vessel flag IDs to exclude. + filter_vessel_tags: A time bound vessel tag, or list of time bound vessel tags to filter on. - exclude_vessel_ice_class: An ice class ID, or list of ice class IDs to exclude. + exclude_products: A product ID, or list of product IDs to exclude. - exclude_vessel_propulsion: An propulsion means ID, or list of propulsion means IDs to exclude. + exclude_vessel_flags: A vessel flag ID, or list of vessel flag IDs to exclude. - exclude_vessels: A vessel ID, or list of vessel IDs to exclude. + exclude_vessel_ice_class: An ice class ID, or list of ice class IDs to exclude. - exclude_vessel_classes: A vessel class, or list of vessel classes to exclude. + exclude_vessel_propulsion: An propulsion means ID, or list of propulsion means IDs to exclude. - exclude_effective_controllers: An effective controller ID, or list of effective controller IDs to exclude. + exclude_vessels: A vessel ID, or list of vessel IDs to exclude. - exclude_vessel_location: A location ID, or list of location IDs to exclude. + exclude_vessel_classes: A vessel class, or list of vessel classes to exclude. - exclude_destinations: A location ID, or list of location IDs to exclude. + exclude_effective_controllers: An effective controller ID, or list of effective controller IDs to exclude. - exclude_origins: A location ID, or list of location IDs to exclude. + exclude_shipper: A shipper ID, or list of shipper IDs to exclude. - exclude_storage_locations: A location ID, or list of location IDs to exclude. + exclude_consignee: A consignee ID, or list of consignee IDs to exclude. - exclude_waypoints: A location ID, or list of location IDs to exclude. + exclude_vessel_location: A location ID, or list of location IDs to exclude. - exclude_ship_to_ship_locations: A location ID, or list of location IDs to exclude. + exclude_destinations: A location ID, or list of location IDs to exclude. - exclude_vessel_tags: A time bound vessel tag, or list of time bound vessel tags to exclude. + exclude_origins: A location ID, or list of location IDs to exclude. - # Returns - `ReferenceBreakdownResult` + exclude_storage_locations: A location ID, or list of location IDs to exclude. + exclude_waypoints: A location ID, or list of location IDs to exclude. - # Example + exclude_ship_to_ship_locations: A location ID, or list of location IDs to exclude. + + exclude_vessel_tags: A time bound vessel tag, or list of time bound vessel tags to exclude. + + # Returns + `ReferenceBreakdownResult` + + + # Example _Breakdown by product of the cargoes in tonnes._ - ```python - >>> from vortexasdk import ProductBreakdown - >>> start = datetime(2019, 11, 10) - >>> end = datetime(2019, 11, 15) - >>> df = ProductBreakdown().search( - ... filter_activity="loading_end", - ... breakdown_product="group", - ... breakdown_unit="t", - ... breakdown_size=5, - ... filter_time_min=start, - ... filter_time_max=end - ... ).to_df() - - ``` - - Gives the following: - - | | key | label | value | count | - |---:|:----------------------------------------------------------------|-----------------------------------------:|---------:|----------:| - | 0 | c3daea3cc9c5b3bd91c90882d42c2a418c4cf17b90ff12da3ac78444282a238a| Juaymah Crude Oil Terminal | 3009799 | 24 | - | 1 | 3a39cf841ece0c7cb879f72af01cb634191142e0de8010d5ef877fd66c2e8605| Houston Enterprise Terminal | 776599 | 17 | - | 2 | 345b7661310bc82a04e0a4edffd02c286c410c023b53edfb90ed3386640c0476| Arzew GL1Z/GL2Z LNG Terminal | 381359 | 24 | - | 3 | 9dfa3be1b42d1f5e80361b6f442b5217b486876ad0c25e382055887c9e231ad2| SabTank (PCQ-1) Al Jubail | 238723 | 21 | - | 4 | 4813dd7209e85b128cc2fbc7c08fef08d26259550210f28a5c7ff3ccd7b2ba61| Mailiao Industrial Park-Formosa Plastics | 118285 | 18 | + ```python + >>> from vortexasdk import ProductBreakdown + >>> start = datetime(2019, 11, 10) + >>> end = datetime(2019, 11, 15) + >>> df = ProductBreakdown().search( + ... filter_activity="loading_end", + ... breakdown_product="group", + ... breakdown_unit="t", + ... breakdown_size=5, + ... filter_time_min=start, + ... filter_time_max=end + ... ).to_df() + + ``` + + Gives the following: + + | | key | label | value | count | + |---:|:----------------------------------------------------------------|-----------------------------------------:|---------:|----------:| + | 0 | c3daea3cc9c5b3bd91c90882d42c2a418c4cf17b90ff12da3ac78444282a238a| Juaymah Crude Oil Terminal | 3009799 | 24 | + | 1 | 3a39cf841ece0c7cb879f72af01cb634191142e0de8010d5ef877fd66c2e8605| Houston Enterprise Terminal | 776599 | 17 | + | 2 | 345b7661310bc82a04e0a4edffd02c286c410c023b53edfb90ed3386640c0476| Arzew GL1Z/GL2Z LNG Terminal | 381359 | 24 | + | 3 | 9dfa3be1b42d1f5e80361b6f442b5217b486876ad0c25e382055887c9e231ad2| SabTank (PCQ-1) Al Jubail | 238723 | 21 | + | 4 | 4813dd7209e85b128cc2fbc7c08fef08d26259550210f28a5c7ff3ccd7b2ba61| Mailiao Industrial Park-Formosa Plastics | 118285 | 18 | """ @@ -213,6 +225,8 @@ def search( "filter_effective_controllers": convert_to_list( exclude_effective_controllers ), + "filter_shipper": convert_to_list(exclude_shipper), + "filter_consignee": convert_to_list(exclude_consignee), "filter_origins": convert_to_list(exclude_origins), "filter_flags": convert_to_list(exclude_vessel_flags), "filter_vessel_ice_class": convert_to_list( @@ -254,6 +268,8 @@ def search( "filter_effective_controllers": convert_to_list( filter_effective_controllers ), + "filter_shipper": convert_to_list(filter_shipper), + "filter_consignee": convert_to_list(filter_consignee), "filter_destinations": convert_to_list(filter_destinations), "filter_origins": convert_to_list(filter_origins), "filter_waypoints": convert_to_list(filter_waypoints), diff --git a/vortexasdk/endpoints/vessel_availability_breakdown.py b/vortexasdk/endpoints/vessel_availability_breakdown.py index 006ada47..7f62afc5 100644 --- a/vortexasdk/endpoints/vessel_availability_breakdown.py +++ b/vortexasdk/endpoints/vessel_availability_breakdown.py @@ -63,12 +63,10 @@ def search( exclude_owners: Optional[Union[ID, List[ID]]] = None, exclude_effective_controllers: Optional[Union[ID, List[ID]]] = None, exclude_destination: Optional[Union[ID, List[ID]]] = None, - exclude_filter_vessel_flags: Optional[Union[ID, List[ID]]] = None, - exclude_filter_vessel_ice_class: Optional[Union[ID, List[ID]]] = None, - exclude_filter_vessel_tags: Optional[Union[List[Tag], Tag]] = None, - exclude_filter_vessel_risk_level: Optional[ - Union[str, List[str]] - ] = None, + exclude_vessel_flags: Optional[Union[ID, List[ID]]] = None, + exclude_vessel_ice_class: Optional[Union[ID, List[ID]]] = None, + exclude_vessel_tags: Optional[Union[List[Tag], Tag]] = None, + exclude_vessel_risk_level: Optional[Union[str, List[str]]] = None, ) -> TimeSeriesResult: """ Number and DWT of all vessels that can be available to load a given cargo at a given port, @@ -137,13 +135,13 @@ def search( exclude_destination: A location ID, or list of location IDs to filter on. - exclude_filter_vessel_flags: A flag ID, or list of flag IDs to exclude. + exclude_vessel_flags: A flag ID, or list of flag IDs to exclude. - exclude_filter_vessel_ice_class: An ice class ID, or list of ice class IDs to exclude. + exclude_vessel_ice_class: An ice class ID, or list of ice class IDs to exclude. - exclude_filter_vessel_tags: A tag ID, or list of tag IDs to exclude. + exclude_vessel_tags: A tag ID, or list of tag IDs to exclude. - exclude_filter_vessel_risk_level: A risk level ID, or list of risk level IDs to exclude. + exclude_vessel_risk_level: A risk level ID, or list of risk level IDs to exclude. # Returns `TimeSeriesResult` @@ -186,15 +184,13 @@ def search( ), "filter_vessel_status": convert_to_list(exclude_vessel_status), "filter_vessel_location": convert_to_list(exclude_vessel_location), - "filter_vessel_flags": convert_to_list( - exclude_filter_vessel_flags - ), + "filter_vessel_flags": convert_to_list(exclude_vessel_flags), "filter_vessel_ice_class": convert_to_list( - exclude_filter_vessel_ice_class + exclude_vessel_ice_class ), - "filter_vessel_tags": convert_to_list(exclude_filter_vessel_tags), + "filter_vessel_tags": convert_to_list(exclude_vessel_tags), "filter_vessel_risk_level": convert_to_list( - exclude_filter_vessel_risk_level + exclude_vessel_risk_level ), } diff --git a/vortexasdk/endpoints/vessel_availability_search.py b/vortexasdk/endpoints/vessel_availability_search.py index eca36397..d5a85e35 100644 --- a/vortexasdk/endpoints/vessel_availability_search.py +++ b/vortexasdk/endpoints/vessel_availability_search.py @@ -64,12 +64,10 @@ def search( exclude_owners: Optional[Union[ID, List[ID]]] = None, exclude_effective_controllers: Optional[Union[ID, List[ID]]] = None, exclude_destination: Optional[Union[ID, List[ID]]] = None, - exclude_filter_vessel_flags: Optional[Union[ID, List[ID]]] = None, - exclude_filter_vessel_ice_class: Optional[Union[ID, List[ID]]] = None, - exclude_filter_vessel_tags: Optional[Union[List[Tag], Tag]] = None, - exclude_filter_vessel_risk_level: Optional[ - Union[str, List[str]] - ] = None, + exclude_vessel_flags: Optional[Union[ID, List[ID]]] = None, + exclude_vessel_ice_class: Optional[Union[ID, List[ID]]] = None, + exclude_vessel_tags: Optional[Union[List[Tag], Tag]] = None, + exclude_vessel_risk_level: Optional[Union[str, List[str]]] = None, order: Optional[str] = None, order_direction: Optional[str] = None, size: Optional[int] = None, @@ -150,13 +148,13 @@ def search( exclude_destination: A location ID, or list of location IDs to filter on. - exclude_filter_vessel_flags: A flag ID, or list of flag IDs to exclude. + exclude_vessel_flags: A flag ID, or list of flag IDs to exclude. - exclude_filter_vessel_ice_class: An ice class ID, or list of ice class IDs to exclude. + exclude_vessel_ice_class: An ice class ID, or list of ice class IDs to exclude. - exclude_filter_vessel_tags: A tag ID, or list of tag IDs to exclude. + exclude_vessel_tags: A tag ID, or list of tag IDs to exclude. - exclude_filter_vessel_risk_level: A risk level ID, or list of risk level IDs to exclude. + exclude_vessel_risk_level: A risk level ID, or list of risk level IDs to exclude. # Returns `VesselAvailabilityResult` @@ -193,15 +191,13 @@ def search( ), "filter_vessel_status": convert_to_list(exclude_vessel_status), "filter_vessel_location": convert_to_list(exclude_vessel_location), - "filter_vessel_flags": convert_to_list( - exclude_filter_vessel_flags - ), + "filter_vessel_flags": convert_to_list(exclude_vessel_flags), "filter_vessel_ice_class": convert_to_list( - exclude_filter_vessel_ice_class + exclude_vessel_ice_class ), - "filter_vessel_tags": convert_to_list(exclude_filter_vessel_tags), + "filter_vessel_tags": convert_to_list(exclude_vessel_tags), "filter_vessel_risk_level": convert_to_list( - exclude_filter_vessel_risk_level + exclude_vessel_risk_level ), } diff --git a/vortexasdk/endpoints/vessel_availability_timeseries.py b/vortexasdk/endpoints/vessel_availability_timeseries.py index 2d3fe4c1..877eb970 100644 --- a/vortexasdk/endpoints/vessel_availability_timeseries.py +++ b/vortexasdk/endpoints/vessel_availability_timeseries.py @@ -67,12 +67,10 @@ def search( exclude_owners: Optional[Union[ID, List[ID]]] = None, exclude_effective_controllers: Optional[Union[ID, List[ID]]] = None, exclude_destination: Optional[Union[ID, List[ID]]] = None, - exclude_filter_vessel_flags: Optional[Union[ID, List[ID]]] = None, - exclude_filter_vessel_ice_class: Optional[Union[ID, List[ID]]] = None, - exclude_filter_vessel_tags: Optional[Union[List[Tag], Tag]] = None, - exclude_filter_vessel_risk_level: Optional[ - Union[str, List[str]] - ] = None, + exclude_vessel_flags: Optional[Union[ID, List[ID]]] = None, + exclude_vessel_ice_class: Optional[Union[ID, List[ID]]] = None, + exclude_vessel_tags: Optional[Union[List[Tag], Tag]] = None, + exclude_vessel_risk_level: Optional[Union[str, List[str]]] = None, ) -> TimeSeriesResult: """ Time series of the number of vessels that can be available to load a given cargo at a given port for @@ -145,13 +143,13 @@ def search( exclude_destination: A location ID, or list of location IDs to filter on. - exclude_filter_vessel_flags: A flag ID, or list of flag IDs to exclude. + exclude_vessel_flags: A flag ID, or list of flag IDs to exclude. - exclude_filter_vessel_ice_class: An ice class ID, or list of ice class IDs to exclude. + exclude_vessel_ice_class: An ice class ID, or list of ice class IDs to exclude. - exclude_filter_vessel_tags: A tag ID, or list of tag IDs to exclude. + exclude_vessel_tags: A tag ID, or list of tag IDs to exclude. - exclude_filter_vessel_risk_level: A risk level ID, or list of risk level IDs to exclude. + exclude_vessel_risk_level: A risk level ID, or list of risk level IDs to exclude. # Returns `TimeSeriesResult` @@ -198,15 +196,13 @@ def search( ), "filter_vessel_status": convert_to_list(exclude_vessel_status), "filter_vessel_location": convert_to_list(exclude_vessel_location), - "filter_vessel_flags": convert_to_list( - exclude_filter_vessel_flags - ), + "filter_vessel_flags": convert_to_list(exclude_vessel_flags), "filter_vessel_ice_class": convert_to_list( - exclude_filter_vessel_ice_class + exclude_vessel_ice_class ), - "filter_vessel_tags": convert_to_list(exclude_filter_vessel_tags), + "filter_vessel_tags": convert_to_list(exclude_vessel_tags), "filter_vessel_risk_level": convert_to_list( - exclude_filter_vessel_risk_level + exclude_vessel_risk_level ), } diff --git a/vortexasdk/endpoints/vessel_class_breakdown.py b/vortexasdk/endpoints/vessel_class_breakdown.py index 72e9bd09..baa1095f 100644 --- a/vortexasdk/endpoints/vessel_class_breakdown.py +++ b/vortexasdk/endpoints/vessel_class_breakdown.py @@ -44,6 +44,8 @@ def search( filter_vessel_classes: Optional[Union[str, List[str]]] = None, filter_owners: Optional[Union[ID, List[ID]]] = None, filter_effective_controllers: Optional[Union[ID, List[ID]]] = None, + filter_shipper: Optional[Union[ID, List[ID]]] = None, + filter_consignee: Optional[Union[ID, List[ID]]] = None, filter_vessel_flags: Optional[Union[ID, List[ID]]] = None, filter_vessel_ice_class: Optional[Union[ID, List[ID]]] = None, filter_vessel_propulsion: Optional[Union[ID, List[ID]]] = None, @@ -62,6 +64,8 @@ def search( exclude_owners: Optional[Union[ID, List[ID]]] = None, exclude_effective_controllers: Optional[Union[ID, List[ID]]] = None, exclude_charterers: Optional[Union[ID, List[ID]]] = None, + exclude_shipper: Optional[Union[ID, List[ID]]] = None, + exclude_consignee: Optional[Union[ID, List[ID]]] = None, exclude_vessel_flags: Optional[Union[ID, List[ID]]] = None, exclude_destinations: Optional[Union[ID, List[ID]]] = None, exclude_origins: Optional[Union[ID, List[ID]]] = None, @@ -74,125 +78,133 @@ def search( intra_movements: Optional[str] = None, ) -> ReferenceBreakdownResult: """ - Vessel class locations breakdown aggregation + Vessel class locations breakdown aggregation - # Arguments + # Arguments - breakdown_unit_average_basis: Per day metrics only - movement activity on which to base the average metric. Can be one of state properties of a cargo movement: `identified_for_loading_state`, `loading_state`, `transiting_state`, `storing_state`, `ship_to_ship`, `unloading_state`, `unloaded_state`, `oil_on_water_state`, `unknown_state`, or one of time properties of a cargo movement: `identified_for_loading_at`, `loading_start`, `loading_end`, `storing_start`, `storing_end`, `ship_to_ship_start`, `ship_to_ship_end`, `unloading_start`, `unloading_end`. + breakdown_unit_average_basis: Per day metrics only - movement activity on which to base the average metric. Can be one of state properties of a cargo movement: `identified_for_loading_state`, `loading_state`, `transiting_state`, `storing_state`, `ship_to_ship`, `unloading_state`, `unloaded_state`, `oil_on_water_state`, `unknown_state`, or one of time properties of a cargo movement: `identified_for_loading_at`, `loading_start`, `loading_end`, `storing_start`, `storing_end`, `ship_to_ship_start`, `ship_to_ship_end`, `unloading_start`, `unloading_end`. - breakdown_unit: Units to aggregate upon. Must be one of the following: `'b'`, `'t'`, `'cbm'`, `'bpd'`, `'tpd'`, `'mpd'`. + breakdown_unit: Units to aggregate upon. Must be one of the following: `'b'`, `'t'`, `'cbm'`, `'bpd'`, `'tpd'`, `'mpd'`. - breakdown_size: Number of top geographies to return. Default is 5. + breakdown_size: Number of top geographies to return. Default is 5. - disable_geographic_exclusion_rules: A boolean which specifies whether certain movements should be excluded, based on a combination of their origin and destination. + disable_geographic_exclusion_rules: A boolean which specifies whether certain movements should be excluded, based on a combination of their origin and destination. - intra_movements: This enum controls a popular industry term intra-movements and determines the filter behaviour for cargo leaving then entering the same geographic area. - One of `all`, `exclude_intra_country` or `exclude_intra_geography` + intra_movements: This enum controls a popular industry term intra-movements and determines the filter behaviour for cargo leaving then entering the same geographic area. + One of `all`, `exclude_intra_country` or `exclude_intra_geography` - filter_activity: Cargo movement activity on which to base the time filter. The endpoint only includes cargo - movements matching that match this filter in the aggregations. Must be one of ['loading_state', - 'loading_start', 'loading_end', 'identified_for_loading_state', 'unloading_state', 'unloading_start', - 'unloading_end', 'storing_state', 'storing_start', 'storing_end', 'transiting_state']. + filter_activity: Cargo movement activity on which to base the time filter. The endpoint only includes cargo + movements matching that match this filter in the aggregations. Must be one of ['loading_state', + 'loading_start', 'loading_end', 'identified_for_loading_state', 'unloading_state', 'unloading_start', + 'unloading_end', 'storing_state', 'storing_start', 'storing_end', 'transiting_state']. - filter_time_min: The UTC start date of the time filter. + filter_time_min: The UTC start date of the time filter. - filter_time_max: The UTC end date of the time filter. + filter_time_max: The UTC end date of the time filter. - filter_effective_controllers: An effective controller ID, or list of effective controller IDs to filter on. + filter_effective_controllers: An effective controller ID, or list of effective controller IDs to filter on. - filter_vessel_flags: A vessel flag ID, or list of vessel flag IDs to filter on. + filter_vessel_flags: A vessel flag ID, or list of vessel flag IDs to filter on. - filter_vessel_ice_class: An ice class ID, or list of ice class IDs to filter on. + filter_vessel_ice_class: An ice class ID, or list of ice class IDs to filter on. - filter_vessel_propulsion: An propulsion means ID, or list of propulsion means IDs to filter on. + filter_vessel_propulsion: An propulsion means ID, or list of propulsion means IDs to filter on. - filter_charterers: An commercial entity ID, or list of commercial entity IDs to filter on. + filter_charterers: An commercial entity ID, or list of commercial entity IDs to filter on. - filter_origins: A geography ID, or list of geography IDs to filter on. + filter_shipper: A shipper ID, or list of shipper IDs to filter on. - filter_destinations: A geography ID, or list of geography IDs to filter on. + filter_consignee: A consignee ID, or list of consignee IDs to filter on. - filter_storage_locations: A geography ID, or list of geography IDs to filter on. + filter_origins: A geography ID, or list of geography IDs to filter on. - filter_waypoints: A geography ID, or list of geography IDs to filter on. + filter_destinations: A geography ID, or list of geography IDs to filter on. - filter_ship_to_ship_locations: A geography ID, or list of geography IDs to filter on. + filter_storage_locations: A geography ID, or list of geography IDs to filter on. - filter_products: A product ID, or list of product IDs to filter on. + filter_waypoints: A geography ID, or list of geography IDs to filter on. - filter_vessels: A vessel ID, or list of vessel IDs to filter on. + filter_ship_to_ship_locations: A geography ID, or list of geography IDs to filter on. - filter_vessel_classes: A vessel class, or list of vessel classes to filter on. + filter_products: A product ID, or list of product IDs to filter on. - filter_vessel_age_min: A number between 1 and 100 (representing years). + filter_vessels: A vessel ID, or list of vessel IDs to filter on. - filter_vessel_age_max: A number between 1 and 100 (representing years). + filter_vessel_classes: A vessel class, or list of vessel classes to filter on. - filter_vessel_scrubbers: Either inactive 'disabled', or included 'inc' or excluded 'exc'. + filter_vessel_age_min: A number between 1 and 100 (representing years). - filter_vessel_tags: A time bound vessel tag, or list of time bound vessel tags to filter on. + filter_vessel_age_max: A number between 1 and 100 (representing years). - exclude_products: A product ID, or list of product IDs to exclude. + filter_vessel_scrubbers: Either inactive 'disabled', or included 'inc' or excluded 'exc'. - exclude_vessel_flags: A vessel flag ID, or list of vessel flag IDs to exclude. + filter_vessel_tags: A time bound vessel tag, or list of time bound vessel tags to filter on. - exclude_vessel_ice_class: An ice class ID, or list of ice class IDs to exclude. + exclude_products: A product ID, or list of product IDs to exclude. - exclude_vessel_propulsion: An propulsion means ID, or list of propulsion means IDs to exclude. + exclude_vessel_flags: A vessel flag ID, or list of vessel flag IDs to exclude. - exclude_vessels: A vessel ID, or list of vessel IDs to exclude. + exclude_vessel_ice_class: An ice class ID, or list of ice class IDs to exclude. - exclude_vessel_classes: A vessel class, or list of vessel classes to exclude. + exclude_vessel_propulsion: An propulsion means ID, or list of propulsion means IDs to exclude. - exclude_effective_controllers: An effective controller ID, or list of effective controller IDs to exclude. + exclude_vessels: A vessel ID, or list of vessel IDs to exclude. - exclude_vessel_location: A location ID, or list of location IDs to exclude. + exclude_vessel_classes: A vessel class, or list of vessel classes to exclude. - exclude_destinations: A location ID, or list of location IDs to exclude. + exclude_effective_controllers: An effective controller ID, or list of effective controller IDs to exclude. - exclude_origins: A location ID, or list of location IDs to exclude. + exclude_shipper: A shipper ID, or list of shipper IDs to exclude. - exclude_storage_locations: A location ID, or list of location IDs to exclude. + exclude_consignee: A consignee ID, or list of consignee IDs to exclude. - exclude_waypoints: A location ID, or list of location IDs to exclude. + exclude_vessel_location: A location ID, or list of location IDs to exclude. - exclude_ship_to_ship_locations: A location ID, or list of location IDs to exclude. + exclude_destinations: A location ID, or list of location IDs to exclude. - exclude_vessel_tags: A time bound vessel tag, or list of time bound vessel tags to exclude. + exclude_origins: A location ID, or list of location IDs to exclude. - # Returns - `ReferenceBreakdownResult` + exclude_storage_locations: A location ID, or list of location IDs to exclude. + exclude_waypoints: A location ID, or list of location IDs to exclude. - # Example + exclude_ship_to_ship_locations: A location ID, or list of location IDs to exclude. + + exclude_vessel_tags: A time bound vessel tag, or list of time bound vessel tags to exclude. + + # Returns + `ReferenceBreakdownResult` + + + # Example _Breakdown by vessel class of cargoes in tonnes._ - ```python - >>> from vortexasdk import VesselClassBreakdown - >>> start = datetime(2019, 11, 10) - >>> end = datetime(2019, 11, 15) - >>> df = VesselClassBreakdown().search( - ... filter_activity="loading_end", - ... breakdown_unit="t", - ... breakdown_size=5, - ... filter_time_min=start, - ... filter_time_max=end - ... ).to_df() - - ``` - - Gives the following: - - | | key | value | count | - |---:|:--------------------|---------:|----------:| - | 0 | vlcc_plus | 94855526 | 24 | - | 1 | aframax | 776599 | 17 | - | 2 | handymax | 381359 | 24 | - | 3 | handysize | 238723 | 21 | - | 4 | panamax | 118285 | 18 | - | 5 | tiny_tanker | 118285 | 18 | - | 6 | general_purpose | 118285 | 18 | - | 5 | sgc | 118285 | 18 | + ```python + >>> from vortexasdk import VesselClassBreakdown + >>> start = datetime(2019, 11, 10) + >>> end = datetime(2019, 11, 15) + >>> df = VesselClassBreakdown().search( + ... filter_activity="loading_end", + ... breakdown_unit="t", + ... breakdown_size=5, + ... filter_time_min=start, + ... filter_time_max=end + ... ).to_df() + + ``` + + Gives the following: + + | | key | value | count | + |---:|:--------------------|---------:|----------:| + | 0 | vlcc_plus | 94855526 | 24 | + | 1 | aframax | 776599 | 17 | + | 2 | handymax | 381359 | 24 | + | 3 | handysize | 238723 | 21 | + | 4 | panamax | 118285 | 18 | + | 5 | tiny_tanker | 118285 | 18 | + | 6 | general_purpose | 118285 | 18 | + | 5 | sgc | 118285 | 18 | """ @@ -211,6 +223,8 @@ def search( "filter_effective_controllers": convert_to_list( exclude_effective_controllers ), + "filter_shipper": convert_to_list(exclude_shipper), + "filter_consignee": convert_to_list(exclude_consignee), "filter_origins": convert_to_list(exclude_origins), "filter_flags": convert_to_list(exclude_vessel_flags), "filter_vessel_ice_class": convert_to_list( @@ -251,6 +265,8 @@ def search( "filter_effective_controllers": convert_to_list( filter_effective_controllers ), + "filter_shipper": convert_to_list(filter_shipper), + "filter_consignee": convert_to_list(filter_consignee), "filter_destinations": convert_to_list(filter_destinations), "filter_origins": convert_to_list(filter_origins), "filter_waypoints": convert_to_list(filter_waypoints), diff --git a/vortexasdk/version.py b/vortexasdk/version.py index bd538f76..66c607f6 100644 --- a/vortexasdk/version.py +++ b/vortexasdk/version.py @@ -1 +1 @@ -__version__ = "1.0.12" +__version__ = "1.0.13"