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