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

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.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

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