List Trade Flows

Retrieve list of trade flows between countries, regions, for various commodity groups, for various vessels, or various ports.

Example questions that can be answered with this endpoint:

• Which vessels loaded coal in Richards Bay in 2020?

• Which vessels discharged Australian coal into China in the past 30 days?

• Which vessels are currently loading fertilizers from the Arabian Gulf?

class oceanbolt.sdk.data.trade_flows.TradeFlows(client: APIClient)

The TradeFlows returns list of historical voyages.

get(**kwargs)

Retrieves trade flow data as a pandas.DataFrame

Example

Which vessels discharged Australian coal into China in the past 30 days?

from oceanbolt.sdk.client import APIClient
from oceanbolt.sdk.data.trade_flows import TradeFlows
from datetime import date, timedelta

base_client = APIClient("<token>")
df = TradeFlows(base_client).get(
    load_country_code=['AU'],
    discharge_country_code=['CN'],
    commodity_group=['coal'],
    start_date=date.today() - timedelta(days=30),
    flow_direction="import", #Specified to filter and group on import date
)

Returns:

voyage_id	flow_id	imo	vessel_name	segment	sub_segment	dwt	commodity	commodity_value	commodity_group	volume	load_port_id	load_port_name	load_port_unlocode	load_berth_id	load_berth_name	load_country_code	load_country	load_region	load_port_arrived_at	load_port_berthed_at	load_port_unberthed_at	load_port_departed_at	load_port_days_total	load_port_days_berthed	load_port_days_waiting	discharge_port_id	discharge_port_name	discharge_port_unlocode	discharge_berth_id	discharge_berth_name	discharge_country_code	discharge_country	discharge_region	discharge_port_arrived_at	discharge_port_berthed_at	discharge_port_unberthed_at	discharge_port_departed_at	discharge_port_days_total	discharge_port_days_berthed	discharge_port_days_waiting	days_steaming	days_total_duration	distance_calculated	distance_actual	eta	destination	status	parceling
a3ba0ef87f61242681c7c70a37960127	534a71d70e8f775b3f0a620957e1838f	9611747	CS SALUBRITY	Capesize	Large Capesize (180-250k)	180300.0	Coking Coal	coking_coal	Coal	44100.0	104	Hay Point	AUHPT	2893	Hay Point BHP Billiton Mitsubishi Alliance Coal Berths	AU	Australia	EAUSSIE	2020-12-10T11:47:15Z	2020-12-19T05:43:08Z		2020-12-21T09:32:28Z	10.906	2.159	8.747	454	Taicang	CNTAC	5875	Taicang Iron Ore Berth	CN	China	FAREAST	2021-02-19T01:59:11Z	2021-02-19T01:59:11Z		2021-02-20T11:21:49Z	1.39	1.39	0.0	59.685	71.982	3722.93	10829.0869359729		CNCFD AUPHE	Complete	True
afc185111ba16621aefb58b2ddff0111	561759de6538530ff53746f5187c7095	9591571	BULK INDONESIA	Panamax	Post-Panamax (90-110k)	95712.0	Thermal Coal	thermal_coal	Coal	46800.0	122	Newcastle	AUNTL	3362	Newcastle NCIG Kooragang Coal Terminal Berths #8 to 10	AU	Australia	EAUSSIE	2020-12-01T20:30:49Z	2020-12-18T02:55:04Z		2020-12-19T07:15:12Z	17.447	1.18	16.266	405	Lanshan	CNLSN	9778	Lanshan Multibulk Berth 4	CN	China	FAREAST	2021-02-14T08:57:04Z	2021-02-14T13:16:30Z		2021-02-18T03:46:55Z	3.784	3.604	0.18	57.07	78.302	4657.7	12901.4480851075	2021-01-04T04:00:00Z	SINGAPORE	Complete	True
c59c682f03c1b04d66e8f192b4738c01	1c5372651561f01161d89e5d4759a48f	9259161	HC PROGRESS	Panamax	Post-Panamax (90-110k)	91879.0	Coal (unclassified)	coal_unclassified	Coal	27800.0	104	Hay Point	AUHPT	2892	Hay Point DBCT Management Coal Berths	AU	Australia	EAUSSIE	2020-11-21T23:03:57Z	2020-11-25T11:00:36Z		2020-11-26T11:34:28Z	4.521	1.023	3.497	413	Xinsha	CNMCI	9123	Xinsha Coal Berth 1	CN	China	FAREAST	2021-02-11T08:20:54Z	2021-02-14T08:58:54Z		2021-02-16T10:56:43Z	5.108	2.081	3.026	76.865	86.494	3469.46	7314.21327295022	2020-12-09T19:30:00Z	KAOHSIUNG	Complete	True
6e3493a6934b3a5d2c330a5269de6738	94a31ee3849059f35bbc5cfa858c618a	9469649	PING MAY	Capesize	Capesize (140-180k)	178043.0	Coking Coal	coking_coal	Coal	86300.0	99	Gladstone	AUGLT	2851	Gladstone RG/Tanna Coal Berth	AU	Australia	EAUSSIE	2020-06-05T02:59:41Z	2020-06-11T14:55:57Z		2020-06-13T19:58:42Z	8.707	2.21	6.497	395	Jingtang	CNJTG	2073	Jingtang Ores Berth 2	CN	China	FAREAST	2020-06-29T18:55:07Z	2021-02-16T04:27:45Z		2021-02-20T00:35:12Z	235.236	3.838	231.397	15.955	259.899	4285.72	4391.5983731839	2020-06-30T14:00:00Z	CN TAS	Complete	True
6e3493a6934b3a5d2c330a5269de6738	3ace89f90616a2b3a59a8aa353c3b5af	9469649	PING MAY	Capesize	Capesize (140-180k)	178043.0	Coking Coal	coking_coal	Coal	86300.0	104	Hay Point	AUHPT	2892	Hay Point DBCT Management Coal Berths	AU	Australia	EAUSSIE	2020-05-28T05:59:52Z	2020-06-03T10:44:59Z		2020-06-04T10:59:45Z	7.208	1.01	6.197	395	Jingtang	CNJTG	2073	Jingtang Ores Berth 2	CN	China	FAREAST	2020-06-29T18:55:07Z	2021-02-16T04:27:45Z		2021-02-20T00:35:12Z	235.236	3.838	231.397	25.33	267.774	4142.27	4632.39126379947	2020-06-05T04:30:00Z	GLT AUS	Complete	True
a98932063b7964d92d3a060fd2089dcf	a3d77733ed47db58433591655876d5bb	9774264	NAVIOS CORAL	Panamax	Kamsarmax (80-90k)	84904.0	Coking Coal	coking_coal	Coal	83200.0	104	Hay Point	AUHPT	2893	Hay Point BHP Billiton Mitsubishi Alliance Coal Berths	AU	Australia	EAUSSIE	2020-05-25T01:46:48Z	2020-06-05T11:55:21Z		2020-06-06T15:59:53Z	12.592	1.169	11.422	395	Jingtang	CNJTG	2073	Jingtang Ores Berth 2	CN	China	FAREAST	2020-06-20T19:55:15Z	2021-02-13T13:48:35Z		2021-02-16T05:57:31Z	240.418	2.672	237.745	14.163	267.174	4142.27	4102.23079895485	2020-06-21T12:00:00Z	JINGTANG CHINA	Complete	False

