Congestion Timeseries

Retrieve timeseries data of how many vessels are congested 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:

  • How many VLOCs are currently congested in Brazil waiting to load?

  • What is the average waiting time for vessels currently congested in China waiting to discharge Australian coal and how has that changed in the past year?

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

The CongestionTimeseries returns timeseries on congestion, including data on number of congested vessels, congested dwt, waiting times etc.

get(**kwargs)[source]

Retrieves congested timeseries as a pandas.DataFrame

Example

How many vessels are currently congested in China waiting to discharge Australian coal and how has that changed in the past year?

from oceanbolt.sdk.client import APIClient
from oceanbolt.sdk.data.congestion import CongestionTimeseries
from datetime import date

base_client = APIClient("<token>")
df = CongestionTimeseries(base_client).get(
    country_code=['CN'],
    last_load_country_code=['AU'],
    commodity_group = ['coal'],
    start_date=date(2020,1,1),
)

Returns:

”date”

group

vessel_count

vessel_dwt

average_waiting_days

median_waiting_days

2021-02-19

default

50

5586544

137.782971

131.122540

2021-02-18

default

50

5674628

134.318293

130.122540

2021-02-17

default

50

5674628

136.004659

129.122540

2021-02-16

default

51

5726315

132.450734

127.651956

2021-02-15

default

53

6074773

130.864687

126.651956

2021-02-14

default

51

5811030

134.971958

126.593125

2021-02-13

default

53

5984440

129.094691

124.651956

2021-02-12

default

55

6152710

131.408019

124.593125

2021-02-11

default

54

6101023

132.827528

123.695417

2021-02-10

default

53

6009144

134.321403

122.797708

2021-02-09

default

57

6356727

136.738331

122.753090

2021-02-08

default

58

6449928

135.311120

121.275399

2021-02-07

default

58

6308928

132.075676

120.275399

2021-02-06

default

57

6227397

135.695934

119.753090

2021-02-05

default

58

6407697

132.385083

118.275399

2021-02-04

default

58

6368678

134.732518

118.046233

2021-02-03

default

57

6284059

135.497696

117.339375

2021-02-02

default

57

6284059

136.874849

116.339375

2021-02-01

default

56

6190825

138.306718

116.255741

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

Congestion timeseries row object.

date

UTC date timestamp of the timeseries row.

Type:

str

vessel_count

Number of vessels that were congested on the date.

Type:

google.protobuf.wrappers_pb2.Int32Value

vessel_dwt

Sum of DWT that were congested on the date.

Type:

google.protobuf.wrappers_pb2.DoubleValue

avg_waiting_days

Average waiting days of vessels that were congested on the date.

Type:

google.protobuf.wrappers_pb2.DoubleValue

median_waiting_days

Median waiting days of vessels that were congested on the date.

Type:

google.protobuf.wrappers_pb2.DoubleValue

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

Congestion timeseries group object.

group

Name of the group. This will be “default”, if no grouping was specified in the query.

Type:

str

rows

Rows of timeseries data.

Type:

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