vortexasdk.endpoints.cargo_timeseries
Try me out in your browser:
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
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
,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 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 |