Time Series Endpoint.
CargoTimeSeries.search(self, filter_activity: str, timeseries_activity: str = 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]] = 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) -> 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?
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_activityif 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_maxto specify 1st Jan 2019 and 31st Dec 2019 respectively, we'd set
timeseries_activity='unloading_state'to filter on loadings but aggregate on unloadings.
filter_activityMust 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 * 14in conjunction with
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 * 14in conjunction with
- 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:
TimeSeriesResult(self, _records: List) -> None
Container class that holds the result obtained from calling a time series endpoint.
TimeSeriesResult.to_list(self) -> List[vortexasdk.api.timeseries_item.TimeSeriesItem]
Represents time series as a list.
TimeSeriesResult.to_df(self, columns=None) -> pandas.core.frame.DataFrame
Represents the timeseries as a dataframe.
pd.DataFrame, of time series items with columns:
key: The time series key
value: The value of the time series for a given key
count: The number of records contributing to this time series record.
If we're aggregating Crude exports in tonnes by day, then the
key column holds the date,
value column holds the Crude exports on that day, and the
count column holds
the number of cargo movements contributing towards this day's tonnage.