Trade Flow Timeseries

Find aggregate trade flows between countries, regions, for various commodity groups, for various vessels, or various ports.

Example questions that can be answered with this endpoint:

  • How many tons of iron ore has been imported into China each day over the last year?

  • How many tonnes of alumina did Hydro export from its Alunorte Facility each week over the last 3 years?

  • How have average haul (nautical miles/ton) for capesize vessels changed over time?

class oceanbolt.sdk.data.trade_flows.TradeFlowTimeseries(client: oceanbolt.sdk.client.APIClient)[source]

The TradeFlowsTimeseries returns list of historical voyages.

get(**kwargs)[source]

Retrieves timeseries data as a pandas.DataFrame

Example

What was the monthly export of iron ore from Port Hedland over the last year?

from oceanbolt.sdk.client import APIClient
from oceanbolt.sdk.data.trade_flows import TradeFlowTimeseries
from datetime import date


base_client = APIClient("<token>")
df = TradeFlowTimeseries(base_client).get(
    frequency="monthly",
    load_port_unlocode=['AUPHE'],
    commodity_group=['iron_ore'],
    start_date=date(2020, 1, 1),
    end_date=date(2020, 12, 31),
)

Returns:

date

value

2020-01-01

40386200.0

2020-02-01

38528300.0

2020-03-01

46603900.0

2020-04-01

44728400.0

2020-05-01

47670900.0

2020-06-01

50618500.0

2020-07-01

44668200.0

2020-08-01

47672900.0

2020-09-01

44929400.0

2020-10-01

45641300.0

2020-11-01

41011600.0

2020-12-01

46966000.0

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

Sequence[str]

commodity_group

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

Type

Sequence[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

Sequence[int]

load_port_id

Oceanbolt database identifier of the load port.

Type

Sequence[int]

load_port_unlocode

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

Type

Sequence[str]

load_berth_id

Oceanbolt database identifier of the load berth/terminal.

Type

Sequence[int]

discharge_port_id

Oceanbolt database identifier of the discharge port.

Type

Sequence[int]

discharge_port_unlocode

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

Type

Sequence[str]

discharge_berth_id

Oceanbolt database identifier of the discharge berth/terminal.

Type

Sequence[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

Sequence[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

Sequence[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

Sequence[str]

discharge_country_code

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

Type

Sequence[str]

load_region

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

Type

Sequence[str]

discharge_region

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

Type

Sequence[str]

status
Type

Sequence[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”]. Default is “volume.

Type

str

parceling

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

Type

Sequence[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

Sequence[float]

category

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

Type

str

Response

class oceanbolt.com.tradeflows_v3.types.GetTradeFlowTimeseriesResponse(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Response object for trade flow timeseries queries

timeseries

Timeseries data groups.

Type

Sequence[oceanbolt.com.tradeflows_v3.types.TimeseriesGroup]

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.TimeseriesGroup(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Trade flow timeseries group

group

Name of the group. This will be “default”, if no grouping was specified in the query.

Type

str

group_value

Helper variable to calculate top groups. Not returned.

Type

google.protobuf.wrappers_pb2.DoubleValue

rows

Rows of timeseries data.

Type

Sequence[oceanbolt.com.tradeflows_v3.types.TimeseriesRow]

class oceanbolt.com.tradeflows_v3.types.TimeseriesRow(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Trade flow timeseries row

date

UTC date timestamp of the timeseries row.

Type

str

value

The value of the timeseries row.

Type

google.protobuf.wrappers_pb2.DoubleValue