def search(
self,
term: Union[str, List[str]] = None,
ids: Union[str, List[str]] = None,
product_parent: Union[str, List[str]] = None,
exact_term_match: bool = False,
) -> ProductResult:
"""
Find all products matching given search terms.
# Arguments
term: The name(s) (or partial name(s)) of a product we'd like to search
ids: ID or IDs of products we'd like to search
product_parent: ID, or list of IDs of the immediate product parent. E.g. `product_parent ='12345'` will return all children of product `12345`.
exact_term_match: By default, the SDK returns all products which name _includes_ the search term. For example, searching for "Gasoil" will return
results including "Gasoil", "Gasoil 0.4pc", "Gasoil 500ppm" etc. Setting `exact_search_match` to true ensure that only exact term matches are
returned, ie just "Gasoil" in this case.
# Returns
List of products matching the search arguments.
# Examples
Let's look for products with in one of `['diesel', 'fuel oil', 'grane']` their name, or related names.
```python
>>> from vortexasdk import Products
>>> df = Products().search(term=['diesel', 'fuel oil', 'grane']).to_df('all')
```
Returns
| | id | name | layer.0 | leaf | parent.0.name | parent.0.layer.0 | parent.0.id | meta.api_min | meta.api_max | ref_type | meta.sulphur_min | meta.sulphur_max |
|---:|:-------------------|:--------------|:----------|:-------|:----------------|:-------------------|:------------------|---------------:|---------------:|:-----------|-------------------:|-------------------:|
| 0 | 1c107b4317bc2c8... | Fuel Oil | category | False | Dirty products | product | 5de0b00094e0fd... | 12.8878 | 12.8878 | product | nan | nan |
| 1 | fddedd17e02507f... | Grane | grade | True | Medium-Sour | subproduct_group | a7e26956fbb917... | 29.2955 | 29.2955 | product | 0.62 | 0.62 |
| 2 | deda35eb9ca56b5... | Diesel/Gasoil | category | False | Clean products | product | b68cbb7746f8b9... | 35.9556 | 35.9556 | product | nan | nan |
# Further Documentation
[VortexaAPI Product Reference](https://docs.vortexa.com/reference/POST/reference/products)
"""
api_params = {
"term": convert_to_list(term),
"ids": convert_to_list(ids),
"product_parent": convert_to_list(product_parent),
"allowTopLevelProducts": True,
}
return ProductResult(
super().search(exact_term_match=exact_term_match, **api_params)
)
def convert_to_vessel_ids(
vessel_attributes: Union[List[Union[ID, str, int]], ID, str,
int]) -> List[ID]:
"""
Convert a mixed list of names, IDs, IMOs, or MMSIs to vessel ids.
# Example
```
>>> convert_to_vessel_ids(["Stallion", 9464326, 477639900, 'vlcc'])
[...]
```
"""
vessel_attributes_list = convert_to_list(vessel_attributes)
ids, others = split_ids_other(vessel_attributes_list)
vessel_classes = []
names_imos_mmsis = []
for e in others:
if _is_vessel_class(e):
vessel_classes.append(e)
else:
names_imos_mmsis.append(e)
vessels_matched_on_vessel_class = (_search_ids(
Vessels(), vessel_classes=vessel_classes)
if len(vessel_classes) > 0 else [])
vessels_matched_on_name_imo_mmsi = (_search_ids(
Vessels(), term=names_imos_mmsis) if len(names_imos_mmsis) > 0 else [])
return (ids + vessels_matched_on_vessel_class +
vessels_matched_on_name_imo_mmsi)
def _convert_to_ids(ids_or_names: IDsNames, searcher: Search) -> List[ID]:
"""Convert containing a mix of IDs and names to a list of IDs."""
ids_or_names_list = convert_to_list(ids_or_names)
ids, others = split_ids_other(ids_or_names_list)
if len(others) == 0:
return ids
else:
return ids + _search_ids(searcher, term=others)
def search(
self,
type: str = None,
term: Union[str, List[str]] = None,
ids: Union[str, List[str]] = None,
) -> AttributeResult:
"""
Find all attributes matching given type.
# Arguments
type: The type of attribute we're filtering on. Type can be: `ice_class`, `propulsion`, `scrubber`
# Returns
List of attributes matching `type`
# Examples
Find all attributes with a type of `ice_class`.
```python
>>> from vortexasdk import Attributes
>>> df = Attributes().search(type="scrubber").to_df()
```
returns
| | id | name | type |
|---:|:-----------------|:-----------|:------------|
| 0 | 14c7b073809eb565 | Open Loop | scrubber |
| 1 | 478fca39000c49d6 | Unkown | scrubber |
"""
search_params = {
"term": [str(e) for e in convert_to_list(term)],
"ids": convert_to_list(ids),
"type": type,
}
return AttributeResult(super().search(**search_params))
def search(
self,
filter_products: Union[ID, List[ID]] = None,
filter_vessels: Union[ID, List[ID]] = None,
filter_vessel_classes: Union[str, List[str]] = None,
filter_vessel_status: str = None,
filter_vessel_location: Union[ID, List[ID]] = None,
filter_owners: Union[ID, List[ID]] = None,
filter_destination: Union[ID, List[ID]] = None,
filter_region: str = None,
filter_port: str = None,
use_reference_port: bool = False,
filter_days_to_arrival: List[Dict[str,int]] = None,
filter_vessel_dwt_min: int = None,
filter_vessel_dwt_max: int = None,
filter_vessel_age_min: int = None,
filter_vessel_age_max: int = None,
filter_vessel_idle_min: int = None,
filter_vessel_idle_max: int = None,
filter_vessel_scrubbers: str = "disabled",
filter_recent_visits: str = None,
exclude_products: Union[ID, List[ID]] = None,
exclude_vessels: Union[ID, List[ID]] = None,
exclude_vessel_classes: Union[str, List[str]] = None,
exclude_vessel_status: str = None,
exclude_vessel_location: Union[ID, List[ID]] = None,
exclude_owners: Union[ID, List[ID]] = None,
exclude_destination: Union[ID, List[ID]] = None,
) -> TimeSeriesResult:
"""
Number and DWT of all vessels that can be available to load a given cargo at a given port,
grouped by the number of days to arrival.
# Arguments
filter_owners: An corporation ID, or list of corporation IDs to filter on.
filter_destination: 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_vessels: A vessel ID, or list of vessel IDs to filter on.
filter_vessel_classes: A vessel class, or list of vessel classes to filter on.
filter_vessel_status: The vessel status on which to base the filter. Enter 'vessel_status_ballast' for ballast vessels, 'vessel_status_laden_known' for laden vessels with known cargo (i.e. a type of cargo that Vortexa currently tracks) or 'any_activity' for any other vessels
filter_vessel_location: A location ID, or list of location IDs to filter on.
filter_port: Filter by port ID.
filter_region: Filter by region ID - takes precedence over filter_port if provided. This should be used in conjunction with `use_reference_port`
filter_days_to_arrival: Filter availability by time to arrival in days`
use_reference_port: If this flag is enabled, we will return data for
the reference port instead of the user selected one,
filter_vessel_age_min: A number between 1 and 100 (representing years).
filter_vessel_age_max: A number between 1 and 100 (representing years).
filter_vessel_idle_min: A number greater than 0 (representing idle days).
filter_vessel_idle_max: A number greater than 0 and filter_vessel_idle_min (representing idle days).
filter_vessel_dwt_min: A number between 0 and 550000.
filter_vessel_dwt_max: A number between 0 and 550000.
filter_vessel_scrubbers: Either inactive 'disabled', or included 'inc' or excluded 'exc'.
filter_recent_visits: Filter availability by each vessel's recent visits
exclude_products: A product ID, or list of product IDs to exclude.
exclude_vessels: A vessel ID, or list of vessel IDs to exclude.
exclude_vessel_classes: A vessel class, or list of vessel classes to exclude.
exclude_vessel_status: The vessel status on which to base the filter. Enter 'vessel_status_ballast' for ballast vessels, 'vessel_status_laden_known' for laden vessels with known cargo (i.e. a type of cargo that Vortexa currently tracks) or 'any_activity' for any other vessels
exclude_owners: An owner ID, or list of owner IDs to exclude.
exclude_vessel_location: A location ID, or list of location IDs to filter on.
exclude_destination: A location ID, or list of location IDs to filter on.
# Returns
`TimeSeriesResult`
# Example
_Breakdown of number and DWT of all vessels arriving at Rotterdam in the next 5 days._
```python
>>> from vortexasdk import VesselAvailabilityBreakdown, Geographies
>>> rotterdam = [g.id for g in Geographies().search("rotterdam").to_list() if "port" in g.layer]
>>> df = VesselAvailabilityBreakdown().search(
... filter_port=rotterdam[0],
... filter_days_to_arrival={"min": 0, "max": 5}
... ).to_df()
```
Gives the following:
| | key | value | count |
|---:|:-------------------------|----------:|----------:|
| 0 | 2021-06-23 00:00:00+00:00| 2939754 | 34 |
| 1 | 2021-06-24 00:00:00+00:00| 2676732 | 38 |
| 2 | 2021-06-25 00:00:00+00:00| 6262914 | 74 |
| 3 | 2021-06-26 00:00:00+00:00| 3445105 | 43 |
| 4 | 2021-06-27 00:00:00+00:00| 3924460 | 51 |
"""
exclude_params = {
"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_owners": convert_to_list(exclude_owners),
"filter_vessel_status": convert_to_list(exclude_vessel_status),
"filter_vessel_location": convert_to_list(
exclude_vessel_location
),
}
api_params = {
"filter_products": convert_to_list(filter_products),
"filter_vessels": convert_to_list(filter_vessels),
"filter_vessel_classes": convert_to_list(
filter_vessel_classes
),
"filter_vessel_status": filter_vessel_status,
"filter_vessel_location": convert_to_list(filter_vessel_location),
"filter_owners": convert_to_list(filter_owners),
"filter_destination": convert_to_list(filter_destination),
"filter_region": filter_region,
"filter_port": filter_port,
"use_reference_port": use_reference_port,
"filter_days_to_arrival": convert_to_list(
filter_days_to_arrival
),
"filter_vessel_dwt_min": filter_vessel_dwt_min,
"filter_vessel_dwt_max": filter_vessel_dwt_max,
"filter_vessel_age_min": filter_vessel_age_min,
"filter_vessel_age_max": filter_vessel_age_max,
"filter_vessel_idle_min": filter_vessel_idle_min,
"filter_vessel_idle_max": filter_vessel_idle_max,
"filter_vessel_scrubbers": filter_vessel_scrubbers,
"filter_recent_visits": filter_recent_visits,
"exclude": exclude_params,
}
return TimeSeriesResult(super().search(response_type="breakdown", **api_params))
def search(
self,
filter_time_min: datetime = datetime(2019, 10, 1, 0),
filter_time_max: datetime = datetime(2019, 10, 1, 1),
unit: str = "b",
filter_activity: str = None,
filter_charterers: Union[ID, List[ID]] = None,
filter_destinations: Union[ID, List[ID]] = None,
filter_origins: Union[ID, List[ID]] = None,
filter_owners: Union[ID, List[ID]] = None,
filter_products: Union[ID, List[ID]] = None,
filter_vessels: Union[ID, List[ID]] = None,
filter_vessel_classes: Union[ID, List[ID]] = None,
filter_vessel_status: str = None,
filter_vessel_age_min: int = None,
filter_vessel_age_max: int = None,
filter_vessel_scrubbers: str = "disabled",
filter_vessel_flags: Union[ID, List[ID]] = None,
filter_vessel_ice_class: Union[ID, List[ID]] = None,
filter_vessel_propulsion: Union[ID, List[ID]] = None,
exclude_origins: Union[ID, List[ID]] = None,
exclude_destinations: Union[ID, List[ID]] = None,
exclude_products: Union[ID, List[ID]] = None,
exclude_vessels: Union[ID, List[ID]] = None,
exclude_vessel_classes: Union[ID, List[ID]] = None,
exclude_charterers: Union[ID, List[ID]] = None,
exclude_owners: Union[ID, List[ID]] = None,
exclude_vessel_flags: Union[ID, List[ID]] = None,
exclude_vessel_ice_class: Union[ID, List[ID]] = None,
exclude_vessel_propulsion: Union[ID, List[ID]] = None,
) -> VesselMovementsResult:
"""
Find VesselMovements matching the given search parameters.
# Arguments
filter_activity: Movement activity on which to base the time filter. Must be one of ['loading_state',
'loading_start', 'loading_end', 'identified_for_loading_state', 'unloading_state', 'unloading_start',
'unloading_end', 'unloaded_state', 'storing_state', 'storing_start', 'storing_end', 'transiting_state',
'any_activity'].
filter_time_min: The UTC start date of the time filter.
filter_time_max: The UTC end date of the time filter.
unit: Unit of measurement. Enter 'b' for barrels or 't' for tonnes.
filter_charterers: A charterer ID, or list of charterer IDs to filter on.
filter_destinations: 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_owners: An corporation ID, or list of corporation 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.
filter_vessel_classes: A vessel class, or list of vessel classes to filter on.
filter_vessel_status: The vessel status on which to base the filter. Enter 'vessel_status_ballast' for ballast vessels, 'vessel_status_laden_known' for laden vessels with known cargo (i.e. a type of cargo that Vortexa currently tracks) or 'vessel_status_laden_unknown' for laden vessels with unknown cargo (i.e. a type of cargo that Vortexa currently does not track).
filter_vessel_age_min: A number between 1 and 100 (representing years).
filter_vessel_age_max: A number between 1 and 100 (representing years).
filter_vessel_scrubbers: Either inactive 'disabled', or included 'inc' or excluded 'exc'.
filter_vessel_flags: A geography ID, or list of geography IDs to filter on.
filter_vessel_ice_class: An attribute ID, or list of attribute IDs to filter on.
filter_vessel_propulsion: An attribute ID, or list of attribute IDs to filter on.
exclude_origins: A geography ID, or list of geography IDs to exclude.
exclude_destinations: A geography ID, or list of geography IDs to exclude.
exclude_products: A product ID, or list of product IDs to exclude.
exclude_vessels: A vessel ID, or list of vessel IDs to exclude.
exclude_vessel_classes: A vessel class, or list of vessel classes to exclude.
exclude_charterers: A charterer ID, or list of charterer IDs to exclude.
exclude_owners: An owner ID, or list of owner 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.
exclude_vessel_propulsion: An attribute ID, or list of attribute IDs to exclude.
# Returns
`VesselMovementsResult`, containing all the vessel movements matching the given search terms.
# Example
Let's search for all vessels that departed from `Rotterdam [NL]` on the morning of 1st December 2018.
```python
>>> from vortexasdk import VesselMovements, Geographies
>>> rotterdam = [g.id for g in Geographies().search("rotterdam").to_list() if "port" in g.layer]
>>> df = VesselMovements().search(
... filter_time_min=datetime(2017, 10, 1, 0, 0),
... filter_time_max=datetime(2017, 10, 1, 0, 10),
... filter_origins=rotterdam
... ).to_df().head(2)
```
| | start_timestamp | end_timestamp | vessel.imo | vessel.name | vessel.vessel_class | origin.location.country.label | origin.location.port.label | destination.location.country.label | destination.location.port.label | cargoes.0.quantity | cargoes.0.product.grade.label |
|---:|:-------------------------|:-------------------------|-------------:|:--------------|:----------------------|:--------------------------------|:-----------------------------|:-------------------------------------|:----------------------------------|---------------------:|:--------------------------------|
| 0 | 2017-09-30T15:30:27+0000 | 2017-10-03T01:46:06+0000 | 9.21091e+06 | ADEBOMI 3 | handysize | Netherlands | Rotterdam [NL] | Netherlands | Rotterdam [NL] | nan | nan |
| 1 | 2017-08-29T14:51:32+0000 | 2017-10-04T14:46:21+0000 | 9.64544e+06 | AEGEAN VISION | suezmax | Netherlands | Rotterdam [NL] | Singapore | Singapore [SG] | 852261 | High Sulphur |
[Vessel Movements Endpoint Further Documentation](https://docs.vortexa.com/reference/POST/vessel-movements/search)
"""
exclude_params = {
"filter_origins": convert_to_list(exclude_origins),
"filter_destinations": convert_to_list(exclude_destinations),
"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_charterers),
"filter_owners": convert_to_list(exclude_owners),
"filter_vessel_flags": convert_to_list(exclude_vessel_flags),
"filter_vessel_ice_class":
convert_to_list(exclude_vessel_ice_class),
"filter_vessel_propulsion":
convert_to_list(exclude_vessel_propulsion),
}
api_params = {
"filter_activity": filter_activity,
"filter_time_min": to_ISODate(filter_time_min),
"filter_time_max": to_ISODate(filter_time_max),
"unit": unit,
"filter_charterers": convert_to_list(filter_charterers),
"filter_owners": convert_to_list(filter_owners),
"filter_destinations": convert_to_list(filter_destinations),
"filter_origins": convert_to_list(filter_origins),
"filter_products": convert_to_list(filter_products),
"filter_vessels": convert_to_list(filter_vessels),
"filter_vessel_classes": convert_to_list(filter_vessel_classes),
"filter_vessel_status": filter_vessel_status,
"filter_vessel_age_min": filter_vessel_age_min,
"filter_vessel_age_max": filter_vessel_age_max,
"filter_vessel_scrubbers": filter_vessel_scrubbers,
"filter_vessel_flags": convert_to_list(filter_vessel_flags),
"filter_vessel_ice_class":
convert_to_list(filter_vessel_ice_class),
"filter_vessel_propulsion":
convert_to_list(filter_vessel_propulsion),
"exclude": exclude_params,
"size": self._MAX_PAGE_RESULT_SIZE,
}
return VesselMovementsResult(super().search(**api_params))
def search(
self,
timeseries_frequency: str = None,
timeseries_unit: str = None,
timeseries_property: str = None,
filter_products: Union[ID, List[ID]] = None,
filter_charterers: Union[ID, List[ID]] = None,
filter_owners: Union[ID, List[ID]] = None,
filter_origins: Union[ID, List[ID]] = None,
filter_destinations: Union[ID, List[ID]] = None,
filter_vessels: Union[ID, List[ID]] = None,
filter_vessel_classes: Union[ID, List[ID]] = None,
filter_vessel_flags: Union[ID, List[ID]] = None,
filter_vessel_ice_class: Union[ID, List[ID]] = None,
filter_vessel_propulsion: Union[ID, List[ID]] = None,
filter_vessel_tags: Union [List[Tag], Tag] = None,
filter_vessel_risk_levels: Union[ID, List[ID]] = None,
filter_vessel_scrubbers: str = "disabled",
filter_vessel_age_min: int = None,
filter_vessel_age_max: int = None,
filter_vessel_dwt_min: int = None,
filter_vessel_dwt_max: int = None,
filter_ship_to_ship: bool = None,
filter_charterer_exists: bool = None,
filter_activity: str = None,
filter_time_min: datetime = datetime(2019, 10, 1, 0),
filter_time_max: datetime = datetime(2019, 10, 1, 1),
filter_vessel_status: Union[ID, List[ID]] = None,
exclude_origins: Union[ID, List[ID]] = None,
exclude_destinations: Union[ID, List[ID]] = None,
exclude_products: Union[ID, List[ID]] = None,
exclude_vessels: Union[ID, List[ID]] = None,
exclude_vessel_classes: Union[ID, List[ID]] = None,
exclude_charterers: Union[ID, List[ID]] = None,
exclude_owners: Union[ID, List[ID]] = None,
exclude_vessel_flags: Union[ID, List[ID]] = None,
exclude_vessel_ice_class: Union[ID, List[ID]] = None,
exclude_vessel_propulsion: Union[ID, List[ID]] = None,
exclude_vessel_tags: Union [List[Tag], Tag] = None,
exclude_vessel_risk_levels: Union[ID, List[ID]] = None,
) -> BreakdownResult:
"""
Sum of cargoes quantity for each day. For frequencies other than ‘day’, the values returned are
calculated by summing each daily cargo quantity bucket and returning the total.
# Arguments
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,
cargo movement count, cargo movement count per day, respectively.
timeseries_frequency: Frequency denoting the granularity of the time series. Must be one of the following: `'day'`, `'week'`, `'doe_week'`, `'month'`, `'quarter'`, `'year'`.
timeseries_property: Property on the vessel movement used to build the value of the aggregation. By default it is “quantity”. Must be one of the following: `'quantity’`, `‘vessel_class’`,
`‘vessel_flag’`, `‘origin_region’`, `‘origin_trading_region’`, `‘origin_trading_sub_region’`, `‘origin_country’`,
`‘origin_port’`, `‘origin_terminal’`, `‘destination_region’`, `‘destination_trading_region’`,
`‘destination_trading_sub_region’`, `‘destination_country’`, `‘destination_port’`, `‘destination_terminal’`,
`'product_group'`, `'product_group_product'`, `'product_category'`, `'product_grade'`.
filter_time_min: The UTC start date of the time filter.
filter_time_max: The UTC end date of the time filter.
filter_products: A product ID, or list of product IDs to filter on.
filter_charterers: A charterer entity ID, or list of product IDs to filter on.
filter_owners: An owner ID, or list of owner IDs to filter on.
filter_origins: 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_vessels: A vessel ID, or list of vessel IDs to filter on.
filter_vessel_classes: A vessel class, or list of vessel classes to filter on.
filter_vessel_flags: A vessel flag ID, or list of vessel flag IDs to filter on.
filter_vessel_ice_class: A vessel ice class ID, or list of vessel ice class IDs to filter on.
filter_vessel_propulsion: A vessel propulsion ID, or list of vessel propulsion IDs to filter on.
filter_vessel_tag: A time bound vessel tag, or list of time bound vessel tags to filter on.
filter_vessel_risk_levels: A vessel risk level, or list of vessel risk levels 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_age_max: A number between 1 and 100 (representing years).
filter_vessel_age_min: A number between 0 and 550000.
filter_vessel_age_max: A number between 0 and 550000.
filter_activity: Movement activity on which to base the time filter. Must be one of: `'loading_state'`,
`'oil_on_water_state'`, `'unloading_state'`, `'ship_to_ship'`, `'storing_state'`, `'transiting_state'`
filter_vessel_status: The vessel status on which to base the filter. Enter 'vessel_status_ballast' for ballast vessels, 'vessel_status_laden_known' for laden vessels with known cargo (i.e. a type of cargo that Vortexa currently tracks) or 'any_activity' for any other vessels.
filter_charterer_exists: A boolean to include or exclude the records to those that have a charterer.
filter_ship_to_ship: A boolean to include or exclude the records to those that are involved in an STS.
exclude_filter_products: A product ID, or list of product IDs to exclude.
exclude_filter_charterers: A charterer entity ID, or list of product IDs to exclude.
exclude_filter_owners: An owner ID, or list of owner IDs to exclude.
exclude_filter_origins: A geography ID, or list of geography IDs to exclude.
exclude_filter_destinations: A geography ID, or list of geography IDs to exclude.
exclude_filter_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_filter_vessel_ice_class: A vessel ice class ID, or list of vessel ice class IDs to exclude.
exclude_filter_vessel_propulsion: A vessel propulsion ID, or list of vessel propulsion IDs to exclude.
exclude_filter_vessel_tag: A time bound vessel tag, or list of time bound vessel tags to exclude.
exclude_filter_vessel_risk_levels: A vessel risk level, or list of vessel risk levels to exclude.
# Returns
`BreakdownResult`
# Example
_Ton days demand of vessels from the Middle East over the last 7 days._
```python
>>> from vortexasdk import FleetUtilisationQuantityTimeseries
>>> from datetime import datetime
>>> search_result = FleetUtilisationQuantityTimeseries().search(
... filter_vessel_status="vessel_status_laden_known",
... filter_origins="80aa9e4f3014c3d96559c8e642157edbb2b684ea0144ed76cd20b3af75110877",
... filter_time_min=datetime(2021, 1, 11),
... filter_time_max=datetime(2021, 1, 18),
... timeseries_unit="t",
... timeseries_frequency="day",
... timeseries_property="quantity")
>>> df = search_result.to_df()
```
Gives the following:
| | key | value | count | breakdown.0.label | breakdown.0.value |breakdown.0.count |
|---:|:-------------------------|----------:|----------:|--------------------:|------------------:|-----------------:|
| 7 | 2021-01-18 00:00:00+00:00| 69661114 | 688 | "quantity" | 69661114 |688 |
| 0 | 2021-01-11 00:00:00+00:00| 73208724 | 738 | "quantity" | 73208724 |738 |
| 1 | 2021-01-12 00:00:00+00:00| 73586280 | 732 | "quantity" | 73586280 |732 |
| 2 | 2021-01-13 00:00:00+00:00| 74638888 | 736 | "quantity" | 74638888 |736 |
| 3 | 2021-01-14 00:00:00+00:00| 74958932 | 746 | "quantity" | 74958932 |746 |
| 4 | 2021-01-15 00:00:00+00:00| 74230202 | 737 | "quantity" | 74230202 |737 |
| 5 | 2021-01-16 00:00:00+00:00| 73723336 | 738 | "quantity" | 73723336 |738 |
| 6 | 2021-01-17 00:00:00+00:00| 74216473 | 751 | "quantity" | 74216473 |751 |
"""
sts_filter = sts_param_value(filter_ship_to_ship)
crossfilters = {
"filter_ship_to_ship": sts_filter["x_filter"],
# if charterer toggle is True, apply cross filter
# else make it false
"filter_charterer_exists": filter_charterer_exists == True
}
exclude_params = {
"filter_destinations": convert_to_list(exclude_destinations),
"filter_products": convert_to_list(exclude_products),
"filter_vessels": convert_to_list(exclude_vessels),
"filter_vessel_classes": convert_to_list(exclude_vessel_classes),
"filter_owners": convert_to_list(exclude_owners),
"filter_origins": convert_to_list(exclude_origins),
"filter_charterers": convert_to_list(exclude_charterers),
"filter_vessel_flags": convert_to_list(exclude_vessel_flags),
"filter_vessel_ice_class": convert_to_list(exclude_vessel_ice_class),
"filter_vessel_propulsion": convert_to_list(exclude_vessel_propulsion),
"filter_vessel_risk_levels": convert_to_list(exclude_vessel_risk_levels),
"filter_ship_to_ship": sts_filter["exclude"]
}
api_params = {
"timeseries_frequency": timeseries_frequency,
"timeseries_unit": timeseries_unit,
"timeseries_property": timeseries_property,
"filter_activity": filter_activity,
"filter_time_min": to_ISODate(filter_time_min),
"filter_time_max": to_ISODate(filter_time_max),
"filter_vessel_age_min": filter_vessel_age_min,
"filter_vessel_age_max": filter_vessel_age_max,
"filter_vessel_dwt_min": filter_vessel_dwt_min,
"filter_vessel_dwt_max": filter_vessel_dwt_max,
"filter_vessel_status": convert_to_list(filter_vessel_status),
"filter_charterers": convert_to_list(filter_charterers),
"filter_owners": convert_to_list(filter_owners),
"filter_products": convert_to_list(filter_products),
"filter_vessels": convert_to_list(filter_vessels),
"filter_vessel_classes": convert_to_list(filter_vessel_classes),
"filter_vessel_flags": convert_to_list(filter_vessel_flags),
"filter_destinations": convert_to_list(filter_destinations),
"filter_origins": convert_to_list(filter_origins),
"filter_vessel_ice_class": convert_to_list(filter_vessel_ice_class),
"filter_vessel_propulsion": convert_to_list(filter_vessel_propulsion),
"vessel_tags": convert_to_list(filter_vessel_tags),
"vessel_tags_excluded": convert_to_list(exclude_vessel_tags),
"filter_vessel_risk_levels": convert_to_list(filter_vessel_risk_levels),
"filter_vessel_scrubbers": filter_vessel_scrubbers,
"exclude": exclude_params,
"crossfilters": crossfilters,
}
return BreakdownResult(super().search(**api_params))
def search(
self,
breakdown_geography: str = "country",
breakdown_unit_average_basis: str = None,
filter_activity: str = "any_activity",
breakdown_unit: str = "b",
disable_geographic_exclusion_rules: bool = None,
breakdown_size: int = None,
filter_time_min: datetime = datetime(2019, 10, 1, 0),
filter_time_max: datetime = datetime(2019, 10, 1, 1),
filter_products: Union[ID, List[ID]] = None,
filter_charterers: Union[ID, List[ID]] = None,
filter_vessels: Union[ID, List[ID]] = None,
filter_vessel_classes: Union[str, List[str]] = None,
filter_owners: Union[ID, List[ID]] = None,
filter_vessel_flags: Union[ID, List[ID]] = None,
filter_vessel_ice_class: Union[ID, List[ID]] = None,
filter_vessel_propulsion: Union[ID, List[ID]] = None,
filter_origins: Union[ID, List[ID]] = None,
filter_destinations: Union[ID, List[ID]] = None,
filter_storage_locations: Union[ID, List[ID]] = None,
filter_waypoints: Union[ID, List[ID]] = None,
filter_ship_to_ship_locations: Union[ID, List[ID]] = None,
filter_vessel_age_min: int = None,
filter_vessel_age_max: int = None,
filter_vessel_scrubbers: str = "disabled",
filter_vessel_tags: Union[List[Tag], Tag] = None,
exclude_products: Union[ID, List[ID]] = None,
exclude_vessels: Union[ID, List[ID]] = None,
exclude_vessel_classes: Union[str, List[str]] = None,
exclude_owners: Union[ID, List[ID]] = None,
exclude_charterers: Union[ID, List[ID]] = None,
exclude_vessel_flags: Union[ID, List[ID]] = None,
exclude_destinations: Union[ID, List[ID]] = None,
exclude_origins: Union[ID, List[ID]] = None,
exclude_waypoints: Union[ID, List[ID]] = None,
exclude_storage_locations: Union[ID, List[ID]] = None,
exclude_ship_to_ship_locations: Union[ID, List[ID]] = None,
exclude_vessel_ice_class: Union[ID, List[ID]] = None,
exclude_vessel_propulsion: Union[ID, List[ID]] = None,
exclude_vessel_tags: Union[List[Tag], Tag] = None,
) -> ReferenceBreakdownResult:
"""
Destination locations breakdown aggregation by geographic area
# 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: Units to aggregate upon. Must be one of the following: `'b'`, `'t'`, `'cbm'`, `'bpd'`, `'tpd'`, `'mpd'`.
breakdown_geography: Geography hierarchy of the origin to aggregate upon. Must be one of the following: `'terminal'`, `'port'`,`'country'`, `'shipping_region'`,
`'region'`,`'trading_block'`,`'trading_region'`,`'trading_subregion'`,`'sts_zone'`,`'waypoint'`.
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.
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_max: The UTC end date of the time filter.
filter_owners: An corporation ID, or list of corporation 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_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_origins: 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_storage_locations: 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_ship_to_ship_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_vessels: A vessel ID, or list of vessel IDs to filter on.
filter_vessel_classes: A vessel class, or list of vessel classes to filter on.
filter_vessel_age_min: A number between 1 and 100 (representing years).
filter_vessel_age_max: A number between 1 and 100 (representing years).
filter_vessel_scrubbers: Either inactive 'disabled', or included 'inc' or excluded 'exc'.
filter_vessel_tags: A time bound vessel tag, or list of time bound vessel tags to filter on.
exclude_products: A product ID, or list of product IDs to exclude.
exclude_vessel_flags: A vessel flag ID, or list of vessel flag IDs to exclude.
exclude_vessel_ice_class: An ice class ID, or list of ice class IDs to exclude.
exclude_vessel_propulsion: An propulsion means ID, or list of propulsion means IDs to exclude.
exclude_vessels: A vessel ID, or list of vessel IDs to exclude.
exclude_vessel_classes: A vessel class, or list of vessel classes to exclude.
exclude_owners: An owner ID, or list of owner IDs to exclude.
exclude_vessel_location: A location ID, or list of location IDs to exclude.
exclude_destinations: A location ID, or list of location IDs to exclude.
exclude_origins: A location ID, or list of location IDs to exclude.
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.
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 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 |
"""
exclude_params = {
"filter_destinations": convert_to_list(exclude_destinations),
"filter_products": convert_to_list(exclude_products),
"filter_vessels": convert_to_list(exclude_vessels),
"filter_charterers": convert_to_list(exclude_charterers),
"filter_vessel_classes": convert_to_list(exclude_vessel_classes),
"filter_owners": convert_to_list(exclude_owners),
"filter_origins": convert_to_list(exclude_origins),
"filter_flags": convert_to_list(exclude_vessel_flags),
"filter_vessel_ice_class": convert_to_list(exclude_vessel_ice_class),
"filter_vessel_propulsion": convert_to_list(exclude_vessel_propulsion),
"filter_storage_locations": convert_to_list(exclude_storage_locations),
"filter_waypoints": convert_to_list(exclude_waypoints),
"filter_ship_to_ship": convert_to_list(exclude_ship_to_ship_locations),
}
api_params = {
"breakdown_unit_average_basis": breakdown_unit_average_basis,
"breakdown_unit": breakdown_unit,
"breakdown_size": breakdown_size,
"breakdown_geography": breakdown_geography,
"disable_geographic_exclusion_rules": disable_geographic_exclusion_rules,
"filter_time_min": to_ISODate(filter_time_min),
"filter_time_max": to_ISODate(filter_time_max),
"filter_activity": filter_activity,
"filter_products": convert_to_list(filter_products),
"filter_charterers": convert_to_list(filter_charterers),
"filter_vessels": convert_to_list(filter_vessels),
"filter_vessel_classes": convert_to_list(
filter_vessel_classes
),
"filter_vessel_flags": convert_to_list(filter_vessel_flags),
"filter_vessel_ice_class": convert_to_list(filter_vessel_ice_class),
"filter_vessel_propulsion": convert_to_list(filter_vessel_propulsion),
"filter_owners": convert_to_list(filter_owners),
"filter_destinations": convert_to_list(filter_destinations),
"filter_origins": convert_to_list(filter_origins),
"filter_waypoints": convert_to_list(filter_waypoints),
"filter_charterers": convert_to_list(filter_charterers),
"filter_storage_locations": convert_to_list(filter_storage_locations),
"filter_ship_to_ship_locations": convert_to_list(filter_ship_to_ship_locations),
"filter_vessel_age_min": filter_vessel_age_min,
"filter_vessel_age_max": filter_vessel_age_max,
"filter_vessel_scrubbers": filter_vessel_scrubbers,
"vessel_tags": convert_to_list(filter_vessel_tags),
"vessel_tags_excluded": convert_to_list(exclude_vessel_tags),
"exclude": exclude_params,
"include_reference": self._INCLUDE_REFERENCE_DATA,
}
return ReferenceBreakdownResult(super().search(response_type="breakdown", **api_params))
def search(
self,
filter_time_min: datetime = datetime(2019, 10, 1, 0),
filter_time_max: datetime = datetime(2019, 10, 1, 1),
filter_products: Union[ID, List[ID]] = None,
filter_vessels: Union[ID, List[ID]] = None,
filter_vessel_classes: Union[str, List[str]] = None,
filter_vessel_status: str = None,
filter_vessel_location: Union[ID, List[ID]] = None,
filter_owners: Union[ID, List[ID]] = None,
filter_destination: Union[ID, List[ID]] = None,
filter_region: str = None,
filter_port: str = None,
use_reference_port: bool = False,
filter_days_to_arrival: List[Dict[str, int]] = None,
filter_vessel_dwt_min: int = None,
filter_vessel_dwt_max: int = None,
filter_vessel_age_min: int = None,
filter_vessel_age_max: int = None,
filter_vessel_idle_min: int = None,
filter_vessel_idle_max: int = None,
filter_vessel_scrubbers: str = "disabled",
filter_recent_visits: str = None,
exclude_products: Union[ID, List[ID]] = None,
exclude_vessels: Union[ID, List[ID]] = None,
exclude_vessel_classes: Union[str, List[str]] = None,
exclude_vessel_status: str = None,
exclude_vessel_location: Union[ID, List[ID]] = None,
exclude_owners: Union[ID, List[ID]] = None,
exclude_destination: Union[ID, List[ID]] = None,
) -> TimeSeriesResult:
"""
Time series of the number of vessels that can be available to load a given cargo at a given port for
every day in the specified range.
# Arguments
filter_time_min: The UTC start date of the time filter.
filter_time_max: The UTC end date of the time filter.
filter_owners: An corporation ID, or list of corporation IDs to filter on.
filter_destination: 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_vessels: A vessel ID, or list of vessel IDs to filter on.
filter_vessel_classes: A vessel class, or list of vessel classes to filter on.
filter_vessel_status: The vessel status on which to base the filter. Enter 'vessel_status_ballast' for ballast vessels, 'vessel_status_laden_known' for laden vessels with known cargo (i.e. a type of cargo that Vortexa currently tracks) or 'any_activity' for any other vessels
filter_vessel_location: A location ID, or list of location IDs to filter on.
filter_port: Filter by port ID.
filter_region: Filter by region ID - takes precedence over filter_port if provided. This should be used in conjunction with `use_reference_port`
filter_days_to_arrival: Filter availability by time to arrival in days`
use_reference_port: If this flag is enabled, we will return data for
the reference port instead of the user selected one,
filter_vessel_age_min: A number between 1 and 100 (representing years).
filter_vessel_age_max: A number between 1 and 100 (representing years).
filter_vessel_idle_min: A number greater than 0 (representing idle days).
filter_vessel_idle_max: A number greater than 0 and filter_vessel_idle_min (representing idle days).
filter_vessel_dwt_min: A number between 0 and 550000.
filter_vessel_dwt_max: A number between 0 and 550000.
filter_vessel_scrubbers: Either inactive 'disabled', or included 'inc' or excluded 'exc'.
filter_recent_visits: Filter availability by each vessel's recent visits
exclude_products: A product ID, or list of product IDs to exclude.
exclude_vessels: A vessel ID, or list of vessel IDs to exclude.
exclude_vessel_classes: A vessel class, or list of vessel classes to exclude.
exclude_vessel_status: The vessel status on which to base the filter. Enter 'vessel_status_ballast' for ballast vessels, 'vessel_status_laden_known' for laden vessels with known cargo (i.e. a type of cargo that Vortexa currently tracks) or 'any_activity' for any other vessels
exclude_owners: An owner ID, or list of owner IDs to exclude.
exclude_vessel_location: A location ID, or list of location IDs to filter on.
exclude_destination: A location ID, or list of location IDs to filter on.
# Returns
`TimeSeriesResult`
# Example
_Time series for the number of vessels available between 0 to 5 days, at port Rotterdam, over 4 days._
```python
>>> from vortexasdk import VesselAvailabilityTimeseries, Geographies
>>> from datetime import datetime
>>> rotterdam = "68faf65af1345067f11dc6723b8da32f00e304a6f33c000118fccd81947deb4e"
>>> start = datetime(2021, 6, 17)
>>> end = datetime(2021, 6, 21)
>>> df = (VesselAvailabilityTimeseries().search(
... filter_time_min=start,
... filter_time_max=end,
... filter_port=rotterdam,
... filter_days_to_arrival={"min": 0, "max": 5},
... ).to_df())
```
Gives the following:
| | key | value | count |
|---:|:-------------------------|----------:|----------:|
| 0 | 2021-06-23 00:00:00+00:00| 19225923 | 224 |
| 1 | 2021-06-24 00:00:00+00:00| 19634766 | 233 |
| 2 | 2021-06-25 00:00:00+00:00| 19154857 | 228 |
| 3 | 2021-06-26 00:00:00+00:00| 18410395 | 225 |
"""
exclude_params = {
"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_owners": convert_to_list(exclude_owners),
"filter_vessel_status": convert_to_list(exclude_vessel_status),
"filter_vessel_location": convert_to_list(exclude_vessel_location),
}
api_params = {
"filter_time_min": to_ISODate(filter_time_min),
"filter_time_max": to_ISODate(filter_time_max),
"filter_products": convert_to_list(filter_products),
"filter_vessels": convert_to_list(filter_vessels),
"filter_vessel_classes": convert_to_list(filter_vessel_classes),
"filter_vessel_status": filter_vessel_status,
"filter_vessel_location": convert_to_list(filter_vessel_location),
"filter_owners": convert_to_list(filter_owners),
"filter_destination": convert_to_list(filter_destination),
"filter_region": filter_region,
"filter_port": filter_port,
"use_reference_port": use_reference_port,
"filter_days_to_arrival": convert_to_list(filter_days_to_arrival),
"filter_vessel_dwt_min": filter_vessel_dwt_min,
"filter_vessel_dwt_max": filter_vessel_dwt_max,
"filter_vessel_age_min": filter_vessel_age_min,
"filter_vessel_age_max": filter_vessel_age_max,
"filter_vessel_idle_min": filter_vessel_idle_min,
"filter_vessel_idle_max": filter_vessel_idle_max,
"filter_vessel_scrubbers": filter_vessel_scrubbers,
"filter_recent_visits": filter_recent_visits,
"exclude": exclude_params,
}
return TimeSeriesResult(super().search(response_type="breakdown",
**api_params))
def search(
self,
filter_activity: str,
filter_time_min: datetime = datetime(2019, 10, 1, 0),
filter_time_max: datetime = datetime(2019, 10, 1, 1),
cm_unit: str = "b",
filter_charterers: Union[ID, List[ID]] = None,
filter_destinations: Union[ID, List[ID]] = None,
filter_origins: Union[ID, List[ID]] = None,
filter_owners: Union[ID, List[ID]] = None,
filter_products: Union[ID, List[ID]] = None,
filter_vessels: Union[ID, List[ID]] = None,
filter_storage_locations: Union[ID, List[ID]] = None,
filter_ship_to_ship_locations: Union[ID, List[ID]] = None,
filter_waypoints: Union[ID, List[ID]] = None,
filter_vessel_age_min: int = None,
filter_vessel_age_max: int = None,
filter_vessel_scrubbers: str = "disabled",
filter_vessel_flags: Union[ID, List[ID]] = None,
filter_vessel_ice_class: Union[ID, List[ID]] = None,
filter_vessel_propulsion: Union[ID, List[ID]] = None,
exclude_origins: Union[ID, List[ID]] = None,
exclude_destinations: Union[ID, List[ID]] = None,
exclude_products: Union[ID, List[ID]] = None,
exclude_vessels: Union[ID, List[ID]] = None,
exclude_charterers: Union[ID, List[ID]] = None,
exclude_owners: Union[ID, List[ID]] = None,
exclude_vessel_flags: Union[ID, List[ID]] = None,
exclude_vessel_ice_class: Union[ID, List[ID]] = None,
exclude_vessel_propulsion: Union[ID, List[ID]] = None,
disable_geographic_exclusion_rules: bool = None,
timeseries_activity_time_span_min: int = None,
timeseries_activity_time_span_max: int = None,
) -> CargoMovementsResult:
"""
Find CargoMovements matching the given search parameters.
# Arguments
filter_activity: Movement activity on which to base the time filter. Must be one of ['loading_state',
'loading_start', 'loading_end', 'identified_for_loading_state', 'unloading_state', 'unloading_start',
'unloading_end', 'unloaded_state', 'storing_state', 'storing_start', 'storing_end', 'transiting_state',
'any_activity'].
filter_time_min: The UTC start date of the time filter.
filter_time_max: The UTC end date of the time filter.
cm_unit: Unit of measurement. Enter 'b' for barrels or 't' for tonnes.
filter_charterers: A charterer ID, or list of charterer IDs to filter on.
filter_destinations: 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_owners: An owner ID, or list of owner 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.
filter_storage_locations: 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_waypoints: A geography ID, or list of geography IDs to filter on.
filter_vessel_age_min: A number between 1 and 100 (representing years).
filter_vessel_age_max: A number between 1 and 100 (representing years).
filter_vessel_scrubbers: Either inactive 'disabled', or included 'inc' or excluded 'exc'.
filter_vessel_flags: A vessel flag, or list of vessel flags to filter on.
filter_vessel_ice_class: An attribute ID, or list of attribute IDs to filter on.
filter_vessel_propulsion: An attribute ID, or list of attribute IDs to filter on.
exclude_origins: A geography ID, or list of geography IDs to exclude.
exclude_destinations: A geography ID, or list of geography IDs to exclude.
exclude_products: A product ID, or list of product IDs to exclude.
exclude_vessels: A vessel ID, or list of vessel IDs to exclude.
exclude_charterers: A charterer ID, or list of charterer IDs to exclude.
exclude_owners: An owner ID, or list of owner 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.
exclude_vessel_propulsion: An attribute ID, or list of attribute IDs to exclude.
disable_geographic_exclusion_rules: This controls a popular industry term "intra-movements" and determines
the filter behaviour for cargo leaving then entering the same geographic area.
timeseries_activity_time_span_min: The minimum amount of time in milliseconds accounted for in a time series
activity. Can be used to request long-term floating storage. For example, to only return floating storage
movements that occured for _more_ than 14 days enter
`timeseries_activity_time_span_min=1000 * 60 * 60 * 24 * 14` in conjunction with
`filter_activity='storing_state'`.
timeseries_activity_time_span_max: The maximum amount of time in milliseconds accounted for in a time series
activity. Can be used to request short-term floating storage. For example, to only return floating storage
movements that occured for _less_ than 14 days enter
`timeseries_activity_time_span_max=1000 * 60 * 60 * 24 * 14`
in conjunction with `filter_activity='storing_state'`.
# Returns
`CargoMovementsResult`, containing all the cargo movements matching the given search terms.
# Example
* _Which cargoes were loaded from Rotterdam on the morning of 1st December 2018?_
```python
>>> from vortexasdk import CargoMovements, Geographies
>>> rotterdam = [g.id for g in Geographies().search("rotterdam").to_list() if "port" in g.layer]
>>> search_result = CargoMovements().search(
... filter_origins=rotterdam,
... filter_activity='loading_state',
... filter_time_min=datetime(2018, 12, 1),
... filter_time_max=datetime(2018, 12, 1, 12))
>>> df = search_result.to_df(columns=['product.grade.label', 'product.group.label', 'vessels.0.vessel_class'])
```
| | product.group.label | product.grade.label | vessels.0.vessel_class |
|---:|:----------------------|:--------------------------------|:-------------------------|
| 0 | Clean products | Pygas | general_purpose |
| 1 | Clean products | Chemicals | tiny_tanker |
| 2 | Clean products | Chemicals | tiny_tanker |
| 3 | Dirty products | Low Sulphur VGO (LSVGO) | general_purpose |
| 4 | Clean products | ULSD (Ultra Low Sulphur Diesel) | general_purpose |
| 5 | Clean products | Chemicals | tiny_tanker |
| 6 | Clean products | Finished Gasoline | handymax |
* _Which VLCC cargoes passed through the Suez canal en route to China?_
Note here we include vessels.0..., vessels.1..., vessels.2... columns.
This lets us view all vessels present in any STS operations.
```python
>>> from vortexasdk import CargoMovements, Geographies, Vessels
>>> suez = [g.id for g in Geographies().search("suez").to_list()]
>>> china = [g.id for g in Geographies().search("china").to_list() if "country" in g.layer]
>>> vlccs = [v.id for v in Vessels().search(vessel_classes="vlcc_plus").to_list()]
>>> cargo_movement_search_result = CargoMovements().search(
... filter_destinations=china,
... filter_activity="loading_state",
... filter_waypoints=suez,
... filter_vessels=vlccs,
... filter_time_min=datetime(2018, 12, 1),
... filter_time_max=datetime(2018, 12, 1))
>>> cols = ['vessels.0.name', 'vessels.0.vessel_class', 'vessels.1.name', 'vessels.1.vessel_class', 'vessels.2.name', 'vessels.2.vessel_class', 'product.group.label', 'quantity']
>>> cargo_movements_df = cargo_movement_search_result.to_df(columns=cols)
```
| | vessels.0.name | vessels.0.vessel_class | vessels.1.name | vessels.1.vessel_class | vessels.2.name | vessels.2.vessel_class | product.group.label | quantity |
|---:|:-----------------|:-------------------------|:-----------------|:-------------------------|:-----------------|:-------------------------|:----------------------|-----------:|
| 0 | MINERVA MARINA | suezmax | COSGLORY LAKE | vlcc_plus | nan | nan | Crude | 700614 |
| 1 | BUKHA | vlcc_plus | nan | nan | nan | nan | Crude | 1896374 |
| 2 | ATHENIAN FREEDOM | vlcc_plus | nan | nan | nan | nan | Crude | 183537 |
| 3 | ATINA | suezmax | DONAT | suezmax | DS VISION | vlcc_plus | Crude | 896773 |
| 4 | MINERVA MARINA | suezmax | COSGLORY LAKE | vlcc_plus | nan | nan | Crude | 405724 |
| 5 | MASAL | suezmax | EKTA | vlcc_plus | nan | nan | Crude | 997896 |
| 6 | ATHENIAN FREEDOM | vlcc_plus | nan | nan | nan | nan | Crude | 120812 |
[Cargo Movements Endpoint Further Documentation](https://docs.vortexa.com/reference/POST/cargo-movements/search)
"""
exclude_params = {
"filter_origins": convert_to_list(exclude_origins),
"filter_destinations": convert_to_list(exclude_destinations),
"filter_products": convert_to_list(exclude_products),
"filter_vessels": convert_to_list(exclude_vessels),
"filter_charterers": convert_to_list(exclude_charterers),
"filter_owners": convert_to_list(exclude_owners),
"filter_vessel_flags": convert_to_list(exclude_vessel_flags),
"filter_vessel_ice_class":
convert_to_list(exclude_vessel_ice_class),
"filter_vessel_propulsion":
convert_to_list(exclude_vessel_propulsion),
}
api_params = {
"filter_activity":
filter_activity,
"filter_time_min":
to_ISODate(filter_time_min),
"filter_time_max":
to_ISODate(filter_time_max),
"timeseries_activity_time_span_min":
timeseries_activity_time_span_min,
"timeseries_activity_time_span_max":
timeseries_activity_time_span_max,
"cm_unit":
cm_unit,
"filter_charterers":
convert_to_list(filter_charterers),
"filter_owners":
convert_to_list(filter_owners),
"filter_products":
convert_to_list(filter_products),
"filter_vessels":
convert_to_list(filter_vessels),
"filter_destinations":
convert_to_list(filter_destinations),
"filter_origins":
convert_to_list(filter_origins),
"filter_storage_locations":
convert_to_list(filter_storage_locations),
"filter_ship_to_ship_locations":
convert_to_list(filter_ship_to_ship_locations),
"filter_waypoints":
convert_to_list(filter_waypoints),
"filter_vessel_age_min":
filter_vessel_age_min,
"filter_vessel_age_max":
filter_vessel_age_max,
"filter_vessel_scrubbers":
filter_vessel_scrubbers,
"filter_vessel_flags":
convert_to_list(filter_vessel_flags),
"filter_vessel_ice_class":
convert_to_list(filter_vessel_ice_class),
"filter_vessel_propulsion":
convert_to_list(filter_vessel_propulsion),
"exclude":
exclude_params,
"disable_geographic_exclusion_rules":
disable_geographic_exclusion_rules,
"size":
self._MAX_PAGE_RESULT_SIZE,
}
return CargoMovementsResult(super().search(**api_params))
def search(
self,
term: Union[str, List[str]] = None,
ids: Union[str, List[str]] = None,
vessel_classes: Union[str, List[str]] = None,
vessel_product_types: Union[ID, List[ID]] = None,
vessel_scrubbers: str = "disabled",
exact_term_match: bool = False,
) -> VesselsResult:
"""
Find all vessels matching given search arguments. Search arguments are combined in an AND manner.
# Arguments
term: The name(s) (or partial name(s)) of a vessel we'd like to search
ids: ID or IDs of vessels we'd like to search
vessel_classes: vessel_class (or list of vessel classes) we'd like to search. Each vessel class must be one of `"tiny_tanker" , "general_purpose" , "handysize" , "handymax" , "panamax", "aframax" , "suezmax" , "vlcc_plus" , "sgc" , "mgc" , "lgc" , "vlgc"`. Refer to [VortexaAPI Vessel Entities](https://docs.vortexa.com/reference/intro-vessel-entities) for the most up-to-date list of vessel classes.
vessel_product_types: A product ID, or list of product IDs to filter on, searching vessels _currently_ carrying these products.
vessel_scrubbers: An optional filter to filter on vessels with or without scrubbers.
To disable the filter (the default behaviour), enter 'disabled'.
To only include vessels with scrubbers, enter 'inc'.
To exclude vessels with scrubbers, enter 'exc'.
exact_term_match: Search on only exact term matches, or allow similar matches.
e.g. When searching for "Ocean" with `exact_term_match=False`, then the SDK will yield vessels named
['Ocean', 'Ocean Wisdom', ...] etc. When `exact_term_match=True`,
the SDK will only yield the vessel named `Ocean`.
# Returns
List of vessels matching the search arguments.
# Examples
- Let's find all the VLCCs with 'ocean' in their name, or related names.
```python
>>> from vortexasdk import Vessels
>>> vessels_df = Vessels().search(vessel_classes='vlcc', term='ocean').to_df(columns=['name', 'imo', 'mmsi', 'related_names'])
```
| | name | imo | mmsi | related_names |
|---:|:-------------|--------:|----------:|:--------------------------|
| 0 | OCEANIS | 9532757 | 241089000 | ['OCEANIS'] |
| 1 | AEGEAN | 9732553 | 205761000 | ['GENER8 OCEANUS'] |
| 2 | OCEANIA | 9246633 | 205753000 | ['OCEANIA'| 'TI OCEANIA'] |
| 3 | ENEOS OCEAN | 9662875 | 432986000 | ['ENEOS OCEAN'] |
| 4 | OCEAN LILY | 9284960 | 477178100 | ['OCEAN LILY'] |
| 5 | SHINYO OCEAN | 9197868 | 636019316 | ['SHINYO OCEAN'] |
| 6 | NASHA | 9079107 | 370497000 | ['OCEANIC'] |
| 7 | HUMANITY | 9180281 | 422204700 | ['OCEAN NYMPH'] |
Note the `term` search also looks for vessels with matching `related_names`
- Let's find all the vessels currently carrying Crude.
```python
>>> from vortexasdk import Vessels, Products
>>> crude = [p.id for p in Products().search(term="crude").to_list() if 'group' in p.layer]
>>> vessels_df = Vessels().search(vessel_product_types=crude).to_df()
```
# Further Documentation
[VortexaAPI Vessel Reference](https://docs.vortexa.com/reference/POST/reference/vessels)
"""
api_params = {
"term": [str(e) for e in convert_to_list(term)],
"ids": convert_to_list(ids),
"vessel_product_types": convert_to_list(vessel_product_types),
"vessel_classes":
[v.lower() for v in convert_to_list(vessel_classes)],
"vessel_scrubbers": vessel_scrubbers,
}
return VesselsResult(super().search(exact_term_match=exact_term_match,
**api_params))
def test_multiple_items_list(self):
self.assertCountEqual(convert_to_list(["a", "b"]), ["a", "b"])
def test_single_item_list(self):
self.assertEqual(convert_to_list("a"), ["a"])
def search(
self,
breakdown_frequency: str = None,
breakdown_unit: str = None,
breakdown_property: str = None,
filter_time_min: datetime = datetime(2019, 10, 1, 0),
filter_time_max: datetime = datetime(2019, 10, 1, 1),
unit: str = "b",
filter_activity: str = None,
filter_charterers: Union[ID, List[ID]] = None,
filter_destinations: Union[ID, List[ID]] = None,
filter_origins: Union[ID, List[ID]] = None,
filter_owners: Union[ID, List[ID]] = None,
filter_products: Union[ID, List[ID]] = None,
filter_vessels: Union[ID, List[ID]] = None,
filter_vessel_classes: Union[ID, List[ID]] = None,
filter_vessel_status: str = None,
filter_ship_to_ship: bool = None,
filter_charterer_exists: bool = None,
filter_vessel_age_min: int = None,
filter_vessel_age_max: int = None,
filter_vessel_dwt_min: int = None,
filter_vessel_dwt_max: int = None,
filter_vessel_scrubbers: str = "disabled",
filter_vessel_flags: Union[ID, List[ID]] = None,
filter_vessel_ice_class: Union[ID, List[ID]] = None,
filter_vessel_propulsion: Union[ID, List[ID]] = None,
exclude_origins: Union[ID, List[ID]] = None,
exclude_destinations: Union[ID, List[ID]] = None,
exclude_products: Union[ID, List[ID]] = None,
exclude_vessels: Union[ID, List[ID]] = None,
exclude_vessel_classes: Union[ID, List[ID]] = None,
exclude_charterers: Union[ID, List[ID]] = None,
exclude_owners: Union[ID, List[ID]] = None,
exclude_vessel_flags: Union[ID, List[ID]] = None,
exclude_vessel_ice_class: Union[ID, List[ID]] = None,
exclude_vessel_propulsion: Union[ID, List[ID]] = None,
) -> BreakdownResult:
"""
Average speed of vessels. For frequencies other than ‘day’, the average daily speed within that period is returned.
# Arguments
breakdown_unit: Must be one of: `'mps'`, `'kmh'`, `'kn'`.
breakdown_frequency: Must be one of: `'day'`, `'week'`, `'doe_week'`, `'month'`, `'quarter'` or `'year'`.
breakdown_property: Property on the vessel movement used to build the value of the aggregation. By default it is “quantity”. Must be one of the following: `'quantity’`, `‘vessel_class’`,
`‘vessel_flag’`, `‘origin_region’`, `‘origin_trading_region’`, `‘origin_trading_sub_region’`, `‘origin_country’`,
`‘origin_port’`, `‘origin_terminal’`, `‘destination_region’`, `‘destination_trading_region’`,
`‘destination_trading_sub_region’`, `‘destination_country’`, `‘destination_port’`, `‘destination_terminal’`,
`'product_group'`, `'product_group_product'`, `'product_category'`, `'product_grade'`.
filter_activity: Movement activity on which to base the time filter. Must be one of: `'loading_state'`,
`'loading_start'`, `'loading_end'`, `'identified_for_loading_state'`, `'unloading_state'`, `'unloading_start'`,
`'unloading_end'`, `'unloaded_state'`, `'storing_state'`, `'storing_start'`, `'storing_end'`, `'transiting_state'`,
`'any_activity'`.
filter_time_min: The UTC start date of the time filter.
filter_time_max: The UTC end date of the time filter.
unit: Unit of measurement. Enter `'b'` for barrels or `'t'` for tonnes.
filter_charterers: A charterer ID, or list of charterer IDs to filter on.
filter_destinations: 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_owners: An corporation ID, or list of corporation 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.
filter_vessel_classes: A vessel class, or list of vessel classes to filter on.
filter_vessel_status: The vessel status on which to base the filter. Enter `'vessel_status_ballast'` for ballast vessels, `'vessel_status_laden_known'` for laden vessels with known cargo (i.e. a type of cargo that Vortexa currently tracks) or `'vessel_status_laden_unknown'` for laden vessels with unknown cargo (i.e. a type of cargo that Vortexa currently does not track).
filter_vessel_age_min: A number between 1 and 100 (representing years).
filter_vessel_age_max: A number between 1 and 100 (representing years).
filter_vessel_dwt_min: A number representing minimum deadweight tonnage of a vessel.
filter_vessel_dwt_max: A number representing maximum deadweight tonnage of a vessel.
filter_vessel_scrubbers: Either inactive `'disabled'`, or included `'inc'` or excluded `'exc'`.
filter_vessel_flags: A geography ID, or list of geography IDs to filter on.
filter_vessel_ice_class: An attribute ID, or list of attribute IDs to filter on.
filter_vessel_propulsion: An attribute ID, or list of attribute IDs to filter on.
exclude_origins: A geography ID, or list of geography IDs to exclude.
exclude_destinations: A geography ID, or list of geography IDs to exclude.
exclude_products: A product ID, or list of product IDs to exclude.
exclude_vessels: A vessel ID, or list of vessel IDs to exclude.
exclude_vessel_classes: A vessel class, or list of vessel classes to exclude.
exclude_charterers: A charterer ID, or list of charterer IDs to exclude.
exclude_owners: An owner ID, or list of owner 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.
exclude_vessel_propulsion: An attribute ID, or list of attribute IDs to exclude.
# Returns
`BreakdownResult`
# Example
_Average daily speed by week and knots, over the last month, from Middle East to China; broken down by vessel class._
```python
>>> from vortexasdk import FleetUtilisationSpeedBreakdown
>>> from datetime import datetime
>>> search_result = FleetUtilisationSpeedBreakdown().search(
... filter_vessel_status="vessel_status_laden_known",
... filter_origins="80aa9e4f3014c3d96559c8e642157edbb2b684ea0144ed76cd20b3af75110877",
... filter_destinations="934c47f36c16a58d68ef5e007e62a23f5f036ee3f3d1f5f85a48c572b90ad8b2",
... filter_time_min=datetime(2020, 12, 19),
... filter_time_max=datetime(2021, 1, 18),
... breakdown_frequency="week",
... breakdown_property="vessel_class",
... breakdown_unit="kn")
>>> df = search_result.to_df()
```
returns
| |key |value |count | breakdown.0.value | breakdown.0.count | breakdown.0.label |
|-----:|:------------------------|:-----------------|-----------------:|------------------:|-------------------:|------------------:|
|0 |2020-12-14 00:00:00+00:00|154.99280077816653|141 | 17.5539329197942 | 3 |'qflex' |
|1 |2020-12-21 00:00:00+00:00|157.30489158419476|143.71428571428572| 17.94667624904423 | 5.142857142857143 |'qmax' |
|2 |2020-12-28 00:00:00+00:00|139.81578683072956|149.28571428571428| 15.522854583046652| 2.857142857142857 |'qflex' |
|3 |2021-01-04 00:00:00+00:00|164.77469345951883|147.85714285714286| 17.22505391874332 | 3.5714285714285716 |'qmax' |
|4 |2021-01-11 00:00:00+00:00|169.1270520125691 |142 | 16.70538969861004 | 2.5714285714285716 |'conventional' |
|5 |2021-01-18 00:00:00+00:00|162.0734332502441 |135 | 17.190140952526683| 3 |'qmax' |
"""
sts_filter = sts_param_value(filter_ship_to_ship)
crossfilters = {
"filter_ship_to_ship": sts_filter["x_filter"],
# if charterer toggle is True, apply cross filter
# else make it false
"filter_charterer_exists": filter_charterer_exists == True
}
exclude_params = {
"filter_origins": convert_to_list(exclude_origins),
"filter_destinations": convert_to_list(exclude_destinations),
"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_charterers),
"filter_owners": convert_to_list(exclude_owners),
"filter_vessel_flags": convert_to_list(exclude_vessel_flags),
"filter_vessel_ice_class": convert_to_list(
exclude_vessel_ice_class
),
"filter_vessel_propulsion": convert_to_list(
exclude_vessel_propulsion
),
"filter_ship_to_ship": sts_filter["exclude"]
}
api_params = {
"breakdown_frequency": breakdown_frequency,
"breakdown_unit": breakdown_unit,
"breakdown_property": breakdown_property,
"filter_activity": filter_activity,
"filter_time_min": to_ISODate(filter_time_min),
"filter_time_max": to_ISODate(filter_time_max),
"unit": unit,
"filter_charterers": convert_to_list(filter_charterers),
"filter_owners": convert_to_list(filter_owners),
"filter_destinations": convert_to_list(filter_destinations),
"filter_origins": convert_to_list(filter_origins),
"filter_products": convert_to_list(filter_products),
"filter_vessels": convert_to_list(filter_vessels),
"filter_vessel_classes": convert_to_list(filter_vessel_classes),
"filter_vessel_status": filter_vessel_status,
"filter_vessel_age_min": filter_vessel_age_min,
"filter_vessel_age_max": filter_vessel_age_max,
"filter_vessel_dwt_min": filter_vessel_dwt_min,
"filter_vessel_dwt_max": filter_vessel_dwt_max,
"filter_vessel_scrubbers": filter_vessel_scrubbers,
"filter_vessel_flags": convert_to_list(filter_vessel_flags),
"filter_vessel_ice_class": convert_to_list(
filter_vessel_ice_class
),
"filter_vessel_propulsion": convert_to_list(
filter_vessel_propulsion
),
"crossfilters": crossfilters,
"exclude": exclude_params
}
return BreakdownResult(super().search(**api_params))
def search(
self,
timeseries_frequency: str = None,
timeseries_property: str = None,
filter_products: Union[ID, List[ID]] = None,
filter_charterers: Union[ID, List[ID]] = None,
filter_owners: Union[ID, List[ID]] = None,
filter_origins: Union[ID, List[ID]] = None,
filter_destinations: Union[ID, List[ID]] = None,
filter_vessels: Union[ID, List[ID]] = None,
filter_vessel_classes: Union[str, List[str]] = None,
filter_vessel_flags: Union[ID, List[ID]] = None,
filter_vessel_ice_class: Union[ID, List[ID]] = None,
filter_vessel_propulsion: Union[ID, List[ID]] = None,
filter_vessel_tags: Union[List[Tag], Tag] = None,
filter_vessel_risk_levels: Union[str, List[str]] = None,
filter_ship_to_ship: bool = None,
filter_charterer_exists: bool = None,
filter_vessel_scrubbers: str = "disabled",
filter_vessel_age_min: int = None,
filter_vessel_age_max: int = None,
filter_vessel_dwt_min: int = None,
filter_vessel_dwt_max: int = None,
filter_activity: str = None,
filter_time_min: datetime = datetime(2019, 10, 1, 0),
filter_time_max: datetime = datetime(2019, 10, 1, 1),
filter_vessel_status: Union[str, List[str]] = None,
exclude_origins: Union[ID, List[ID]] = None,
exclude_destinations: Union[ID, List[ID]] = None,
exclude_products: Union[ID, List[ID]] = None,
exclude_vessels: Union[ID, List[ID]] = None,
exclude_vessel_classes: Union[ID, List[ID]] = None,
exclude_charterers: Union[ID, List[ID]] = None,
exclude_owners: Union[ID, List[ID]] = None,
exclude_vessel_flags: Union[ID, List[ID]] = None,
exclude_vessel_ice_class: Union[ID, List[ID]] = None,
exclude_vessel_propulsion: Union[ID, List[ID]] = None,
exclude_vessel_tags: Union[List[Tag], Tag] = None,
exclude_vessel_risk_levels: Union[ID, List[ID]] = None,
) -> BreakdownResult:
"""
Daily average count of unique vessels. For frequencies other than ‘day’, the values returned are
calculated by summing the average counts per day within the frequency specified, and returning
the average count per day.
# Arguments
timeseries_frequency: Frequency denoting the granularity of the time series. Must be one of the following: ['day', 'week', 'doe_week', 'month', 'quarter', 'year'].
timeseries_property: Property on the vessel movement used to build the value of the aggregation. By default it is “quantity”. Must be one of the following: `'quantity’`, `‘vessel_class’`,
`‘vessel_flag’`, `‘origin_region’`, `‘origin_trading_region’`, `‘origin_trading_sub_region’`, `‘origin_country’`,
`‘origin_port’`, `‘origin_terminal’`, `‘destination_region’`, `‘destination_trading_region’`,
`‘destination_trading_sub_region’`, `‘destination_country’`, `‘destination_port’`, `‘destination_terminal’`,
`'product_group'`, `'product_group_product'`, `'product_category'`, `'product_grade'`.
filter_time_min: The UTC start date of the time filter.
filter_time_max: The UTC end date of the time filter.
filter_products: A product ID, or list of product IDs to filter on.
filter_charterers: A charterer entity ID, or list of product IDs to filter on.
filter_owners: An owner ID, or list of owner IDs to filter on.
filter_origins: 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_vessels: A vessel ID, or list of vessel IDs to filter on.
filter_vessel_classes: A vessel class, or list of vessel classes to filter on.
filter_vessel_flags: A vessel flag ID, or list of vessel flag IDs to filter on.
filter_vessel_ice_class: A vessel ice class ID, or list of vessel ice class IDs to filter on.
filter_vessel_propulsion: A vessel propulsion ID, or list of vessel propulsion IDs to filter on.
filter_vessel_tag: A time bound vessel tag, or list of time bound vessel tags to filter on.
filter_vessel_risk_levels: A vessel risk level, or list of vessel risk levels 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_age_max: A number between 1 and 100 (representing years).
filter_vessel_age_min: A number between 0 and 550000.
filter_vessel_age_max: A number between 0 and 550000.
filter_activity: Movement activity on which to base the time filter. Must be one of: `'loading_state'`,
`'oil_on_water_state'`, `'unloading_state'`, `'ship_to_ship'`, `'storing_state'`, `'transiting_state'`
filter_vessel_status: The vessel status on which to base the filter. Enter 'vessel_status_ballast' for ballast vessels, 'vessel_status_laden_known' for laden vessels with known cargo (i.e. a type of cargo that Vortexa currently tracks) or 'any_activity' for any other vessels.
filter_charterer_exists: A boolean to include or exclude the records to those that have a charterer.
filter_ship_to_ship: A boolean to include or exclude the records to those that are involved in an STS.
exclude_products: A product ID, or list of product IDs to exclude.
exclude_charterers: A charterer entity ID, or list of product IDs to exclude.
exclude_owners: An owner ID, or list of owner IDs to exclude.
exclude_origins: A geography ID, or list of geography IDs to exclude.
exclude_destinations: A geography ID, or list of geography IDs to exclude.
exclude_vessels: A vessel ID, or list of vessel IDs to exclude.
exclude_vessel_classes: A vessel class, or list of vessel classes to exclude.
exclude_vessel_flags: A vessel flag ID, or list of vessel flag IDs to filter on.
exclude_vessel_ice_class: A vessel ice class ID, or list of vessel ice class IDs to exclude.
exclude_vessel_propulsion: A vessel propulsion ID, or list of vessel propulsion IDs to exclude.
exclude_vessel_tags: A time bound vessel tag, or list of time bound vessel tags to exclude.
exclude_vessel_risk_levels: A vessel risk level, or list of vessel risk levels to exclude.
# Returns
`BreakdownResult`
# Example
_Utilisation of laden vessels carrying Crude/Condensate, between Middle East and China over the last 7 days, by vessel_class breakdown._
```python
>>> from vortexasdk import FleetUtilisationTimeseries
>>> from datetime import datetime
>>> search_result = FleetUtilisationTimeseries().search(
... filter_vessel_status="vessel_status_laden_known",
... filter_products="54af755a090118dcf9b0724c9a4e9f14745c26165385ffa7f1445bc768f06f11",
... filter_origins="80aa9e4f3014c3d96559c8e642157edbb2b684ea0144ed76cd20b3af75110877",
... filter_destinations="934c47f36c16a58d68ef5e007e62a23f5f036ee3f3d1f5f85a48c572b90ad8b2",
... filter_time_min=datetime(2021, 1, 11),
... filter_time_max=datetime(2021, 1, 18),
... timeseries_frequency="day",
... timeseries_property="vessel_class")
>>> df = search_result.to_df()
```
Gives the following:
| | key | value | count | breakdown.0.label | breakdown.0.value |breakdown.0.count |
|---:|:-------------------------|----------:|----------:|--------------------:|------------------:|-----------------:|
| 0 | 2021-01-11 00:00:00+00:00| 76 | 76 | "vlcc_plus" | 70 | 70 |
| 1 | 2021-01-12 00:00:00+00:00| 74 | 74 | "vlcc_plus" | 68 | 68 |
| 2 | 2021-01-13 00:00:00+00:00| 76 | 76 | "vlcc_plus" | 69 | 69 |
| 3 | 2021-01-14 00:00:00+00:00| 76 | 76 | "vlcc_plus" | 68 | 68 |
| 4 | 2021-01-15 00:00:00+00:00| 76 | 76 | "vlcc_plus" | 68 | 68 |
| 5 | 2021-01-16 00:00:00+00:00| 76 | 76 | "vlcc_plus" | 68 | 68 |
| 6 | 2021-01-17 00:00:00+00:00| 75 | 75 | "vlcc_plus" | 67 | 67 |
| 7 | 2021-01-18 00:00:00+00:00| 74 | 74 | "vlcc_plus" | 66 | 66 |
"""
sts_filter = sts_param_value(filter_ship_to_ship)
crossfilters = {
"filter_ship_to_ship": sts_filter["x_filter"],
# if charterer toggle is True, apply cross filter
# else make it false
"filter_charterer_exists": filter_charterer_exists == True
}
exclude_params = {
"filter_destinations":
convert_to_list(exclude_destinations),
"filter_products":
convert_to_list(exclude_products),
"filter_vessels":
convert_to_list(exclude_vessels),
"filter_vessel_classes":
convert_to_list(exclude_vessel_classes),
"filter_owners":
convert_to_list(exclude_owners),
"filter_origins":
convert_to_list(exclude_origins),
"filter_charterers":
convert_to_list(exclude_charterers),
"filter_vessel_flags":
convert_to_list(exclude_vessel_flags),
"filter_vessel_ice_class":
convert_to_list(exclude_vessel_ice_class),
"filter_vessel_propulsion":
convert_to_list(exclude_vessel_propulsion),
"filter_vessel_risk_levels":
convert_to_list(exclude_vessel_risk_levels),
"filter_ship_to_ship":
sts_filter["exclude"]
}
api_params = {
"timeseries_frequency": timeseries_frequency,
"timeseries_property": timeseries_property,
"filter_activity": filter_activity,
"filter_time_min": to_ISODate(filter_time_min),
"filter_time_max": to_ISODate(filter_time_max),
"filter_vessel_age_min": filter_vessel_age_min,
"filter_vessel_age_max": filter_vessel_age_max,
"filter_vessel_dwt_min": filter_vessel_dwt_min,
"filter_vessel_dwt_max": filter_vessel_dwt_max,
"filter_vessel_status": convert_to_list(filter_vessel_status),
"filter_charterers": convert_to_list(filter_charterers),
"filter_owners": convert_to_list(filter_owners),
"filter_products": convert_to_list(filter_products),
"filter_vessels": convert_to_list(filter_vessels),
"filter_vessel_classes": convert_to_list(filter_vessel_classes),
"filter_vessel_flags": convert_to_list(filter_vessel_flags),
"filter_destinations": convert_to_list(filter_destinations),
"filter_origins": convert_to_list(filter_origins),
"filter_vessel_ice_class":
convert_to_list(filter_vessel_ice_class),
"filter_vessel_propulsion":
convert_to_list(filter_vessel_propulsion),
"vessel_tags": convert_to_list(filter_vessel_tags),
"vessel_tags_excluded": convert_to_list(exclude_vessel_tags),
"filter_vessel_risk_levels":
convert_to_list(filter_vessel_risk_levels),
"filter_ship_to_ship": filter_ship_to_ship,
"filter_vessel_scrubbers": filter_vessel_scrubbers,
"exclude": exclude_params,
"crossfilters": crossfilters
}
return BreakdownResult(super().search(**api_params))
def search(
self,
breakdown_unit: str = None,
breakdown_size: int = None,
breakdown_geography: str = None,
filter_time_min: datetime = datetime(2019, 10, 1, 0),
filter_time_max: datetime = datetime(2019, 10, 1, 1),
unit: str = "b",
filter_activity: str = None,
filter_charterers: Union[ID, List[ID]] = None,
filter_destinations: Union[ID, List[ID]] = None,
filter_origins: Union[ID, List[ID]] = None,
filter_owners: Union[ID, List[ID]] = None,
filter_products: Union[ID, List[ID]] = None,
filter_vessels: Union[ID, List[ID]] = None,
filter_vessel_classes: Union[str, List[str]] = None,
filter_vessel_status: str = None,
filter_ship_to_ship: bool = None,
filter_charterer_exists: bool = None,
filter_vessel_age_min: int = None,
filter_vessel_age_max: int = None,
filter_vessel_dwt_min: int = None,
filter_vessel_dwt_max: int = None,
filter_vessel_scrubbers: str = "disabled",
filter_vessel_flags: Union[ID, List[ID]] = None,
filter_vessel_ice_class: Union[ID, List[ID]] = None,
filter_vessel_propulsion: Union[ID, List[ID]] = None,
exclude_origins: Union[ID, List[ID]] = None,
exclude_destinations: Union[ID, List[ID]] = None,
exclude_products: Union[ID, List[ID]] = None,
exclude_vessels: Union[ID, List[ID]] = None,
exclude_vessel_classes: Union[str, List[str]] = None,
exclude_charterers: Union[ID, List[ID]] = None,
exclude_owners: Union[ID, List[ID]] = None,
exclude_vessel_flags: Union[ID, List[ID]] = None,
exclude_vessel_ice_class: Union[ID, List[ID]] = None,
exclude_vessel_propulsion: Union[ID, List[ID]] = None
) -> ReferenceBreakdownResult:
"""
Number of unique vessels by destination.
# Arguments
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.
breakdown_geography: Geography hierarchy of the destination to aggregate upon. Must be one of the following: `'berth'`, `'terminal'`, `'port'`,`'country'`, `'shipping_region'`,
`'region'`,`'trading_block'`,`'trading_region'`,`'trading_subregion'`,`'sts_zone'`,`'waypoint'`.
filter_activity: Movement activity on which to base the time filter. Must be one of: `'loading_state'`,
`'loading_start'`, `'loading_end'`, `'identified_for_loading_state'`, `'unloading_state'`, `'unloading_start'`,
`'unloading_end'`, `'unloaded_state'`, `'storing_state'`, `'storing_start'`, `'storing_end'`, `'transiting_state'`,
`'any_activity'`.
filter_time_min: The UTC start date of the time filter.
filter_time_max: The UTC end date of the time filter.
unit: Unit of measurement. Enter `'b'` for barrels or `'t'` for tonnes.
filter_charterers: A charterer ID, or list of charterer IDs to filter on.
filter_destinations: 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_owners: An corporation ID, or list of corporation 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.
filter_vessel_classes: A vessel class, or list of vessel classes to filter on.
filter_vessel_status: The vessel status on which to base the filter. Enter `'vessel_status_ballast'` for ballast vessels, `'vessel_status_laden_known'` for laden vessels with known cargo (i.e. a type of cargo that Vortexa currently tracks) or `'vessel_status_laden_unknown'` for laden vessels with unknown cargo (i.e. a type of cargo that Vortexa currently does not track).
filter_vessel_age_min: A number between 1 and 100 (representing years).
filter_vessel_age_max: A number between 1 and 100 (representing years).
filter_vessel_dwt_min: A number representing minimum deadweight tonnage of a vessel.
filter_vessel_dwt_max: A number representing maximum deadweight tonnage of a vessel.
filter_vessel_scrubbers: Either inactive `'disabled'`, or included `'inc'` or excluded `'exc'`.
filter_vessel_flags: A geography ID, or list of geography IDs to filter on.
filter_vessel_ice_class: An attribute ID, or list of attribute IDs to filter on.
filter_vessel_propulsion: An attribute ID, or list of attribute IDs to filter on.
filter_charterer_exists: A boolean to include or exclude the records to those that have a charterer.
filter_ship_to_ship: A boolean to include or exclude the records to those that are involved in an STS.
exclude_origins: A geography ID, or list of geography IDs to exclude.
exclude_destinations: A geography ID, or list of geography IDs to exclude.
exclude_products: A product ID, or list of product IDs to exclude.
exclude_vessels: A vessel ID, or list of vessel IDs to exclude.
exclude_vessel_classes: A vessel class, or list of vessel classes to exclude.
exclude_charterers: A charterer ID, or list of charterer IDs to exclude.
exclude_owners: An owner ID, or list of owner 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.
exclude_vessel_propulsion: An attribute ID, or list of attribute IDs to exclude.
# Returns
`ReferenceBreakdownResult`
# Example
_Top 5 countries by number of unique vessels by destination country breakdown, in the last quarter._
```python
>>> from vortexasdk import FleetUtilisationDestinationBreakdown, Vessels
>>> from datetime import datetime
>>> search_result = FleetUtilisationDestinationBreakdown().search(
... breakdown_geography='country',
... breakdown_size='5',
... filter_time_min=datetime(2020, 10, 18),
... filter_time_max=datetime(2021, 1, 18))
>>> df = search_result.to_df()
```
returns
| |key | label |value |count |
|-----:|:-----------------------------------------------------------------|:--------------|:-----------|-----:|
|0 | 934c47f36c16a58d68ef5e007e62a23f5f036ee3f3d1f5f85a48c572b90ad8b2 | China |3305 |16226 |
|1 | 50182d9d05051a6c8d24f0514d4ee828da6eaa29eacbb11cfe368f51526328ce | Japan |1248 |10683 |
|2 | 2d92cc08f22524dba59f6a7e340f132a9da0ce9573cca968eb8e3752ef17a963 | United States |2017 |6092 |
|3 | bcd7dddaf951959ebf6076a3a594b426a246d3bffe13339b10d04e45f222e011 | South Korea |1543 |4883 |
|4 | 3267ef2a83a749052c87e981f1bb12c6396acf590b4b1cd3316cf8f8c5aeb7bc | Malaysia |1539 |4495 |
"""
sts_filter = sts_param_value(filter_ship_to_ship)
crossfilters = {
"filter_ship_to_ship": sts_filter["x_filter"],
# if charterer toggle is True, apply cross filter
# else make it false
"filter_charterer_exists": filter_charterer_exists == True
}
exclude_params = {
"filter_origins": convert_to_list(exclude_origins),
"filter_destinations": convert_to_list(exclude_destinations),
"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_charterers),
"filter_owners": convert_to_list(exclude_owners),
"filter_vessel_flags": convert_to_list(exclude_vessel_flags),
"filter_vessel_ice_class":
convert_to_list(exclude_vessel_ice_class),
"filter_vessel_propulsion":
convert_to_list(exclude_vessel_propulsion),
}
api_params = {
"breakdown_unit": breakdown_unit,
"breakdown_size": breakdown_size,
"breakdown_geography": breakdown_geography,
"filter_activity": filter_activity,
"filter_time_min": to_ISODate(filter_time_min),
"filter_time_max": to_ISODate(filter_time_max),
"unit": unit,
"filter_charterers": convert_to_list(filter_charterers),
"filter_owners": convert_to_list(filter_owners),
"filter_destinations": convert_to_list(filter_destinations),
"filter_origins": convert_to_list(filter_origins),
"filter_products": convert_to_list(filter_products),
"filter_vessels": convert_to_list(filter_vessels),
"filter_vessel_classes": convert_to_list(filter_vessel_classes),
"filter_vessel_status": filter_vessel_status,
"filter_vessel_age_min": filter_vessel_age_min,
"filter_vessel_age_max": filter_vessel_age_max,
"filter_vessel_dwt_min": filter_vessel_dwt_min,
"filter_vessel_dwt_max": filter_vessel_dwt_max,
"filter_vessel_scrubbers": filter_vessel_scrubbers,
"filter_vessel_flags": convert_to_list(filter_vessel_flags),
"filter_vessel_ice_class":
convert_to_list(filter_vessel_ice_class),
"filter_vessel_propulsion":
convert_to_list(filter_vessel_propulsion),
"crossfilters": crossfilters,
"exclude": exclude_params
}
return ReferenceBreakdownResult(super().search(
response_type="breakdown", **api_params))
def search(
self,
filter_activity: str,
timeseries_activity: str = None,
timeseries_frequency: str = "day",
timeseries_unit: str = "b",
filter_time_min: datetime = datetime(2019, 10, 1, 0),
filter_time_max: datetime = datetime(2019, 10, 1, 1),
filter_charterers: Union[str, List[str]] = None,
filter_destinations: Union[str, List[str]] = None,
filter_origins: Union[str, List[str]] = None,
filter_owners: Union[str, List[str]] = None,
filter_products: Union[str, List[str]] = None,
filter_vessels: Union[str, List[str]] = None,
filter_storage_locations: Union[str, List[str]] = None,
filter_ship_to_ship_locations: Union[str, List[str]] = None,
filter_waypoints: Union[str, List[str]] = None,
disable_geographic_exclusion_rules: bool = None,
timeseries_activity_time_span_min: int = None,
timeseries_activity_time_span_max: int = None,
) -> TimeSeriesResult:
"""
Find Aggregate flows between regions, for various products, for various vessels, or various corporations.
Example questions that can be answered with this endpoint:
* _How many Crude/Condensate barrels have been imported into China each day over the last year?_
* _How many tonnes of Fuel Oil has company X exported from the United States each week over the last 2 years?_
* _How have long-term Medium-Sour floating storage levels changed over time?_
# Arguments
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_max: The UTC end date of the time filter.
filter_corporations: A corporation ID, or list of corporation IDs to filter on.
filter_destinations: 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_owners: An owner ID, or list of owner 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.
filter_storage_locations: 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_waypoints: A geography ID, or list of geography IDs to filter on.
disable_geographic_exclusion_rules: This controls a popular industry term "intra-movements" and determines
the filter behaviour for cargo leaving then entering the same geographic area.
timeseries_activity: The cargo movement activity we want to aggregate on. This param defaults to
`filter_activity` if left blank. For example, Let's say we want to aggregate the unloading timestamps of
all cargo movements that loaded in 2019, then we'd use `filter_time_min` and `filter_time_max` to specify
1st Jan 2019 and 31st Dec 2019 respectively, we'd set `filter_activity='loading_state'` and
`timeseries_activity='unloading_state'` to filter on loadings but aggregate on unloadings.
`filter_activity` 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'].
timeseries_frequency: Frequency denoting the granularity of the time series. Must be one of ['day', 'week',
'doe_week', 'month', 'quarter', 'year']
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,
cargo movement count, cargo movement count per day, respectively.
timeseries_activity_time_span_min: The minimum amount of time in milliseconds accounted for in a time series
activity. Can be used to request long-term floating storage. For example, to only return floating storage
movements that occurred for _more_ than 14 days enter
`timeseries_activity_time_span_min=1000 * 60 * 60 * 24 * 14` in conjunction with
`filter_activity='storing_state'`.
timeseries_activity_time_span_max: The maximum amount of time in milliseconds accounted for in a time series
activity. Can be used to request short-term floating storage. For example, to only return floating storage
movements that occurred for _less_ than 14 days enter
`timeseries_activity_time_span_max=1000 * 60 * 60 * 24 * 14` in conjunction with
`filter_activity='storing_state'`.
# Returns
`TimeSeriesResult`
# Example
* _What was the monthly average barrels per day of crude loaded from Rotterdam over the last year?_
```python
>>> from vortexasdk import CargoTimeSeries, Geographies, Products
>>> rotterdam = [g.id for g in Geographies().search("rotterdam").to_list() if "port" in g.layer]
>>> crude = [p.id for p in Products().search("crude").to_list() if "Crude" == p.name]
>>> search_result = CargoTimeSeries().search(
... timeseries_unit='bpd',
... timeseries_frequency='month',
... filter_origins=rotterdam,
... filter_products=crude,
... filter_activity='loading_state',
... filter_time_min=datetime(2018, 1, 1),
... filter_time_max=datetime(2018, 12, 31))
>>> df = search_result.to_df()
```
Gives the following:
| | key | count | value |
|---:|:-------------------------|----------:|----------:|
| 0 | 2018-01-01T00:00:00.000Z | 0.354839 | 458665 |
| 1 | 2018-02-01T00:00:00.000Z | 0.75 | 45024 |
| 2 | 2018-03-01T00:00:00.000Z | 0.0645161 | 35663.5 |
| 3 | 2018-04-01T00:00:00.000Z | 0.878777 | 12345.2 |
| 4 | 2018-05-01T00:00:00.000Z | 0.455932 | 9999.32 |
| 5 | 2018-06-01T00:00:00.000Z | 0.777667 | 12234.8 |
| 6 | 2018-07-01T00:00:00.000Z | 0.555097 | 987666 |
| 7 | 2018-08-01T00:00:00.000Z | 0.290323 | 5318008.1 |
| 8 | 2018-09-01T00:00:00.000Z | 0.0333333 | 686888.87 |
| 9 | 2018-10-01T00:00:00.000Z | 0.354839 | 234344 |
| 10 | 2018-11-01T00:00:00.000Z | 0.2345 | 111111 |
| 11 | 2018-12-01T00:00:00.000Z | 0.123129 | 34344.5 |
"""
api_params = {
"filter_activity":
filter_activity,
"filter_time_min":
to_ISODate(filter_time_min),
"filter_time_max":
to_ISODate(filter_time_max),
"timeseries_activity_time_span_min":
timeseries_activity_time_span_min,
"timeseries_activity_time_span_max":
timeseries_activity_time_span_max,
"filter_charterers":
convert_to_list(filter_charterers),
"filter_owners":
convert_to_list(filter_owners),
"filter_products":
convert_to_list(filter_products),
"filter_vessels":
convert_to_list(filter_vessels),
"filter_destinations":
convert_to_list(filter_destinations),
"filter_origins":
convert_to_list(filter_origins),
"filter_storage_locations":
convert_to_list(filter_storage_locations),
"filter_ship_to_ship_locations":
convert_to_list(filter_ship_to_ship_locations),
"filter_waypoints":
convert_to_list(filter_waypoints),
"disable_geographic_exclusion_rules":
disable_geographic_exclusion_rules,
"timeseries_frequency":
timeseries_frequency,
"timeseries_unit":
timeseries_unit,
"timeseries_activity":
timeseries_activity or filter_activity,
"size":
self._MAX_PAGE_RESULT_SIZE,
}
return TimeSeriesResult(super().search(**api_params))
def search(
self,
filter_region: str = None,
filter_port: str = None,
use_reference_port: bool = None,
filter_products: Union[ID, List[ID]] = None,
filter_vessels: Union[ID, List[ID]] = None,
filter_vessel_classes: Union[str, List[str]] = None,
filter_vessel_status: str = None,
filter_vessel_location: Union[ID, List[ID]] = None,
filter_owners: Union[ID, List[ID]] = None,
filter_destination: Union[ID, List[ID]] = None,
filter_days_to_arrival: List[Dict[str,int]] = None,
filter_vessel_dwt_min: int = None,
filter_vessel_dwt_max: int = None,
filter_vessel_age_min: int = None,
filter_vessel_age_max: int = None,
filter_vessel_idle_min: int = None,
filter_vessel_idle_max: int = None,
filter_vessel_scrubbers: str = "disabled",
filter_recent_visits: str = None,
exclude_products: Union[ID, List[ID]] = None,
exclude_vessels: Union[ID, List[ID]] = None,
exclude_vessel_classes: Union[str, List[str]] = None,
exclude_vessel_status: str = None,
exclude_vessel_location: Union[ID, List[ID]] = None,
exclude_owners: Union[ID, List[ID]] = None,
exclude_destination: Union[ID, List[ID]] = None,
offset: int = None,
order: str = None,
order_direction: str = None,
) -> VesselAvailabilityResult:
"""
List of vessels that can be available to load a given cargo at a given port on a future date.
# Arguments
order: Used to sort the returned results. Must be one of the following: [‘vessel_status’,
‘days_to_arrival’, ‘days_idle’].
order_direction: Determines the direction of sorting. ‘asc’ for ascending, ‘desc’ for
descending.
offset: Used to page results. The offset from which records should be returned.
size: Used to page results. The size of the result set. Between 0 and 500.
filter_owners: An corporation ID, or list of corporation IDs to filter on.
filter_destination: 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_vessels: A vessel ID, or list of vessel IDs to filter on.
filter_vessel_classes: A vessel class, or list of vessel classes to filter on.
filter_vessel_status: The vessel status on which to base the filter. Enter 'vessel_status_ballast' for ballast vessels, 'vessel_status_laden_known' for laden vessels with known cargo (i.e. a type of cargo that Vortexa currently tracks) or 'any_activity' for any other vessels
filter_vessel_location: A location ID, or list of location IDs to filter on.
filter_port: Filter by port ID.
filter_region: Filter by region ID - takes precedence over filter_port if provided. This should be used in conjunction with `use_reference_port`
filter_days_to_arrival: Filter availability by time to arrival in days`
use_reference_port: If this flag is enabled, we will return data for
the reference port instead of the user selected one,
filter_vessel_age_min: A number between 1 and 100 (representing years).
filter_vessel_age_max: A number between 1 and 100 (representing years).
filter_vessel_idle_min: A number greater than 0 (representing idle days).
filter_vessel_idle_max: A number greater than 0 and filter_vessel_idle_min (representing idle days).
filter_vessel_dwt_min: A number between 0 and 550000.
filter_vessel_dwt_max: A number between 0 and 550000.
filter_vessel_scrubbers: Either inactive 'disabled', or included 'inc' or excluded 'exc'.
filter_recent_visits: Filter availability by each vessel's recent visits
exclude_products: A product ID, or list of product IDs to exclude.
exclude_vessels: A vessel ID, or list of vessel IDs to exclude.
exclude_vessel_classes: A vessel class, or list of vessel classes to exclude.
exclude_vessel_status: The vessel status on which to base the filter. Enter 'vessel_status_ballast' for ballast vessels, 'vessel_status_laden_known' for laden vessels with known cargo (i.e. a type of cargo that Vortexa currently tracks) or 'any_activity' for any other vessels
exclude_owners: An owner ID, or list of owner IDs to exclude.
exclude_vessel_location: A location ID, or list of location IDs to filter on.
exclude_destination: A location ID, or list of location IDs to filter on.
# Returns
`VesselAvailabilityResult`
# Example
Top 2 available vessels arriving at Rotterdam port in the next 5 days.
```python
>>> from vortexasdk import VesselAvailabilitySearch, Geographies
>>> rotterdam = "68faf65af1345067f11dc6723b8da32f00e304a6f33c000118fccd81947deb4e"
>>> df = VesselAvailabilitySearch().search(
... filter_port=rotterdam,
... filter_days_to_arrival={"min": 0, "max": 35}
... ).to_df(columns=['available_at','vessel_name','vessel_class']).head(2)
```
| | available_at | vessel_name | vessel_class |
|---:|:-------------------------|:-------------------------|-------------:|
| 0 | 2017-09-30 15:30:27+00:00| STAR RIVER | handysize |
| 1 | 2017-08-29 14:51:32+00:00| AMALTHEA | aframax |
"""
exclude_params = {
"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_owners": convert_to_list(exclude_owners),
"filter_vessel_status": convert_to_list(exclude_vessel_status),
"filter_vessel_location": convert_to_list(
exclude_vessel_location
),
}
api_params = {
"filter_products": convert_to_list(filter_products),
"filter_vessels": convert_to_list(filter_vessels),
"filter_vessel_classes": convert_to_list(
filter_vessel_classes
),
"filter_vessel_status": filter_vessel_status,
"filter_vessel_location": convert_to_list(filter_vessel_location),
"filter_owners": convert_to_list(filter_owners),
"filter_destination": convert_to_list(filter_destination),
"filter_region": filter_region,
"filter_port": filter_port,
"use_reference_port": use_reference_port,
"filter_days_to_arrival": convert_to_list(
filter_days_to_arrival
),
"filter_vessel_dwt_min": filter_vessel_dwt_min,
"filter_vessel_dwt_max": filter_vessel_dwt_max,
"filter_vessel_age_min": filter_vessel_age_min,
"filter_vessel_age_max": filter_vessel_age_max,
"filter_vessel_idle_min": filter_vessel_idle_min,
"filter_vessel_idle_max": filter_vessel_idle_max,
"filter_vessel_scrubbers": filter_vessel_scrubbers,
"filter_recent_visits": filter_recent_visits,
"exclude": exclude_params,
"offset": offset,
"order": order,
"order_direction": order_direction,
"size": self._MAX_PAGE_RESULT_SIZE,
}
return VesselAvailabilityResult(super().search(**api_params))
def search(
self,
breakdown_geography: str = "country",
breakdown_unit_average_basis: str = None,
filter_activity: str = "any_activity",
breakdown_unit: str = "b",
disable_geographic_exclusion_rules: bool = None,
breakdown_size: int = None,
filter_time_min: datetime = datetime(2019, 10, 1, 0),
filter_time_max: datetime = datetime(2019, 10, 1, 1),
filter_products: Union[ID, List[ID]] = None,
filter_charterers: Union[ID, List[ID]] = None,
filter_vessels: Union[ID, List[ID]] = None,
filter_vessel_classes: Union[str, List[str]] = None,
filter_owners: Union[ID, List[ID]] = None,
filter_vessel_flags: Union[ID, List[ID]] = None,
filter_vessel_ice_class: Union[ID, List[ID]] = None,
filter_vessel_propulsion: Union[ID, List[ID]] = None,
filter_origins: Union[ID, List[ID]] = None,
filter_destinations: Union[ID, List[ID]] = None,
filter_storage_locations: Union[ID, List[ID]] = None,
filter_waypoints: Union[ID, List[ID]] = None,
filter_ship_to_ship_locations: Union[ID, List[ID]] = None,
filter_vessel_age_min: int = None,
filter_vessel_age_max: int = None,
filter_vessel_scrubbers: str = "disabled",
filter_vessel_tags: Union[List[Tag], Tag] = None,
exclude_products: Union[ID, List[ID]] = None,
exclude_vessels: Union[ID, List[ID]] = None,
exclude_vessel_classes: Union[str, List[str]] = None,
exclude_owners: Union[ID, List[ID]] = None,
exclude_charterers: Union[ID, List[ID]] = None,
exclude_vessel_flags: Union[ID, List[ID]] = None,
exclude_destinations: Union[ID, List[ID]] = None,
exclude_origins: Union[ID, List[ID]] = None,
exclude_waypoints: Union[ID, List[ID]] = None,
exclude_storage_locations: Union[ID, List[ID]] = None,
exclude_ship_to_ship_locations: Union[ID, List[ID]] = None,
exclude_vessel_ice_class: Union[ID, List[ID]] = None,
exclude_vessel_propulsion: Union[ID, List[ID]] = None,
exclude_vessel_tags: Union[List[Tag], Tag] = None,
) -> ReferenceBreakdownResult:
"""
Origin locations breakdown aggregation by geographic area
# 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: Units to aggregate upon. Must be one of the following: `'b'`, `'t'`, `'cbm'`, `'bpd'`, `'tpd'`, `'mpd'`.
breakdown_geography: Geography hierarchy of the origin to aggregate upon. Must be one of the following: `'terminal'`, `'port'`,`'country'`, `'shipping_region'`,
`'region'`,`'trading_block'`,`'trading_region'`,`'trading_subregion'`,`'sts_zone'`,`'waypoint'`.
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.
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_max: The UTC end date of the time filter.
filter_owners: An corporation ID, or list of corporation 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_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_origins: 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_storage_locations: 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_ship_to_ship_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_vessels: A vessel ID, or list of vessel IDs to filter on.
filter_vessel_classes: A vessel class, or list of vessel classes to filter on.
filter_vessel_age_min: A number between 1 and 100 (representing years).
filter_vessel_age_max: A number between 1 and 100 (representing years).
filter_vessel_scrubbers: Either inactive 'disabled', or included 'inc' or excluded 'exc'.
filter_vessel_tags: A time bound vessel tag, or list of time bound vessel tags to filter on.
exclude_products: A product ID, or list of product IDs to exclude.
exclude_vessel_flags: A vessel flag ID, or list of vessel flag IDs to exclude.
exclude_vessel_ice_class: An ice class ID, or list of ice class IDs to exclude.
exclude_vessel_propulsion: An propulsion means ID, or list of propulsion means IDs to exclude.
exclude_vessels: A vessel ID, or list of vessel IDs to exclude.
exclude_vessel_classes: A vessel class, or list of vessel classes to exclude.
exclude_owners: An owner ID, or list of owner IDs to exclude.
exclude_vessel_location: A location ID, or list of location IDs to exclude.
exclude_destinations: A location ID, or list of location IDs to exclude.
exclude_origins: A location ID, or list of location IDs to exclude.
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.
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 |
"""
exclude_params = {
"filter_destinations": convert_to_list(exclude_destinations),
"filter_products": convert_to_list(exclude_products),
"filter_vessels": convert_to_list(exclude_vessels),
"filter_charterers": convert_to_list(exclude_charterers),
"filter_vessel_classes": convert_to_list(exclude_vessel_classes),
"filter_owners": convert_to_list(exclude_owners),
"filter_origins": convert_to_list(exclude_origins),
"filter_flags": convert_to_list(exclude_vessel_flags),
"filter_vessel_ice_class":
convert_to_list(exclude_vessel_ice_class),
"filter_vessel_propulsion":
convert_to_list(exclude_vessel_propulsion),
"filter_storage_locations":
convert_to_list(exclude_storage_locations),
"filter_waypoints": convert_to_list(exclude_waypoints),
"filter_ship_to_ship":
convert_to_list(exclude_ship_to_ship_locations),
}
api_params = {
"breakdown_unit_average_basis":
breakdown_unit_average_basis,
"breakdown_unit":
breakdown_unit,
"breakdown_size":
breakdown_size,
"breakdown_geography":
breakdown_geography,
"disable_geographic_exclusion_rules":
disable_geographic_exclusion_rules,
"filter_time_min":
to_ISODate(filter_time_min),
"filter_time_max":
to_ISODate(filter_time_max),
"filter_activity":
filter_activity,
"filter_products":
convert_to_list(filter_products),
"filter_charterers":
convert_to_list(filter_charterers),
"filter_vessels":
convert_to_list(filter_vessels),
"filter_vessel_classes":
convert_to_list(filter_vessel_classes),
"filter_vessel_flags":
convert_to_list(filter_vessel_flags),
"filter_vessel_ice_class":
convert_to_list(filter_vessel_ice_class),
"filter_vessel_propulsion":
convert_to_list(filter_vessel_propulsion),
"filter_owners":
convert_to_list(filter_owners),
"filter_destinations":
convert_to_list(filter_destinations),
"filter_origins":
convert_to_list(filter_origins),
"filter_waypoints":
convert_to_list(filter_waypoints),
"filter_charterers":
convert_to_list(filter_charterers),
"filter_storage_locations":
convert_to_list(filter_storage_locations),
"filter_ship_to_ship_locations":
convert_to_list(filter_ship_to_ship_locations),
"filter_vessel_age_min":
filter_vessel_age_min,
"filter_vessel_age_max":
filter_vessel_age_max,
"filter_vessel_scrubbers":
filter_vessel_scrubbers,
"vessel_tags":
convert_to_list(filter_vessel_tags),
"vessel_tags_excluded":
convert_to_list(exclude_vessel_tags),
"exclude":
exclude_params,
"include_reference":
self._INCLUDE_REFERENCE_DATA,
}
return ReferenceBreakdownResult(super().search(
response_type="breakdown", **api_params))
def search(
self,
breakdown_frequency: str = None,
filter_time_min: datetime = datetime(2019, 10, 1, 0),
filter_time_max: datetime = datetime(2019, 10, 1, 1),
unit: str = "b",
filter_activity: str = None,
filter_charterers: Union[ID, List[ID]] = None,
filter_destinations: Union[ID, List[ID]] = None,
filter_origins: Union[ID, List[ID]] = None,
filter_owners: Union[ID, List[ID]] = None,
filter_products: Union[ID, List[ID]] = None,
filter_vessels: Union[ID, List[ID]] = None,
filter_vessel_classes: Union[ID, List[ID]] = None,
filter_vessel_status: str = None,
filter_vessel_age_min: int = None,
filter_vessel_age_max: int = None,
filter_vessel_dwt_min: int = None,
filter_vessel_dwt_max: int = None,
filter_vessel_scrubbers: str = "disabled",
filter_vessel_flags: Union[ID, List[ID]] = None,
filter_vessel_ice_class: Union[ID, List[ID]] = None,
filter_vessel_propulsion: Union[ID, List[ID]] = None,
exclude_origins: Union[ID, List[ID]] = None,
exclude_destinations: Union[ID, List[ID]] = None,
exclude_products: Union[ID, List[ID]] = None,
exclude_vessels: Union[ID, List[ID]] = None,
exclude_vessel_classes: Union[ID, List[ID]] = None,
exclude_charterers: Union[ID, List[ID]] = None,
exclude_owners: Union[ID, List[ID]] = None,
exclude_vessel_flags: Union[ID, List[ID]] = None,
exclude_vessel_ice_class: Union[ID, List[ID]] = None,
exclude_vessel_propulsion: Union[ID, List[ID]] = None,
) -> TimeSeriesResult:
"""
Find TonMilesBreakdown matching the given search parameters.
# Arguments
breakdown_frequency: Must be one of: `'day'`, `'week'`, `'doe_week'`, `'month'`, `'quarter'` or `'year'`.
filter_activity: Movement activity on which to base the time filter. Must be one of: `'loading_state'`,
`'loading_start'`, `'loading_end'`, `'identified_for_loading_state'`, `'unloading_state'`, `'unloading_start'`,
`'unloading_end'`, `'unloaded_state'`, `'storing_state'`, `'storing_start'`, `'storing_end'`, `'transiting_state'`,
`'any_activity'`.
filter_time_min: The UTC start date of the time filter.
filter_time_max: The UTC end date of the time filter.
unit: Unit of measurement. Enter `'b'` for barrels or `'t'` for tonnes.
filter_charterers: A charterer ID, or list of charterer IDs to filter on.
filter_destinations: 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_owners: An corporation ID, or list of corporation 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.
filter_vessel_classes: A vessel class, or list of vessel classes to filter on.
filter_vessel_status: The vessel status on which to base the filter. Enter `'vessel_status_ballast'` for ballast vessels, `'vessel_status_laden_known'` for laden vessels with known cargo (i.e. a type of cargo that Vortexa currently tracks) or `'vessel_status_laden_unknown'` for laden vessels with unknown cargo (i.e. a type of cargo that Vortexa currently does not track).
filter_vessel_age_min: A number between 1 and 100 (representing years).
filter_vessel_age_max: A number between 1 and 100 (representing years).
filter_vessel_dwt_min: A number representing minimum deadweight tonnage of a vessel.
filter_vessel_dwt_max: A number representing maximum deadweight tonnage of a vessel.
filter_vessel_scrubbers: Either inactive `'disabled'`, or included `'inc'` or excluded `'exc'`.
filter_vessel_flags: A geography ID, or list of geography IDs to filter on.
filter_vessel_ice_class: An attribute ID, or list of attribute IDs to filter on.
filter_vessel_propulsion: An attribute ID, or list of attribute IDs to filter on.
exclude_origins: A geography ID, or list of geography IDs to exclude.
exclude_destinations: A geography ID, or list of geography IDs to exclude.
exclude_products: A product ID, or list of product IDs to exclude.
exclude_vessels: A vessel ID, or list of vessel IDs to exclude.
exclude_vessel_classes: A vessel class, or list of vessel classes to exclude.
exclude_charterers: A charterer ID, or list of charterer IDs to exclude.
exclude_owners: An owner ID, or list of owner 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.
exclude_vessel_propulsion: An attribute ID, or list of attribute IDs to exclude.
# Returns
`TimeSeriesResult`
# Example
```python
>>> from vortexasdk import TonMilesBreakdown, Vessels
>>> from datetime import datetime
>>> new_wisdom = [g.id for g in Vessels().search("NEW WISDOM").to_list()]
>>> search_result = TonMilesBreakdown().search(
... unit='b',
... breakdown_frequency='month',
... filter_vessels=new_wisdom,
... filter_time_min=datetime(2018, 1, 1),
... filter_time_max=datetime(2018, 12, 31))
>>> df = search_result.to_df()
```
returns
| |key |value |count |
|-----:|:------------------------|:-----------|-----:|
|0 |2018-01-01 00:00:00+00:00|4.558499e+07|1 |
|1 |2018-02-01 00:00:00+00:00|4.393985e+07|1 |
|2 |2018-03-01 00:00:00+00:00|7.781776e+06|1 |
|3 |2018-04-01 00:00:00+00:00|8.041169e+07|1 |
|4 |2018-05-01 00:00:00+00:00|3.346161e+07|1 |
|5 |2018-06-01 00:00:00+00:00|5.731648e+07|1 |
|6 |2018-07-01 00:00:00+00:00|4.976054e+07|1 |
|7 |2018-08-01 00:00:00+00:00|3.022656e+06|1 |
|8 |2018-09-01 00:00:00+00:00|2.504909e+07|1 |
|9 |2018-10-01 00:00:00+00:00|6.269583e+07|1 |
|10 |2018-11-01 00:00:00+00:00|1.823642e+07|1 |
|11 |2018-12-01 00:00:00+00:00|3.137448e+07|1 |
"""
exclude_params = {
"filter_origins": convert_to_list(exclude_origins),
"filter_destinations": convert_to_list(exclude_destinations),
"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_charterers),
"filter_owners": convert_to_list(exclude_owners),
"filter_vessel_flags": convert_to_list(exclude_vessel_flags),
"filter_vessel_ice_class":
convert_to_list(exclude_vessel_ice_class),
"filter_vessel_propulsion":
convert_to_list(exclude_vessel_propulsion),
}
api_params = {
"breakdown_frequency": breakdown_frequency,
"filter_activity": filter_activity,
"filter_time_min": to_ISODate(filter_time_min),
"filter_time_max": to_ISODate(filter_time_max),
"unit": unit,
"filter_charterers": convert_to_list(filter_charterers),
"filter_owners": convert_to_list(filter_owners),
"filter_destinations": convert_to_list(filter_destinations),
"filter_origins": convert_to_list(filter_origins),
"filter_products": convert_to_list(filter_products),
"filter_vessels": convert_to_list(filter_vessels),
"filter_vessel_classes": convert_to_list(filter_vessel_classes),
"filter_vessel_status": filter_vessel_status,
"filter_vessel_age_min": filter_vessel_age_min,
"filter_vessel_age_max": filter_vessel_age_max,
"filter_vessel_dwt_min": filter_vessel_dwt_min,
"filter_vessel_dwt_max": filter_vessel_dwt_max,
"filter_vessel_scrubbers": filter_vessel_scrubbers,
"filter_vessel_flags": convert_to_list(filter_vessel_flags),
"filter_vessel_ice_class":
convert_to_list(filter_vessel_ice_class),
"filter_vessel_propulsion":
convert_to_list(filter_vessel_propulsion),
"exclude": exclude_params,
}
return TimeSeriesResult(super().search(**api_params))
def search(
self,
timeseries_frequency: str = None,
timeseries_property: str = None,
filter_time_min: datetime = datetime(2019, 10, 1, 0),
filter_time_max: datetime = datetime(2019, 10, 1, 1),
filter_products: Union[ID, List[ID]] = None,
filter_charterers: Union[ID, List[ID]] = None,
filter_owners: Union[ID, List[ID]] = None,
filter_origins: Union[ID, List[ID]] = None,
filter_destinations: Union[ID, List[ID]] = None,
filter_vessels: Union[ID, List[ID]] = None,
filter_vessel_classes: Union[str, List[str]] = None,
filter_vessel_flags: Union[ID, List[ID]] = None,
filter_vessel_ice_class: Union[ID, List[ID]] = None,
filter_vessel_propulsion: Union[ID, List[ID]] = None,
filter_vessel_tags: Union[List[Tag], Tag] = None,
filter_vessel_risk_levels: Union[str, List[str]] = None,
filter_vessel_scrubbers: str = "disabled",
filter_ship_to_ship: bool = None,
filter_charterer_exists: bool = None,
filter_vessel_age_min: int = None,
filter_vessel_age_max: int = None,
filter_vessel_dwt_min: int = None,
filter_vessel_dwt_max: int = None,
filter_activity: str = None,
filter_vessel_status: Union[str, List[str]] = None,
exclude_origins: Union[ID, List[ID]] = None,
exclude_destinations: Union[ID, List[ID]] = None,
exclude_products: Union[ID, List[ID]] = None,
exclude_vessels: Union[ID, List[ID]] = None,
exclude_vessel_classes: Union[ID, List[ID]] = None,
exclude_charterers: Union[ID, List[ID]] = None,
exclude_owners: Union[ID, List[ID]] = None,
exclude_vessel_flags: Union[ID, List[ID]] = None,
exclude_vessel_ice_class: Union[ID, List[ID]] = None,
exclude_vessel_propulsion: Union[ID, List[ID]] = None,
exclude_vessel_tags: Union[List[Tag], Tag] = None,
exclude_vessel_risk_levels: Union[ID, List[ID]] = None,
) -> BreakdownResult:
"""
Sum of the dead weight tonnage for all unique vessels for each day. For frequencies other than
‘day’, the values returned are calculated by summing each daily DWT bucket and returning the
total.
# Arguments
timeseries_frequency: Frequency denoting the granularity of the time series. Must be one of the following: ['day', 'week', 'doe_week', 'month', 'quarter', 'year'].
timeseries_property: Property on the vessel movement used to build the value of the aggregation. By default it is “quantity”. Must be one of the following: `'quantity’`, `‘vessel_class’`,
`‘vessel_flag’`, `‘origin_region’`, `‘origin_trading_region’`, `‘origin_trading_sub_region’`, `‘origin_country’`,
`‘origin_port’`, `‘origin_terminal’`, `‘destination_region’`, `‘destination_trading_region’`,
`‘destination_trading_sub_region’`, `‘destination_country’`, `‘destination_port’`, `‘destination_terminal’`,
`'product_group'`, `'product_group_product'`, `'product_category'`, `'product_grade'`.
filter_time_min: The UTC start date of the time filter.
filter_time_max: The UTC end date of the time filter.
filter_products: A product ID, or list of product IDs to filter on.
filter_charterers: A charterer entity ID, or list of product IDs to filter on.
filter_owners: An owner ID, or list of owner IDs to filter on.
filter_origins: 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_vessels: A vessel ID, or list of vessel IDs to filter on.
filter_vessel_classes: A vessel class, or list of vessel classes to filter on.
filter_vessel_flags: A vessel flag ID, or list of vessel flag IDs to filter on.
filter_vessel_ice_class: A vessel ice class ID, or list of vessel ice class IDs to filter on.
filter_vessel_propulsion: A vessel propulsion ID, or list of vessel propulsion IDs to filter on.
filter_vessel_tag: A time bound vessel tag, or list of time bound vessel tags to filter on.
filter_vessel_risk_levels: A vessel risk level, or list of vessel risk levels 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_age_max: A number between 1 and 100 (representing years).
filter_vessel_age_min: A number between 0 and 550000.
filter_vessel_age_max: A number between 0 and 550000.
filter_activity: Movement activity on which to base the time filter. Must be one of: `'loading_state'`,
`'oil_on_water_state'`, `'unloading_state'`, `'ship_to_ship'`, `'storing_state'`, `'transiting_state'`
filter_vessel_status: The vessel status on which to base the filter. Enter 'vessel_status_ballast' for ballast vessels, 'vessel_status_laden_known' for laden vessels with known cargo (i.e. a type of cargo that Vortexa currently tracks) or 'any_activity' for any other vessels.
filter_charterer_exists: A boolean to include or exclude the records to those that have a charterer.
filter_ship_to_ship: A boolean to include or exclude the records to those that are involved in an STS.
exclude_products: A product ID, or list of product IDs to exclude.
exclude_charterers: A charterer entity ID, or list of product IDs to exclude.
exclude_owners: An owner ID, or list of owner IDs to exclude.
exclude_origins: A geography ID, or list of geography IDs to exclude.
exclude_destinations: A geography ID, or list of geography IDs to exclude.
exclude_vessels: A vessel ID, or list of vessel IDs to exclude.
exclude_vessel_classes: A vessel class, or list of vessel classes to exclude.
exclude_vessel_flags: A vessel flag ID, or list of vessel flag IDs to filter on.
exclude_vessel_ice_class: A vessel ice class ID, or list of vessel ice class IDs to exclude.
exclude_vessel_propulsion: A vessel propulsion ID, or list of vessel propulsion IDs to exclude.
exclude_vessel_tags: A time bound vessel tag, or list of time bound vessel tags to exclude.
exclude_vessel_risk_levels: A vessel risk level, or list of vessel risk levels to exclude.
# Returns
`BreakdownResult`
# Example
_Ton days supply (ballast) of vessels originating from the Middle East by daily frequency over the last 7 days, by origin_country breakdown._
```python
>>> from vortexasdk import FleetUtilisationCapacityTimeseries
>>> from datetime import datetime
>>> search_result = FleetUtilisationCapacityTimeseries().search(
... filter_vessel_status="vessel_status_ballast",
... filter_origins="80aa9e4f3014c3d96559c8e642157edbb2b684ea0144ed76cd20b3af75110877",
... filter_time_min=datetime(2021, 1, 11),
... filter_time_max=datetime(2021, 1, 18),
... timeseries_frequency="day",
... timeseries_property="origin_country")
>>> df = search_result.to_df()
```
Gives the following:
| | key | value | count | breakdown.0.label | breakdown.0.value |breakdown.0.count |
|---:|:-------------------------|----------:|----------:|-----------------------:|------------------:|-----------------:|
| 1 | 2021-01-11 00:00:00+00:00| 17487464 | 308 | "United Arab Emirates" | 6106197 | 133 |
| 2 | 2021-01-12 00:00:00+00:00| 17197204 | 307 | "United Arab Emirates" | 6020588 | 132 |
| 3 | 2021-01-13 00:00:00+00:00| 17393685 | 311 | "United Arab Emirates" | 5768300 | 129 |
| 4 | 2021-01-14 00:00:00+00:00| 16896103 | 302 | "United Arab Emirates" | 5401173 | 124 |
| 5 | 2021-01-15 00:00:00+00:00| 16755532 | 302 | "United Arab Emirates" | 5393500 | 123 |
| 6 | 2021-01-16 00:00:00+00:00| 16243406 | 298 | "United Arab Emirates" | 5382719 | 122 |
| 7 | 2021-01-17 00:00:00+00:00| 16016945 | 288 | "United Arab Emirates" | 5557221 | 121 |
| 8 | 2021-01-18 00:00:00+00:00| 15462925 | 277 | "United Arab Emirates" | 5203393 | 114 |
"""
sts_filter = sts_param_value(filter_ship_to_ship)
crossfilters = {
"filter_ship_to_ship": sts_filter["x_filter"],
# if charterer toggle is True, apply cross filter
# else make it false
"filter_charterer_exists": filter_charterer_exists == True
}
exclude_params = {
"filter_products":
convert_to_list(exclude_products),
"filter_charterers":
convert_to_list(exclude_charterers),
"filter_owners":
convert_to_list(exclude_owners),
"filter_destinations":
convert_to_list(exclude_destinations),
"filter_origins":
convert_to_list(exclude_origins),
"filter_vessels":
convert_to_list(exclude_vessels),
"filter_vessel_classes":
convert_to_list(exclude_vessel_classes),
"filter_vessel_flags":
convert_to_list(exclude_vessel_flags),
"filter_vessel_ice_class":
convert_to_list(exclude_vessel_ice_class),
"filter_vessel_propulsion":
convert_to_list(exclude_vessel_propulsion),
"filter_vessel_risk_levels":
convert_to_list(exclude_vessel_risk_levels),
}
api_params = {
"filter_activity": filter_activity,
"timeseries_frequency": timeseries_frequency,
"timeseries_property": timeseries_property,
"filter_time_min": to_ISODate(filter_time_min),
"filter_time_max": to_ISODate(filter_time_max),
"filter_vessel_age_min": filter_vessel_age_min,
"filter_vessel_age_max": filter_vessel_age_max,
"filter_vessel_dwt_min": filter_vessel_dwt_min,
"filter_vessel_dwt_max": filter_vessel_dwt_max,
"filter_vessel_status": convert_to_list(filter_vessel_status),
"filter_charterers": convert_to_list(filter_charterers),
"filter_owners": convert_to_list(filter_owners),
"filter_products": convert_to_list(filter_products),
"filter_vessels": convert_to_list(filter_vessels),
"filter_vessel_classes": convert_to_list(filter_vessel_classes),
"filter_vessel_flags": convert_to_list(filter_vessel_flags),
"filter_destinations": convert_to_list(filter_destinations),
"filter_origins": convert_to_list(filter_origins),
"filter_vessel_ice_class":
convert_to_list(filter_vessel_ice_class),
"filter_vessel_propulsion":
convert_to_list(filter_vessel_propulsion),
"vessel_tags": convert_to_list(filter_vessel_tags),
"vessel_tags_excluded": convert_to_list(exclude_vessel_tags),
"filter_vessel_risk_levels":
convert_to_list(filter_vessel_risk_levels),
"filter_vessel_scrubbers": filter_vessel_scrubbers,
"exclude": exclude_params,
"crossfilters": crossfilters
}
return BreakdownResult(super().search(**api_params))
