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

Response object for trade flow timeseries queries

timeseries

Timeseries data groups.

Type: MutableSequence[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: MutableSequence[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