Port Call Timeseries

Find aggregate counts of port calls 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 vessels have called the port of Santos in the past year grouped by segment?

  • How many port calls have been completed in the Atlantic vs the Pacific each week over the last 3 years?

  • How many panamax vessels have discharged coal in China in the past month?

class oceanbolt.sdk.data.port_calls.PortCallTimeseries(client: oceanbolt.sdk.client.APIClient)[source]

The PortCallTimeseries returns a timeseries data on historical number of port calls.

get(**kwargs)[source]

Retrieves timeseries data as a pandas.DataFrame

Example

How many handysize vessels have called the port of Santos on a weekly basis in the past year?

from oceanbolt.sdk.client import APIClient
from oceanbolt.sdk.data.port_calls import PortCallTimeseries
from datetime import date


base_client = APIClient("<token>")
df = PortCallTimeseries(base_client).get(
    frequency="weekly",
    group_by="segment",
    unlocode=['BRSSZ'],
    start_date=date(2020, 1, 1),
    end_date=date(2020, 12, 31),
)

Returns:

date

group

value

2019-12-30

Panamax

4

2020-01-06

Panamax

8

2020-01-13

Panamax

7

2020-01-20

Panamax

11

2020-01-27

Panamax

14

2020-02-03

Panamax

14

2020-02-10

Panamax

24

2020-02-17

Panamax

21

2020-02-24

Panamax

16

2019-12-30

Supramax

7

2020-01-06

Supramax

16

2020-01-13

Supramax

8

2020-01-20

Supramax

10

2020-01-27

Supramax

11

2020-02-03

Supramax

6

2020-02-10

Supramax

15

2020-02-17

Supramax

7

2020-02-24

Supramax

5

2019-12-30

Handysize

3

2020-01-06

Handysize

5

2020-01-13

Handysize

9

2020-01-20

Handysize

8

2020-01-27

Handysize

6

2020-02-03

Handysize

11

2020-02-10

Handysize

6

2020-02-17

Handysize

7

2020-02-24

Handysize

5

Arguments

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

Port calls data requests object. This is shared between all port calls queries

imo

List of unique vessel identifiers (IMO numbers). This allows filtering to show data only for a subset of vessels. Example: [1234567,7654321].

Type

Sequence[int]

port_id

List of Oceanbolt port ids to filter on.

Type

Sequence[int]

berth_id

List of Oceanbolt berth ids to filter on.

Type

Sequence[int]

unlocode

List of five letter UNLOCODEs of ports to filter on.

Type

Sequence[str]

country_code

List of two letter ISO country codes to filter on.

Type

Sequence[str]

region

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

Type

Sequence[str]

basin

List of basins to filter on. Allowed values are: [“atlantic”,”indian_ocean”,”pacific_americas”,”pacific_asia”].

Type

Sequence[str]

latest_only

Flat to indiciate whether only the latest port call should be included on an IMO basis. If this is enabled, only the latest port call for each imo passing the filter will be returned.

Type

bool

next_token

The pagination token specifying which page of results to return in the response. If no token is provided, the default page is the first page.

Type

str

max_results

An optional limit for the number of resources returned in a single call.

Type

int

format_

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

Type

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]

start_date

The UTC start date of the date filter.

Type

str

end_date

The UTC end date of the date filter.

Type

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]

operation

List of port call operation types to filter on. Allowed values are: **[“D”,”Dx”;”L”,”Lx”,”B”,”Y”,”U”].

Type

Sequence[str]

sort

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

Type

str

group_by

Determines the grouping of the timeseries data. This parameter only applies to the /portcalls/timeseries endpoint.

Type

str

frequency

Frequency determines the granularity/period grouping of the timeseries. Allowed values are: [“daily”, “weekly”, “monthly”,”quarterly “yearly”]. Default value is “monthly”. This parameter only applies to the /portcalls/timeseries endpoint.

Type

str

limit_groups

Flag to indicate whether grouped timeseries should be limited to top N entries. If the parameter is present, the endpoint will only return the top N groups, and the remaining entries will be grouped into others.

Type

bool

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

Response object for port call timeseries queries

timeseries

Timeseries data groups.

Type

Sequence[oceanbolt.com.portcalls_v3.types.TimeseriesGroup]

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

Port call timeseries group

group

Name of the group. This will be “default”, if no grouping was specified in the query.

Type

str

group_value

Helper variable to calculate top groups. Not returned.

Type

google.protobuf.wrappers_pb2.DoubleValue

rows

Rows of timeseries data.

Type

Sequence[oceanbolt.com.portcalls_v3.types.TimeseriesRow]

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

Port call timeseries row

date

UTC date timestamp of the timeseries row.

Type

str

value

The value of the timeseries row.

Type

google.protobuf.wrappers_pb2.DoubleValue