List Congested Vessels

Retrieve list of congested vessels 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 VLOCs are currently congested in Brazil waiting to load?

  • Which vessels are currently congested in China waiting to discharge Australian coal?

class oceanbolt.sdk.data.congestion.CongestionVessels(client: APIClient)[source]

The CongestionVessels returns a list of either current congested vessels or a list of congested vessels at a prior historical date.

get(**kwargs)[source]

Retrieves current congested vessels as a pandas.DataFrame

Example

Which vessels are currently congested in China waiting to discharge Australian coal?

from oceanbolt.sdk.client import APIClient
from oceanbolt.sdk.data.congestion import CongestionVessels


base_client = APIClient("<token>")
df = CongestionVessels(base_client).get(
    country_code=['CN'],
    last_load_country_code=['AU'],
    commodity_group = ['coal'],
)

Returns:

”imo”

vesselName

segment

subSegment

dwt

currentPortName

currentCountry

currentCountryCode

arrivedAt

waitingTimeDays

lastLoadCountry

lastLoadCountryCode

lastLoadPortName

lastLoadBerthName

lastPortDepartedAt

commodityGroup

commodity

volume

9693422

FRATERNELLE

Panamax

Kamsarmax (80-90k)

82086

Bayuquan

China

CN

2020-09-11T14:50:51Z

160.94841746067797

Australia

AU

Hay Point

Hay Point DBCT Management Coal Berths

2020-08-26T15:59:55Z

Coal

Coal (unclassified)

80400

9501071

PELOPIDAS

Capesize

Capesize (140-180k)

176006

Bayuquan

China

CN

2020-09-13T23:56:56Z

158.56919292613023

Australia

AU

Hay Point

Hay Point DBCT Management Coal Berths

2020-08-29T13:59:53Z

Coal

Coal (unclassified)

172400

9719941

KSL SAKURA

Capesize

Large Capesize (180-250k)

181062

Zhanjiang

China

CN

2020-10-05T03:49:38Z

137.40759569984374

Australia

AU

Newcastle

Newcastle PWCS Kooragang Coal Terminal Berths #4 to 7

2020-09-20T16:57:11Z

Coal

Coal (unclassified)

175500

9510694

OLYMPIC GLORY

Panamax

Kamsarmax (80-90k)

84091

Donggang

China

CN

2020-10-06T00:51:55Z

136.53101005195037

Australia

AU

Hay Point

Hay Point BHP Billiton Mitsubishi Alliance Coal Berths

2020-09-18T03:44:27Z

Coal

Coking Coal

82400

9442768

FAR EASTERN JUPITER

Panamax

Kamsarmax (80-90k)

82655

Bayuquan

China

CN

2020-10-06T03:56:16Z

136.4029892226362

Australia

AU

Hay Point

Hay Point DBCT Management Coal Berths

2020-09-21T02:58:14Z

Coal

Coal (unclassified)

81000

Arguments

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

Congestion request object.

port_id

List of Oceanbolt port ids to filter on. This filters on the port where the vessel is currently congested.

Type:

MutableSequence[int]

port_unlocode

List of five letter UNLOCODEs for to filter on.

Type:

MutableSequence[str]

country_code

The list of 2-letter ISO countries to get congestion data for. This filters on the country where the vessel is currently congested. Country code can be obtained either from the /entities/countries endpoint.

Type:

MutableSequence[str]

region_id

The list of regionIds to get congestion data for. This filters on the region where the vessel is currently congested. Region Id can be obtained either from the /entities/regions endpoint.

Type:

MutableSequence[str]

operation

List of port call operation types to filter on. Allowed values are: **[“load”,”discharge”;”yard”,”unknown”].

Type:

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

laden_status

Laden status to filter on. Allowed values are [‘laden’, ‘ballast’].

Type:

MutableSequence[str]

imo

List of IMO numbers to include in the congestion data results.

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]

group_by

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

Type:

str

frequency

Not implemented.

Type:

str

last_load_country_code

The list of 2-letter ISO countries to get congestion data for. This filters on the country where the vessel loaded its prior cargo. Country code can be obtained either from the /entities/countries endpoint.

Type:

MutableSequence[str]

last_load_port_id

List of Oceanbolt port ids to filter on. This filters on the ports where the vessel loaded its prior cargo.

Type:

MutableSequence[int]

exclude

