Trades

Note

available on platforms : Platform.Liquids, Platform.LNG, Platform.LPG, Platform.Dry

class kpler.sdk.resources.trades.Trades(configuration, column_ids=True, log_level=None)

The Trades query returns the volumes from one point of interest to another (installation/zone) on a cargo-by-cargo basis.

get(size=None, vessels=None, from_installations=None, to_installations=None, from_zones=None, to_zones=None, buyers=None, sellers=None, products=None, start_date=None, end_date=None, destination_start_date=None, destination_end_date=None, trade_status=None, with_forecast=None, with_intra_country=None, with_intra_region=None, columns=None, with_freight_view=False, with_product_estimation=False)

Parameters

• size – Optional[int] Maximum number of trades returned (a trade can result in more than one row if multi-products one)

• vessels – Optional[List[str]] Names/IMO’s of vessels

• from_installations – Optional[List[str]] Names of the origin installations

• to_installations – Optional[List[str]] Names of the destination installations (terminal/refinery)

• from_zones – Optional[List[str]] Names of the origin zones (port/region/country/continent)

• to_zones – Optional[List[str]] Names of the destination zones (port/region/country/continent)

• buyers – Optional[List[str]] Buyers of the cargo

• sellers – Optional[List[str]] Sellers of the cargo

• products – Optional[List[str]] Names of products

• start_date – Optional[date] Start of the vessel departure period

• end_date – Optional[date] End of the vessel departure period

• destination_start_date – Optional[date] Start of the vessel arrival period

• destination_end_date – Optional[date] End of the vessel arrival period

• trade_status – Optional[List[Enum]] TradesStatus Return only trades of a particular status. By default value is scheduled.

• with_forecast – Optional[bool] By default: withForecast=true. Include trades predicted by our in-house model when set to “true”. Use [“true”, “false”]

• with_intra_country – Optional[bool] By default: withIntraCountry=true. Takes into account the trades within the selected country. Use [“true”, “false”]

• with_intra_region – Optional[bool] By default: withIntraRegion=true. Takes into account the trades within the selected region. Use [“true”, “false”]

• columns – Optional[List[str]] Retrieve all available columns when set to “all”

• with_freight_view – bool By default: with_freight_view=False. Provides access to the entire fleet’s trades, irrespective of your current cargo subscription. Only available via Freight subscription.

• with_product_estimation – bool By default withProductEstimation=False. Activate the product estimation feature. When set to true, the estimated product will overwrite the existing product information.

Examples

>>> from datetime import date, timedelta
... from kpler.sdk.resources.trades import Trades
... trades_client = Trades(config)
... trades_client.get(
... to_zones=["United States"],
... products=["crude"],
... with_forecast=False,
... with_intra_country=True,
... start_date=date.today() - timedelta(days=7),
... columns=[
...     "vessel_name",
...     "closest_ancestor_product",
...     "closest_ancestor_grade",
...     "start",
...     "end",
...     "origin_location_name",
...     "destination_location_name"
... ]
... )

vessel_name	closest_ancestor_product	closest_ancestor_grade	start	end	origin_location_name	destination_location_name
Eco Bel Air	crude	Basrah	2020-11-01 14:20:00	2020-12-14 01:02:00	Al Basrah	PADD 5
Stella	crude	NaN	2020-10-30 09:48:00	2020-12-09 21:30:00	Angra dos Reis	PADD 5
Cap Charles	crude	NaN	2020-10-21 05:47:00	2020-11-20 23:15:00	Angra dos Reis	Long Beach
Sebarok Spirit	crude	Maya	2020-10-21 01:00:00	2020-10-24 06:49:00	Yuum Kak Naab FPSO	Houston
Montreal Spirit	crude	NaN	2020-10-20 13:30:00	2020-11-24 01:18:00	Sao Sebastiao	Cherry Point
Washington	crude	ANS	2020-10-19 14:48:00	2020-10-27 00:00:00	Valdez	San Francisco
…	…	…	…	…	…	…

Return type

DataFrame

get_columns()

This endpoint returns a recent and updated list of all columns available for the endpoint trades.

Examples

>>> from kpler.sdk.resources.trades import Trades
...   trades_client = Trades(config)
...   trades_client.get_columns()

id	name	description	deprecated	type
vessel_name	Vessel	Name of the vessel	False	string
start	Date (origin)	Departure date of the vessel	False	datetime yyyy-MM-dd HH:mm
origin_location_name	Origin	Origin location of the cargo	False	string
origin_eta_source	Eta source (origin)	Source of the Estimated Time of Arrival to the Installation of Origin information (Port, Analyst, etc.)	False	string
cargo_origin_cubic_meters	Volume (origin m3)	None	False	long
…	…	…	…	…

Return type

DataFrame

class kpler.sdk.TradesStatus(value)

Delivered = 'delivered'

InTransit = 'in transit'

Loading = 'loading'

Scheduled = 'scheduled'