vortexasdk.endpoints.cargo_timeseries

Try me out in your browser:

Binder

CargoTimeSeries

CargoTimeSeries(self) -> None

search

CargoTimeSeries.search(self, filter_activity: str, timeseries_activity: Union[str, NoneType] = None, timeseries_frequency: str = 'day', timeseries_unit: str = 'b', filter_time_min: datetime.datetime = datetime.datetime(2019, 10, 1, 0, 0), filter_time_max: datetime.datetime = datetime.datetime(2019, 10, 1, 1, 0), filter_charterers: Union[str, List[str], NoneType] = None, filter_destinations: Union[str, List[str], NoneType] = None, filter_origins: Union[str, List[str], NoneType] = None, filter_owners: Union[str, List[str], NoneType] = None, filter_vessel_owners: Union[str, List[str], NoneType] = None, filter_time_charterers: Union[str, List[str], NoneType] = None, filter_effective_controllers: Union[str, List[str], NoneType] = None, filter_products: Union[str, List[str], NoneType] = None, filter_vessels: Union[str, List[str], NoneType] = None, filter_vessel_classes: Union[str, List[str], NoneType] = None, filter_vessel_age_min: Union[int, NoneType] = None, filter_vessel_age_max: Union[int, NoneType] = None, filter_storage_locations: Union[str, List[str], NoneType] = None, filter_ship_to_ship_locations: Union[str, List[str], NoneType] = None, filter_waypoints: Union[str, List[str], NoneType] = None, exclude_ship_to_ship: Union[bool, NoneType] = False, exclude_ship_to_ship_locations: Union[str, List[str], NoneType] = None, exclude_storage_locations: Union[str, List[str], NoneType] = None, exclude_charterers: Union[str, List[str], NoneType] = None, exclude_vessel_owners: Union[str, List[str], NoneType] = None, exclude_time_charterers: Union[str, List[str], NoneType] = None, exclude_origins: Union[str, List[str], NoneType] = None, exclude_products: Union[str, List[str], NoneType] = None, exclude_vessels: Union[str, List[str], NoneType] = None, exclude_vessel_classes: Union[str, List[str], NoneType] = None, exclude_vessel_flags: Union[str, List[str], NoneType] = None, exclude_vessel_ice_class: Union[str, List[str], NoneType] = None, exclude_vessel_propulsion: Union[str, List[str], NoneType] = None, exclude_effective_controllers: Union[str, List[str], NoneType] = None, exclude_owners: Union[str, List[str], NoneType] = None, exclude_destinations: Union[str, List[str], NoneType] = None, exclude_waypoints: Union[str, List[str], NoneType] = None, disable_geographic_exclusion_rules: Union[bool, NoneType] = None, intra_movements: Union[str, NoneType] = None, timeseries_activity_time_span_min: Union[int, NoneType] = None, timeseries_activity_time_span_max: Union[int, NoneType] = None, timeseries_property: Union[str, NoneType] = None) -> vortexasdk.endpoints.timeseries_result.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', 'oil_on_water_state', 'waypoint_start,waypoint_end`].

  • 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_effective_controllers: An effective controller ID, or list of effective controller IDs to filter on.

  • filter_vessel_owners: An vessel owner ID, or list of vessel owners IDs to filter on.

  • filter_time_charterers: An time charterer ID, or list of time charterers 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_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.

  • 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_ship_to_ship: A boolean flag to exclude ship-to-ship movements.

  • exclude_ship_to_ship_locations: A geography ID, or list of geography IDs to exclude.

  • exclude_storage_locations: 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_charterers: A charterer ID, or list of charterer IDs to exclude.

  • exclude_effective_controllers: An effective controller ID, or list of effective controller IDs to exclude.

  • exclude_vessel_owners: A vessel owner ID, or list of vessel owners IDs to filter on.

  • exclude_time_charterers: An time charterer ID, or list of time charterers IDs to filter on.

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

  • exclude_waypoints: A geography ID, or list of geography 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.

  • intra_movements: This enum controls a popular industry term intra-movements and determines the filter behaviour for cargo leaving then entering the same geographic area. One of all, exclude_intra_country or exclude_intra_geography

  • 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_property: Property to split results by. Can be one of: quantity, 'vessel_class_group', 'vessel_class_coarse', 'vessel_class_granular', vessel_flag, origin_region, origin_shipping_region, origin_trading_region, origin_trading_sub_region, origin_country, origin_port, origin_terminal, destination_region, destination_shipping_region, destination_trading_region, destination_trading_sub_region, destination_country, destination_port, destination_terminal, product_group, product_group_product, product_category, product_grade, waypoint_selected, none or not provided.

  • timeseries_unit: A numeric metric to be calculated for each time bucket. Must be one of ['b', 'bpd', 't', 'tpd', 'c', 'cpd'], corresponding to barrels, barrels per day, metric tonnes, metric tonnes per day, 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?
>>> 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