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
PortCallTimeseriesreturns a timeseries data on historical number of port calls.
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
- 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
- max_results
An optional limit for the number of resources returned in a single call.
- Type
- format_
The return format of the data [“csv”,”json”, “xlsx”]. Default is “json”.
- Type
- 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
- end_date
The UTC end date of the date filter.
- Type
- 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
- group_by
Determines the grouping of the timeseries data. This parameter only applies to the /portcalls/timeseries endpoint.
- Type
- 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
- 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
- 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]
- 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
- group_value
Helper variable to calculate top groups. Not returned.
- rows
Rows of timeseries data.
- Type
MutableSequence[oceanbolt.com.portcalls_v3.types.TimeseriesRow]