vortexasdk.endpoints.cargo_timeseries

Try me out in your browser:

Binder

CargoTimeSeries

CargoTimeSeries(self)

search

CargoTimeSeries.search(
  filter_activity: str,
  timeseries_activity: typing.Optional[str] = None,
  timeseries_frequency: str = 'day',
  timeseries_unit: str = 'b',
  filter_time_min: datetime = datetime.datetime(2019, 10, 1, 0, 0),
  filter_time_max: datetime = datetime.datetime(2019, 10, 1, 1, 0),
  filter_charterers: typing.Union[str, typing.List[str], NoneType] = None,
  filter_destinations:
    typing.Union[str, typing.List[str], NoneType] = None,
  filter_origins: typing.Union[str, typing.List[str], NoneType] = None,
  filter_owners: typing.Union[str, typing.List[str], NoneType] = None,
  filter_vessel_owners:
    typing.Union[str, typing.List[str], NoneType] = None,
  filter_time_charterers:
    typing.Union[str, typing.List[str], NoneType] = None,
  filter_effective_controllers:
    typing.Union[str, typing.List[str], NoneType] = None,
  filter_shipper: typing.Union[str, typing.List[str], NoneType] = None,
  filter_consignee: typing.Union[str, typing.List[str], NoneType] = None,
  filter_products: typing.Union[str, typing.List[str], NoneType] = None,
  filter_vessels: typing.Union[str, typing.List[str], NoneType] = None,
  filter_vessel_classes:
    typing.Union[str, typing.List[str], NoneType] = None,
  filter_vessel_age_min: typing.Optional[int] = None,
  filter_vessel_age_max: typing.Optional[int] = None,
  filter_storage_locations:
    typing.Union[str, typing.List[str], NoneType] = None,
  filter_ship_to_ship_locations:
    typing.Union[str, typing.List[str], NoneType] = None,
  filter_waypoints: typing.Union[str, typing.List[str], NoneType] = None,
  exclude_ship_to_ship: typing.Optional[bool] = False,
  exclude_ship_to_ship_locations:
    typing.Union[str, typing.List[str], NoneType] = None,
  exclude_storage_locations:
    typing.Union[str, typing.List[str], NoneType] = None,
  exclude_charterers:
    typing.Union[str, typing.List[str], NoneType] = None,
  exclude_vessel_owners:
    typing.Union[str, typing.List[str], NoneType] = None,
  exclude_time_charterers:
    typing.Union[str, typing.List[str], NoneType] = None,
  exclude_shipper: typing.Union[str, typing.List[str], NoneType] = None,
  exclude_consignee: typing.Union[str, typing.List[str], NoneType] = None,
  exclude_origins: typing.Union[str, typing.List[str], NoneType] = None,
  exclude_products: typing.Union[str, typing.List[str], NoneType] = None,
  exclude_vessels: typing.Union[str, typing.List[str], NoneType] = None,
  exclude_vessel_classes:
    typing.Union[str, typing.List[str], NoneType] = None,
  exclude_vessel_flags:
    typing.Union[str, typing.List[str], NoneType] = None,
  exclude_vessel_ice_class:
    typing.Union[str, typing.List[str], NoneType] = None,
  exclude_vessel_propulsion:
    typing.Union[str, typing.List[str], NoneType] = None,
  exclude_effective_controllers:
    typing.Union[str, typing.List[str], NoneType] = None,
  exclude_owners: typing.Union[str, typing.List[str], NoneType] = None,
  exclude_destinations:
    typing.Union[str, typing.List[str], NoneType] = None,
  exclude_waypoints: typing.Union[str, typing.List[str], NoneType] = None,
  disable_geographic_exclusion_rules: typing.Optional[bool] = None,
  intra_movements: typing.Optional[str] = None,
  timeseries_activity_time_span_min: typing.Optional[int] = None,
  timeseries_activity_time_span_max: typing.Optional[int] = None,
  timeseries_property: typing.Optional[str] = None,
  quantity_at_time_of: str = 'load')

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_shipper: A shipper ID, or list of shipper IDs to filter on.

    filter_consignee: A consignee ID, or list of consignee IDs to filter on.

    filter_products: A product ID, or list of product IDs to filter on.

    filter_vessels: A vessel ID, or list of vessel IDs to filter on.

    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_shipper: A shipper ID, or list of shipper IDs to exclude.

    exclude_consignee: A consignee ID, or list of consignee IDs to exclude.

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

    exclude_vessel_ice_class: An attribute ID, or list of attribute IDs to exclude.

    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, waypoint_selected, origin_country, origin_port, origin_region, origin_trading_region, origin_shipping_region, origin_terminal, origin_trading_sub_region, origin_shipping_region_v2, origin_basin, origin_wider_shipping_region, origin_country_zone, origin_alternative_region, origin_state_or_province, destination_country, destination_port, destination_region, destination_shipping_region, destination_terminal, destination_trading_region, destination_trading_sub_region, destination_basin, destination_shipping_region_v2, destination_wider_shipping_region, destination_country_zone, destination_alternative_region, destination_state_or_province, product_category, product_grade, product_group, product_group_product, vessel_class_group, vessel_class_coarse, vessel_class_granular, vessel_flag, storage_location_country, storage_location_region, storage_location_shipping_region_v2, storage_location_trading_sub_region, shipper, consignee, or not provided.

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

    quantity_at_time_of: This parameter is designed for LNG cargo and gives the user the freedom to choose whether to create the time series based on the load volume or discharged volumes, as we consider the discharge quantities to differ from load quantities due to boil-off gas. Can be load or unload. Default is load. load - represents the quantity of the selected unit at the time of the loading event. unload - represents the quantity of the selected unit at the time of the unloading event.

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