Specifies whether to exclude congestion stays that have a longer duration than N (in days). For example if a value of exlude=60’` is specified then all congestion stays that lasted longer than 60 days will be excluded from the returned data.

Type:

int

max_stay_length

Specifies whether to exclude congestion stays that have a longer duration than N (in days). For example if a value of max_stay_length=60’` is specified then all congestion stays that lasted longer than 60 days will be excluded from the returned data.

Type:

int

include_vessels_currently_at_berth

Flag to indicate whether vessels that are currently at berth should be included in congestion statistics.

Type:

bool

include_vessels_previously_berthed

Flag to indicate whether vessels that have already visited a berth (but are not currently in a berth) as part of the current Port Call should be included in congestion statistics.

Type:

bool

format_

The return format of the data [“csv”,”json”, “xlsx”]. Default is “json”.

Type:

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

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 descing order. Allowed values: [“asc”,”desc”].

Type:

str

display_date

Parameter used to display historical vessel lists for congested vessels. It is only applicable to the CongestionVessels method.

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]

vessel_filter

Specifies vessel parameters to filter on.

Type:

oceanbolt.com.ptypes.filters.vessel_filter_pb2.VesselFilter

Response

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

Congestion responseobject.

number_of_current_vessels

Number of vessels currently congested.

Type:

int

current_top_ports

List of top ports by amount of congested.

Type:

MutableSequence[oceanbolt.com.congestion_v3.types.CongestionSplitRow]

current_top_sub_segments

List of top segments by amount of congested.

Type:

MutableSequence[oceanbolt.com.congestion_v3.types.CongestionSplitRow]

current_top_commodity_groups

List of top commodities by amount of congested.

Type:

MutableSequence[oceanbolt.com.congestion_v3.types.CongestionSplitRow]

current_top_load_countries

List of top countries by amount of congested.

Type:

MutableSequence[oceanbolt.com.congestion_v3.types.CongestionSplitRow]

timeseriesDefault

Ungrouped timeseries response.

Type:

oceanbolt.com.congestion_v3.types.CongestionTimeseriesGroup

current_vessels

List of vessels currently congested.

Type:

MutableSequence[oceanbolt.com.congestion_v3.types.CongestionStay]

timeseries

Congestion timeseries response.

Type:

MutableSequence[oceanbolt.com.congestion_v3.types.CongestionTimeseriesGroup]

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

IMO number of the vessel.

Type:

int

vessel_name

Name of the vessel.

Type:

str

segment

The vessel segment (handysize, supramax, panamax etc.).

Type:

str

sub_segment

The vessel sub segment (large capesize, kamsarmax, vloc etc.).

Type:

str

dwt

The DWT of the vessel.

Type:

float

current_port_id

The Oceanbolt port id where the vessel is currently congested.

Type:

str

current_port_name

The name of the port where the vessel is currently congested.

Type:

str

current_country

The name of the country where the vessel is currently congested.

Type:

str

current_country_code

The 2-letter ISO code of the country where the vessel is currently congested.

Type:

str

arrived_at

The UTC timestamp of when the vessel arrived at the current port.

Type:

str

waiting_time_days

The waiting time in days that the vessel has waiting up until today.

Type:

float

last_load_country

The name of the country where the vessel loaded its prior cargo.

Type:

str

last_load_country_code

The 2-letter ISO code of the country where the vessel loaded its prior cargo.

Type:

str

last_load_port_name

The name of the port where the vessel loaded its prior cargo.

Type:

str

last_load_berth_name

The name of the terminal where the vessel loaded its prior cargo.

Type:

str

last_port_departed_at

The UTC timestamp of when the vessel departed its prior load port.

Type:

str

last_load_port_id

The Oceanbolt port id of the port where the vessel loaded its prior cargo.

Type:

int

commodity_group

Name of the commodity group.

Type:

str

commodity

Name of the commodity.

Type:

str

volume

Volume of the cargo onboard the vessel.

Type:

float

lat

Not implemented.

Type:

google.protobuf.wrappers_pb2.DoubleValue

lng

Not implemented.

Type:

google.protobuf.wrappers_pb2.DoubleValue

course

Not implemented.

Type:

google.protobuf.wrappers_pb2.DoubleValue

speed

Not implemented.

Type:

google.protobuf.wrappers_pb2.DoubleValue

laden_status

Current laden status of the vessel (laden or ballast).

Type:

str