Arguments

class oceanbolt.com.tradeflows_v3.types.TradeFlowDataRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Trade flow data requests object. This is shared between all trade flows queries

frequency

Frequency determines the granularity/period grouping of the timeseries. Allowed values are: [“daily”, “weekly”, “monthly”,”quarterly”, “yearly”]. Default value is “monthly”. This parameter only applies to the /tradeflows/timeseries endpoint.

Type

str

commodity

List of commodities to get data for (get a list of all commodities from /entities/commodities).

Type

MutableSequence[str]

commodity_group

List of commodity groups to get data for (get a list of all commodity groups from /entities/commodities).

Type

MutableSequence[str]

flow_direction

This controls whether to group the date by export date/import date. Allowed values are **[“export”,”import”]. Default value is “export”. This parameter only applies to the /tradeflows/timeseries endpoint.

Type

str

imo

List of unique vessel identifiers (IMO numbers). This allows filtering to show data only for a subset of vessels. Example: [1234567,7654321].

Type

MutableSequence[int]

load_port_id

Oceanbolt database identifier of the load port.

Type

MutableSequence[int]

load_port_unlocode

List of five letter UNLOCODEs for load (export) ports to filter on.

Type

MutableSequence[str]

load_berth_id

Oceanbolt database identifier of the load berth/terminal.

Type

MutableSequence[int]

discharge_port_id

Oceanbolt database identifier of the discharge port.

Type

MutableSequence[int]

discharge_port_unlocode

List of five letter UNLOCODEs for discharge (import) ports to filter on.

Type

