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: APIClient)

The PortCalls returns a lists of port calls.

get(**kwargs)

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)

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

MutableSequence[int]

port_id

List of Oceanbolt port ids to filter on.

Type

MutableSequence[int]

berth_id

List of Oceanbolt berth ids to filter on.

Type

MutableSequence[int]

unlocode

List of five letter UNLOCODEs of ports to filter on.

Type

MutableSequence[str]

country_code

List of two letter ISO country codes to filter on.

Type

MutableSequence[str]

region

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

Type

MutableSequence[str]

basin

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

Type

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

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

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]

operation

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

Type

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

MutableSequence[float]

vessel_filter

Specifies vessel parameters to filter on.

Type

oceanbolt.com.ptypes.filters.vessel_filter_pb2.VesselFilter

Response

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

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

MutableSequence[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)

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 primary berth/terminal visited during the port call.

Type

google.protobuf.wrappers_pb2.Int32Value

berth_name

Name of the primary berth/terminal visited during the port call.

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 waiting at anchor before shifting to berth.

Type

google.protobuf.wrappers_pb2.DoubleValue

days_at_berth

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

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