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: 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:: MutableSequence[int]

port_id

List of Oceanbolt port ids to filter on.

Type:: MutableSequence[int]

berth_id

List of Oceanbolt berth ids to filter on.

Type:: MutableSequence[int]

unlocode

List of five letter UNLOCODEs of ports to filter on.

Type:: MutableSequence[str]

country_code

List of two letter ISO country codes to filter on.

Type:: MutableSequence[str]

region

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

Type:: MutableSequence[str]

basin

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

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

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:: MutableSequence[str]

commodity_group

List of commodity groups to get data for (get a list of all commodity groups from /entities/commodities).

Type:: MutableSequence[str]

operation

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

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

vessel_filter

Specifies vessel parameters to filter on.

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

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