MutableSequence[str]

discharge_berth_id

Oceanbolt database identifier of the discharge berth/terminal.

Type

MutableSequence[int]

segment

List of vessel segments to filter on. Allowed values can be obtained from the /entities/segments endpoint. Cannot be supplied alongside subSegment.

Type

MutableSequence[str]

sub_segment

List of vessel sub segments to filter on. Allowed values can be obtained from the /entities/segments endpoint. Cannot be supplied alongside segment.

Type

MutableSequence[str]

start_date

The UTC start date of the date filter.

Type

str

end_date

The UTC end date of the date filter.

Type

str

load_country_code

List of two letter ISO country codes for loading (export) countries to filter on.

Type

MutableSequence[str]

discharge_country_code

List of two letter ISO country codes for discharge (import) countries to filter on.

Type

MutableSequence[str]

load_region

List of loading regions to filter on. Allowed values can be obtained from the /entities/regions endpoint.

Type

MutableSequence[str]

discharge_region

List of discharge regions to filter on. Allowed values can be obtained from the /entities/regions endpoint.

Type

MutableSequence[str]

status

Type

MutableSequence[str]

exclude_intra_country

Determines whether to include/exclude intra country voyages. Default is to include.

Type

bool

exclude_unknown_destinations

Determines whether to include/exclude voyages with unknown destination. Default is to include.

Type

bool

exclude_missing_load_berth

Determines whether to include/exclude voyages with that have a missing load_berth_id. Default is to include.

Type

bool

exclude_missing_discharge_berth

Determines whether to include/exclude voyages with that have a missing discharge_berth_id. Default is to include.

Type

bool

next_token

The pagination token specifying which page of results to return in the response. If no token is provided, the default page is the first page.

Type

str

max_results

An optional limit for the number of resources returned in a single call.

Type

int

format_

The return format of the data [“csv”, “json”, “xlsx”]. Default is “json”.

Type

str

group_by

Determines the grouping of the timeseries data. This parameter only applies to the /tradeflows/timeseries endpoint.

Type

str

pivot_by

Not implemented.

Type

str

tall_format

Not implemented.

Type

bool

metric

The metric to retrieve for timeseries aggregations. Allowed values: [“volume”,”count”,”ton_mile_calculated”,”ton_mile_actual”,”average_haul”,”average_speed”, “volume_times_duration”]. Default is “volume”.

Type

str

parceling

List of parceling statuses to retrieve. Allowed values are: [“include”,”exclude”,”only”].

Type

MutableSequence[str]

limit_groups

Flag to indicate whether grouped timeseries should be limited to top N entries. If the parameter is present, the endpoint will only return the top N groups, and the remaining entries will be grouped into others.

Type

bool

last_n_days

Short hand parameter for quickly getting data for the last N days. Cannot be supplied along either start_date or end_date.

Type

int

sort

Specifies whether results should be sorted in ascending or descending order. Allowed values: [“asc”,”desc”].

Type

str

dwt

DWT range to filter on. Example: [60000,90000] - this would filter only to only include dwt between 60k and 90k (both values inclusive).

Type

MutableSequence[float]

category

Specifies the base category for aggregation queries. This parameter only has effect on the GetTradeFlowAggregation method (REST endpoint: /tradeflows/aggregation).

Type

str

vessel_filter

Specifies vessel parameters to filter on.

Type

oceanbolt.com.ptypes.filters.vessel_filter_pb2.VesselFilter

Response

