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

The TradeFlows returns list of historical voyages.

get(**kwargs)[source]

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

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

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

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