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_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_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)

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, 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, 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