class oceanbolt.com.tradeflows_v3.types.GetTradeFlowsResponse(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Response object for trade flow queries

data

List of trade flows.

Type

MutableSequence[oceanbolt.com.tradeflows_v3.types.TradeFlow]

next_token

Pagination token indicating the presence of additional further results.

Type

str

prev_token

Pagination token indicating the presence of additional previous results.

Type

str

csv

Link to download csv file, if format was specified to be “csv”.

Type

str

xlsx

Link to download excel file, if format was specified to be “xlsx”.

Type

str

class oceanbolt.com.tradeflows_v3.types.TradeFlow(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Trade flow object

voyage_id

Unique ID for the voyage. This can be shared across multiple flows in the case of parceling voyages.

Type

str

flow_id

Unique ID for the trade flow. This will always be unique to the flow.

Type

str

imo

IMO number of the vessel.

Type

int

vessel_name

Name of the vessel.

Type

str

segment

Segment of the vessel.

Type

str

sub_segment

Sub segment of the vessel.

Type

str

dwt

DWT of the vessel.

Type

float

commodity

Name of the commodity.

Type

str

commodity_value

Database friendly name of the commodity.

Type

str

commodity_group

Name of the commodity group.

Type

str

volume

Volume loaded in metric tons.

Type

float

load_port_id

Oceanbolt database identifier of the load port.

Type

google.protobuf.wrappers_pb2.Int32Value

load_port_name

Name of the load port.

Type

str

load_port_unlocode

UNLOCODE of the load port.

Type

str

load_berth_id

Oceanbolt database identifier of the load berth/load terminal.

Type

google.protobuf.wrappers_pb2.Int32Value

load_berth_name

Name of the load berth/load terminal.

Type

str

load_country_code

ISO 2-letter country code of the load country.

Type

str

load_country

Name of the load country.

Type

str

load_region

Name of the load region.

Type

str

load_port_arrived_at

UTC timestamp for when the vessel arrived at the load port.

Type

str

load_port_berthed_at

UTC timestamp for when the vessel berthed in the load port.

Type

str

load_port_unberthed_at

UTC timestamp for when the vessel left the berth the load port.

Type

str

load_port_departed_at

UTC timestamp for when the vessel departed the load port.

Type

str

load_port_days_total

Total duration of the load port call (in days).

Type

google.protobuf.wrappers_pb2.DoubleValue

load_port_days_berthed

Number of days the vessel was at berth in the load port.

Type

google.protobuf.wrappers_pb2.DoubleValue

load_port_days_waiting

Number of days the vessel was waiting at the load port before shifting to berth.

Type

google.protobuf.wrappers_pb2.DoubleValue

discharge_port_id

Oceanbolt database identifier of the load berth/load terminal.

Type

google.protobuf.wrappers_pb2.Int32Value

discharge_port_name

Name of the load port.

Type

str

discharge_port_unlocode

UNLOCODE of the load port.

Type

str

discharge_berth_id

Oceanbolt database identifier of the load berth/load terminal.

Type

google.protobuf.wrappers_pb2.Int32Value

discharge_berth_name

Name of the load berth/load terminal.

Type

str

discharge_country_code

ISO 2-letter country code of the load country.

Type

str

discharge_country

Name of the load country.

Type

str

discharge_region

Name of the load region.

Type

str

discharge_port_arrived_at

UTC timestamp for when the vessel arrived at the discharge port.

Type

str

discharge_port_berthed_at

UTC timestamp for when the vessel berthed in the discharge port.

Type

str

discharge_port_unberthed_at

UTC timestamp for when the vessel left the berth the discharge port.

Type

str

discharge_port_departed_at

UTC timestamp for when the vessel departed the discharge port.

Type

str

discharge_port_days_total

Total duration of the load port call (in days).

Type

google.protobuf.wrappers_pb2.DoubleValue

discharge_port_days_berthed

Number of days the vessel was at berth in the discharge port.

Type

google.protobuf.wrappers_pb2.DoubleValue

discharge_port_days_waiting

Number of days the vessel was waiting at the discharge port before shifting to berth.

Type

google.protobuf.wrappers_pb2.DoubleValue

days_steaming

Number of days the vessel was steaming (the time from when it left the discharge port until it arrived at the discharge port).

Type

google.protobuf.wrappers_pb2.DoubleValue

days_total_duration

Total duration of the voyage (in days).

Type

google.protobuf.wrappers_pb2.DoubleValue

distance_calculated

Calculated distance in nautical miles between load port and discharge port. Based on port distance tables.

Type

google.protobuf.wrappers_pb2.DoubleValue

distance_actual

Actual distance sailed in nautical miles between load port and discharge port. Based on AIS tracks.

Type

google.protobuf.wrappers_pb2.DoubleValue

eta

Captain’s Reported ETA.

Type

str

destination

Captain’s Reported Destination.

Type

str

status

Status of the trade flow.

Type

str

parceling

Flag indicating whether the trade flow was part of a parceling voyage or a single voyage.

Type

bool

ballast_started_at

UTC timestamp for when the vessel started ballasting from the last discharge port.

Type

str

ballast_port_name

Name of the port where the vessel ballasted from.

Type

str

ballast_port_id

Oceanbolt database identifier for the port where the vessel ballasted from.

Type

google.protobuf.wrappers_pb2.Int32Value

ballast_port_unlocode

Type

str

ballast_country

Name of the ballast country.

Type

str

ballast_country_code

ISO 2-letter country code of the ballast country.

Type

str

ballast_region

Name of the ballast region.

Type

str