Tonnage Zone Counts

Find aggregated vessel counts for various vessels segments, various laden status, various directions or various zones.

Example questions that can be answered with this endpoint:

  • How many ballast ultramax or supramax vessels are currently in the Indian Ocean?

  • How many panamaxes are currently in the atlantic vs the pacific and how has this changed over time?

class oceanbolt.sdk.data.tonnage.TonnageZoneTimeseries(client: APIClient)[source]

The TonnageZoneTimeseries returns timeseries on zone counts.

get(**kwargs)[source]

Retrieves timeseries data as a pandas.DataFrame

Example

How many ballast ultramax or supramax vessels are currently in the Indian Ocean?

from oceanbolt.sdk.client import APIClient
from oceanbolt.sdk.data.tonnage import TonnageZoneTimeseries
from datetime import date


base_client = APIClient("<token>")
df = TonnageZoneTimeseries(base_client).get(
    sub_segment=['ultramax','supramax'],
    laden_status=["ballast"],
    zone_id=[22, 13, 97, 96, 8], #Zone Ids can be obtained from the zone selector map in the Oceanbolt App or from the entities/zones endpoint.

)

Returns:

date

vessel_count

vessel_dwt

2021-02-01

161

9384746

2021-02-02

161

9385891

2021-02-03

167

9707184

2021-02-04

165

9590778

2021-02-05

161

9367220

2021-02-06

161

9353406

2021-02-07

160

9312805

2021-02-08

152

8829415

2021-02-09

149

8637758

2021-02-10

150

8698294

2021-02-11

152

8811801

2021-02-12

156

9084444

2021-02-13

160

9320787

2021-02-14

157

9155971

2021-02-15

157

9180257

2021-02-16

157

9144834

2021-02-17

154

8964411

2021-02-18

153

8904227

2021-02-19

153

8904227

Arguments

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

Request object for getting tonnage zone data and fleet speed data.

zone_id

List of zones ids to filter on. Allowed values can be obtained from the /entities/zones endpoint.

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]

direction

The list of directions to get tonnage data for. The following directions are allowed: [“NNE”,”ENE”,”ESE”,”SSE”,”SSW”,”WSW”,”WNW”,”NNW”]. Directions can also be obtained from the interactive direction selector found at app.oceanbolt.com.

Type:

MutableSequence[str]

laden_status

The laden status to get tonnage data for. The following values are allowed: [“laden”,”ballast”].

Type:

MutableSequence[str]

port_status

The port status to get tonnage data for. The following values are allowed: [“in_port”,”at_sea”].

Type:

MutableSequence[str]

group_by

Not Implemented Yet //TODO

Type:

str

exclude_mpv

Flag to specify whether or not MPV vessels should be included/excluded. Default is to include.

Type:

bool

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.

Type:

int

format_

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

Type:

str

sort

Specifies whether results should be sorted in ascending or descing order. Allowed values: [“asc”,”desc”].

Type:

str

Response

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

Response object for tonnage zone counts

timeseries

Timeseries data groups.

Type:

MutableSequence[oceanbolt.com.tonnage_v3.types.TonnageTimeseriesGroup]

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

Tonnage zone/fleet speed timeseries group

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.tonnage_v3.types.TonnageTimeseriesRow]

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

Tonnage zone/fleet speed timeseries row.

date

UTC date timestamp of the timeseries row.

Type:

str

vessel_count

The number of vessels for the timeseries row.

Type:

google.protobuf.wrappers_pb2.Int32Value

vessel_dwt

The sum of dwt for the timeseries row.

Type:

google.protobuf.wrappers_pb2.DoubleValue

avg_speed

The average speed in knots for the timeseries row.

Type:

google.protobuf.wrappers_pb2.DoubleValue