List Port Calls

Retrieve list of port calls in different countries or regions, while filtering for various commodity groups, for various vessels, or various ports.

Example questions that can be answered with this endpoint:

  • Which vessels have called the port of Santos in the past year?

  • Which vessels have loaded bauxite in Guinea in the past month?

class oceanbolt.sdk.data.port_calls.PortCalls(client: oceanbolt.sdk.client.APIClient)[source]

The PortCalls returns a lists of port calls.

get(**kwargs)[source]

Retrieves port calls data as a pandas.DataFrame

Example

Which vessels have loaded bauxite in Guinea in the past month?

from oceanbolt.sdk.client import APIClient
from oceanbolt.sdk.data.port_calls import PortCalls
from datetime import date,timedelta


base_client = APIClient("<token>")
df = PortCalls(base_client).get(
    country_code=['GN'],
    commodity_group = ['bauxite'],
    start_date=date.today() - timedelta(days=30),
)

Returns:

voyage_id

port_call_id

imo

vessel_name

port_id

port_name

segment

sub_segment

unlocode

berth_id

berth_name

anchorage_id

anchorage_name

arrived_at

berthed_at

unberthed_at

departed_at

days_in_port

days_waiting

days_at_berth

country_code

operation

voyage_type

commodity

commodity_value

commodity_group

volume

port_visited

22f5c4b1c13ffd56aa6179614b78cdf0

b2894d359ccb34bbd008ab61bd1259dd

9262730

AGIOS CHARALAMBOS

998

Port Kamsar

Capesize

Large Capesize (180-250k)

GNKMR

10171

Port Kamsar Bauxite Loading Anchorage

2021-02-21T13:48:55Z

2021-02-21T13:48:55Z

0.0

GN

Load

Part of Laden Leg

Bauxite

bauxite

Bauxite

181100.0

False

b9b237384e1ec8a7cc5869da60602754

a1667ce115d3f46952b739547620b168

9165516

CAPE OSPREY

998

Port Kamsar

Capesize

Capesize (140-180k)

GNKMR

10171

Port Kamsar Bauxite Loading Anchorage

2021-02-20T16:45:36Z

2021-02-20T16:45:36Z

0.0

GN

Load

Part of Laden Leg

Bauxite

bauxite

Bauxite

168400.0

False

6ce296f896c8c16fa60aa8ee72879587

536cda0f3344512eac7d793d75423927

9844588

CL HUANGPU RIVER

998

Port Kamsar

Capesize

Large Capesize (180-250k)

GNKMR

10171

Port Kamsar Bauxite Loading Anchorage

2021-02-19T17:13:47Z

2021-02-19T17:13:47Z

0.0

GN

Load

Part of Laden Leg

Bauxite

bauxite

Bauxite

203800.0

False

0664d6d6310b18a09f386ce1a09b4e2c

252c092f7075dd75c95e3ff17e4807c4

9279393

WINNING EXCELLENCE

998

Port Kamsar

Capesize

Large Capesize (180-250k)

GNKMR

10171

Port Kamsar Bauxite Loading Anchorage

2021-02-18T15:39:05Z

2021-02-18T15:39:05Z

0.0

GN

Load

Part of Laden Leg

Bauxite

bauxite

Bauxite

151300.0

False

16091932b47134794bc9518b20a05a6b

5e43bdd5d33ccb7a8b18d0348a09ae27

9607289

YELLOW FIN

998

Port Kamsar

Supramax

Supramax (50-60k)

GNKMR

10171

Port Kamsar Bauxite Loading Anchorage

2021-02-16T11:46:33Z

2021-02-16T11:46:33Z

0.0

GN

Load

Part of Laden Leg

Bauxite

bauxite

Bauxite

55600.0

False

Arguments

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

Port calls data requests object. This is shared between all port calls queries

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]

port_id

List of Oceanbolt port ids to filter on.

Type

Sequence[int]

berth_id

List of Oceanbolt berth ids to filter on.

Type

Sequence[int]

unlocode

List of five letter UNLOCODEs of ports to filter on.

Type

Sequence[str]

country_code

List of two letter ISO country codes to filter on.

Type

Sequence[str]

region

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

Type

Sequence[str]

basin

List of basins to filter on. Allowed values are: [“atlantic”,”indian_ocean”,”pacific_americas”,”pacific_asia”].

Type

Sequence[str]

latest_only

Flat to indiciate whether only the latest port call should be included on an IMO basis. If this is enabled, only the latest port call for each imo passing the filter will be returned.

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

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

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]

operation

List of port call operation types to filter on. Allowed values are: **[“D”,”Dx”;”L”,”Lx”,”B”,”Y”,”U”].

Type

Sequence[str]

sort

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

Type

str

group_by

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

Type

str

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 /portcalls/timeseries endpoint.

Type

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

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]

Response

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

Response object for port call queries

prev_token

Pagination token indicating the presence of additional previous results.

Type

str

next_token

Pagination token indicating the presence of additional further results.

Type

str

data

List of port calls.

Type

Sequence[oceanbolt.com.portcalls_v3.types.PortCall]

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

Port call object

voyage_id

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

Type

str

port_call_id

Unique ID for the port call. This will always be unique to the port call.

Type

str

imo

IMO number of the vessel.

Type

int

vessel_name

Name of the vessel.

Type

str

port_id

Oceanbolt database identifier of the port.

Type

google.protobuf.wrappers_pb2.Int32Value

port_name

Name of the port.

Type

str

segment

Segment of the vessel.

Type

str

sub_segment

Sub segment of the vessel.

Type

str

unlocode

UNLOCODE of the port.

Type

str

berth_id

Oceanbolt database identifier of the berth/terminal.

Type

google.protobuf.wrappers_pb2.Int32Value

berth_name

Name of the berth/terminal.

Type

str

anchorage_id

Oceanbolt database identifier of the anchorage.

Type

google.protobuf.wrappers_pb2.Int32Value

anchorage_name

Name of the anchorage.

Type

str

arrived_at

UTC timestamp for when the vessel arrived at the port.

Type

str

berthed_at

UTC timestamp for when the vessel berthed in the port.

Type

str

unberthed_at

UTC timestamp for when the vessel left the berth/terminal.

Type

str

departed_at

UTC timestamp for when the vessel left the port.

Type

str

days_in_port

Total duration of the port call (in days).

Type

google.protobuf.wrappers_pb2.DoubleValue

days_waiting

Number of days the vessel was at berth in during the duration of the port call.

Type

google.protobuf.wrappers_pb2.DoubleValue

days_at_berth

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

Type

google.protobuf.wrappers_pb2.DoubleValue

country_code

ISO 2-letter country code of the load country.

Type

str

operation

Operation type of the port call.

Type

str

voyage_type

The type of the voyage.

Type

str

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

google.protobuf.wrappers_pb2.DoubleValue

port_visited

Flag to indicate whether the vessel has visited the port interior. If the flag is false the vessels only visited an anchorage.

Type

bool