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