Zone Changes

Find timeseries data on the number of zone changes (zone crossings) during a given period, while filtering on zone id or vessel segment.

Example questions that can be answered with this endpoint:

How many panamax vessels have crossed from the Indian Ocean into the Atlantic on a weekly basis in the past 3 months?
How many vessels have entered the Mediterranean in the past 7 days

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

The ZoneChangesTimeseries returns timeseries on tonnage movements and zone crossings.

get(**kwargs)[source]: Retrieves timeseries data as a pandas.DataFrame

Example

How many panamax vessels have crossed from the Indian Ocean into the Atlantic on a weekly basis in the past 3 months?

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

base_client = APIClient()
df = ZoneChangesTimeseries(base_client).get(
    start_date=date.today() - timedelta(days=90),
    frequency="weekly",
    segment=["panamax"],
    from_zone_id=[22, 13, 97, 96, 8], # zones corresponding to the indian ocean
    to_zone_id=[9, 58, 42, 7, 15], # zones corresponding to the atlantic
)

Returns:

date	vessel_count	vessel_dwt
2020-11-23	25	1231235
2020-11-30	27	1350000
2020-12-07	40	1358413
2020-12-14	20	1128648
2020-12-21	26	1121358
2020-12-28	26	9113258
2021-01-04	31	4561430
2021-01-11	30	1231235
2021-01-18	51	1231235
2021-01-25	45	4684686
2021-02-01	61	6486450
2021-02-08	64	4664350
2021-02-15	50	4241450
2021-02-22	21	5231235

Arguments

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

Request object for TonnageZoneChange

from_zone_id

Type: MutableSequence[int]

to_zone_id

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]

laden_status

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

Type: MutableSequence[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

group_by

Determines the grouping of the timeseries data.

Type: str

sort

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

Type: str

format_

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

Type: str

frequency

Frequency determines the granularity/period grouping of the timeseries. Allowed values are: [“daily”, “weekly”, “monthly”,”quarterly “yearly”]. Default value is “monthly”.

Type: str

vessel_filter

Specifies vessel parameters to filter on.

Type: oceanbolt.com.ptypes.filters.vessel_filter_pb2.VesselFilter

Response

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

Response object for TonnageZoneChange

timeseries

Timeseries data groups.

Type: MutableSequence[oceanbolt.com.tonnage_v3.types.ZoneChangesTimeseriesGroup]

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.ZoneChangesTimeseriesGroup(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.ZoneChangesTimeseriesRow]

class oceanbolt.com.tonnage_v3.types.ZoneChangesTimeseriesRow(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