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

Sequence[int]

to_zone_id
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]

laden_status

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

Type

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

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

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

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