vortexasdk.endpoints.cargo_timeseries
Try me out in your browser:
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
orexclude_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 usefilter_time_min
andfilter_time_max
to specify 1st Jan 2019 and 31st Dec 2019 respectively, we'd setfilter_activity='loading_state'
andtimeseries_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 withfilter_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 withfilter_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 |