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: oceanbolt.sdk.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

Sequence[int]

port_unlocode

List of five letter UNLOCODEs for to filter on.

Type

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

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

Sequence[str]

operation

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

Type

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

laden_status

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

Type

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

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

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

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

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

Sequence[float]

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

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

current_top_sub_segments

List of top segments by amount of congested.

Type

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

current_top_commodity_groups

List of top commodities by amount of congested.

Type

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

current_top_load_countries

List of top countries by amount of congested.

Type

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

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

timeseries

Congestion timeseries response.

Type

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