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)[source]

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, trade_status=None, with_forecast=None, with_intra_country=None, columns=None, with_freight_view=False, with_product_estimation=False)[source]
Parameters
  • size – Optional[int] Maximum number of trades returned

  • 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 period

  • end_date – Optional[date] End of the 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 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 for CPP trades only. 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()[source]

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)[source]
Delivered = 'delivered'
InTransit = 'in transit'
Loading = 'loading'
Scheduled = 'scheduled'