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

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

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]

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

Sequence[str]

laden_status

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

Type

Sequence[str]

port_status

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

Type

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

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

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