Skip to content

Package Documentation

âš  Deprecation Warning

This package is deprecated and will be removed in a future version of the SDK. Please use the tonnage_list package instead.

Historical Tonnage List API Package.

Classes:

Name Description
HistoricalTonnageListAPI

Represents Signal's Historical Tonnage List API.
HistoricalTonnageList

Result of a Historical Tonnage List query.
TonnageList

A singular tonnage list in HistoricalTonnageList.
Vessel

A vessel contained in a TonnageList.
VesselFilter

Used for filtering vessels in queries.
PushType

Contains constants for available push types.
MarketDeployment

Contains constants for available market deployments.
CommercialStatus

Contains constants for available commercial statuses.
VesseSubclass

Contains constants for available vessel subclasses.
LocationTaxonomy

Contains constants for available location taxonomies.
Area

A geographical area.
Column

Contains constants for available data frame column names.
IndexLevel

Contains constants for available data frame index levels.
OperationalStatus

Contains constants for available operational statuses.
FixtureType

Contains constants for available fixture types.

Area dataclass

A geographical area.

Attributes:

Name Type Description
name str

The area name.
location_taxonomy str

The area's location taxonomy. See the LocationTaxonomy class for available values.
Source code in signal_ocean/historical_tonnage_list/area.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
@dataclass(frozen=True)
class Area:
    """A geographical area.

    Attributes:
        name: The area name.
        location_taxonomy: The area's location taxonomy. See the
            LocationTaxonomy class for available values.
    """
    name: str
    location_taxonomy: str

Column

Contains constants for data frame column names.

Source code in signal_ocean/historical_tonnage_list/column.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
class Column(metaclass=IterableConstants):
    """Contains constants for data frame column names."""

    NAME = "name"
    VESSEL_CLASS = _category("vessel_class")
    ICE_CLASS = _category("ice_class")
    YEAR_BUILT = "year_built"
    DEADWEIGHT = "deadweight"
    LENGTH_OVERALL = "length_overall"
    BREADTH_EXTREME = "breadth_extreme"
    SUBCLASS = _category("subclass")
    MARKET_DEPLOYMENT = _category(_pit_col("market_deployment"))
    PUSH_TYPE = _category(_pit_col("push_type"))
    OPEN_PORT = _category(_pit_col("open_port"))
    OPEN_DATE = _pit_col("open_date")
    OPERATIONAL_STATUS = _category(_pit_col("operational_status"))
    COMMERCIAL_OPERATOR = _category(_pit_col("commercial_operator"))
    COMMERCIAL_STATUS = _category(_pit_col("commercial_status"))
    ETA = _pit_col("eta")
    LATEST_AIS = _pit_col("latest_ais")
    OPEN_PREDICTION_ACCURACY = _category(_pit_col("open_prediction_accuracy"))
    OPEN_COUNTRY = _category(_pit_col("open_country"))
    OPEN_NARROW_AREA = _category(_pit_col("open_narrow_area"))
    OPEN_WIDE_AREA = _category(_pit_col("open_wide_area"))
    AVAILABILITY_PORT_TYPE = _category(_pit_col("availability_port_type"))
    AVAILABILITY_DATE_TYPE = _category(_pit_col("availability_date_type"))

    @staticmethod
    def _create_row(vessel: Vessel) -> List[Any]:
        return [
            vessel.name,
            vessel.vessel_class,
            vessel.ice_class,
            vessel.year_built,
            vessel.deadweight,
            vessel.length_overall,
            vessel.breadth_extreme,
            vessel.subclass,
            vessel.market_deployment,
            vessel.push_type,
            vessel.open_port,
            vessel.open_date,
            vessel.operational_status,
            vessel.commercial_operator,
            vessel.commercial_status,
            vessel.eta,
            vessel.latest_ais,
            vessel.open_prediction_accuracy,
            vessel.open_country,
            vessel.open_narrow_area,
            vessel.open_wide_area,
            vessel.availability_port_type,
            vessel.availability_date_type
        ]

    @staticmethod
    def _get_data_types() -> Dict[str, str]:
        return _data_types

CommercialStatus

Contains constants for available commercial statuses.

Source code in signal_ocean/historical_tonnage_list/commercial_status.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
class CommercialStatus(metaclass=IterableConstants):
    """Contains constants for available commercial statuses."""
    ON_SUBS = 'On Subs'
    """
    Vessel is On Subs for a new Fixture.
    """
    FAILED = 'Failed'
    """
    Last fixture failed for this Vessel.
    """
    CANCELLED = 'Cancelled'
    """
    Last fixture cancelled for this Vessel.
    """
    AVAILABLE = 'Available'
    """
    Vessel is available for a new voyage after her open date.
    """
    POTENTIALLY_FIXED = 'Poss Fixed'
    """
    Systems assumes the vessel is fixed for her new voyage based
        on AIS information
    """

AVAILABLE = 'Available' class-attribute instance-attribute

Vessel is available for a new voyage after her open date.

CANCELLED = 'Cancelled' class-attribute instance-attribute

Last fixture cancelled for this Vessel.

FAILED = 'Failed' class-attribute instance-attribute

Last fixture failed for this Vessel.

ON_SUBS = 'On Subs' class-attribute instance-attribute

Vessel is On Subs for a new Fixture.

POTENTIALLY_FIXED = 'Poss Fixed' class-attribute instance-attribute

Systems assumes the vessel is fixed for her new voyage based on AIS information

FixtureType

Contains constants for available fixture types.

Source code in signal_ocean/historical_tonnage_list/fixture_type.py 
 6
 7
 8
 9
10
class FixtureType(metaclass=IterableConstants):
    """Contains constants for available fixture types."""
    SCRAPED = 'Scraped'
    MANUAL = 'Manual'
    IMPLIED = 'Implied'

HistoricalTonnageList

Bases: Sequence[TonnageList]

The class that represents a Historical Tonnage List.

A Historical Tonnage List consists from an collection of Tonnage Lists one for every day between the start and end date specified when querying the Historica Tonnage List API.

Source code in signal_ocean/historical_tonnage_list/historical_tonnage_list.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
class HistoricalTonnageList(Sequence[TonnageList]):
    """The class that represents a Historical Tonnage List.

    A Historical Tonnage List consists from an collection of Tonnage Lists
    one for every day between the start and end date specified
    when querying the Historica Tonnage List API.
    """

    def __init__(self, tonnage_lists: Iterable[TonnageList]):
        """Initializes the Historical Tonnage List.

        Args:
            tonnage_lists: Tonnage Lists contained within the Historical
                Tonnage List.
        """
        self.__tonnage_lists = tuple(tonnage_lists)

    @overload
    def __getitem__(self, index: int) -> TonnageList:  # noqa: D105
        ...

    @overload
    def __getitem__(self, slice: slice) -> Sequence[TonnageList]:  # noqa: D105
        ...

    def __getitem__(
        self, i: Union[int, slice]
    ) -> Union[TonnageList, Sequence[TonnageList]]:  # noqa: D105
        return self.__tonnage_lists.__getitem__(i)

    def __len__(self) -> int:  # noqa: D105
        return self.__tonnage_lists.__len__()

    def __repr__(self) -> str:  # noqa: D105
        class_name = self.__class__.__name__
        return f"{class_name}(tonnage_lists={self.__tonnage_lists!r})"

    def to_data_frame(self) -> pd.DataFrame:
        """Converts the Historical Tonnage List to a pandas data frame."""
        index_tuples = []
        data = []
        for tonnage_list in self.__tonnage_lists:
            for vessel in tonnage_list.vessels:
                index_tuples.append((tonnage_list.date, vessel.imo))
                data.append(Column._create_row(vessel))

        data_frame = pd.DataFrame(
            data,
            index=pd.MultiIndex.from_tuples(
                index_tuples, names=[IndexLevel.DATE, IndexLevel.IMO]
            ),
            columns=list(Column),
        )

        return data_frame.astype(Column._get_data_types())  # type: ignore

__init__(tonnage_lists)

Initializes the Historical Tonnage List.

Parameters:

Name Type Description Default
tonnage_lists Iterable[TonnageList]

Tonnage Lists contained within the Historical Tonnage List.

 required
Source code in signal_ocean/historical_tonnage_list/historical_tonnage_list.py 
20
21
22
23
24
25
26
27
def __init__(self, tonnage_lists: Iterable[TonnageList]):
    """Initializes the Historical Tonnage List.

    Args:
        tonnage_lists: Tonnage Lists contained within the Historical
            Tonnage List.
    """
    self.__tonnage_lists = tuple(tonnage_lists)

to_data_frame()

Converts the Historical Tonnage List to a pandas data frame.

Source code in signal_ocean/historical_tonnage_list/historical_tonnage_list.py 
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
def to_data_frame(self) -> pd.DataFrame:
    """Converts the Historical Tonnage List to a pandas data frame."""
    index_tuples = []
    data = []
    for tonnage_list in self.__tonnage_lists:
        for vessel in tonnage_list.vessels:
            index_tuples.append((tonnage_list.date, vessel.imo))
            data.append(Column._create_row(vessel))

    data_frame = pd.DataFrame(
        data,
        index=pd.MultiIndex.from_tuples(
            index_tuples, names=[IndexLevel.DATE, IndexLevel.IMO]
        ),
        columns=list(Column),
    )

    return data_frame.astype(Column._get_data_types())  # type: ignore

HistoricalTonnageListAPI

Handles communications with Signal's Historical Tonnage List API.

Source code in signal_ocean/historical_tonnage_list/historical_tonnage_list_api.py 
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
class HistoricalTonnageListAPI:
    """Handles communications with  Signal's Historical Tonnage List API."""

    __MAX_DATE_RANGE_DAYS = 365

    def __init__(self, connection: Optional[Connection] = None):
        """Initializes HistoricalTonnageListAPI.

        Args:
            connection: API connection configuration. If not provided, the
                default connection method is used.
        """
        self.__connection = connection or Connection()

    def get_historical_tonnage_list(
        self,
        loading_port: Port,
        vessel_class: VesselClass,
        laycan_end_in_days: Optional[int] = None,
        start_date: Optional[date] = None,
        end_date: Optional[date] = None,
        time: Optional[time] = None,
        vessel_filter: Optional[VesselFilter] = None,
    ) -> HistoricalTonnageList:
        """Retrieves a Historical Tonnage List.

        If no input dates are provided, the last 10 days will be fetched
        (including today).

        To get a tonnage list for a specific day, set both date parameters to
        the desired date.

        Args:
            loading_port: The loading port from which ETA will be calculated.
            vessel_class: The vessel class to calculate the tonnage lists.
            laycan_end_in_days: The maximum ETA expressed as a number of days
                after the end date.
            start_date: The date of the earliest tonnage list in the response.
            end_date: The date of the latest tonnage list in the response.
            time: Specifies the UTC time of day for which the state of
                the tonnage lists will be retrieved.
                It can get the values 00, 06, 12, 18.
            vessel_filter: A filter defining which vessels should be included
                in the response see Vessel Filter class for more details.

        Returns:
            Given a time-range, returns a Historical Tonnage List containing a
            Tonnage List for every day between the start and end dates, at the
            requested time of day.
        """
        all_tonnage_lists: List[TonnageList] = []
        date_ranges = _DateRange(start_date, end_date).split(
            HistoricalTonnageListAPI.__MAX_DATE_RANGE_DAYS
        )

        for date_range in date_ranges:
            tonnage_lists = self._get_htl_chunk(
                loading_port,
                vessel_class,
                date_range,
                laycan_end_in_days,
                time,
                vessel_filter,
            )
            all_tonnage_lists.extend(tonnage_lists)

        return HistoricalTonnageList(all_tonnage_lists)

    def _get_htl_chunk(
        self,
        loading_port: Port,
        vessel_class: VesselClass,
        date_range: _DateRange,
        laycan_end_in_days: Optional[int] = None,
        time: Optional[time] = None,
        vessel_filter: Optional[VesselFilter] = None,
    ) -> Iterable[TonnageList]:
        query_string: QueryString = {
            "loadingPort": loading_port.id,
            "vesselClass": vessel_class.id,
            "laycanEndInDays": laycan_end_in_days,
            "startDate": format_iso_date(date_range.start),
            "endDate": format_iso_date(date_range.end),
            "time": time.strftime("%H:%M") if time else None,
            **(vessel_filter._to_query_string() if vessel_filter else {}),
        }

        response = self.__connection._make_get_request(
            "htl-api/historical-tonnage-list/", query_string
        )

        response.raise_for_status()
        return _historical_tonnage_list_json.parse_tonnage_lists(
            response.json()
        )

__init__(connection=None)

Initializes HistoricalTonnageListAPI.

Parameters:

Name Type Description Default
connection Optional[Connection]

API connection configuration. If not provided, the default connection method is used.

 None
Source code in signal_ocean/historical_tonnage_list/historical_tonnage_list_api.py 
45
46
47
48
49
50
51
52
def __init__(self, connection: Optional[Connection] = None):
    """Initializes HistoricalTonnageListAPI.

    Args:
        connection: API connection configuration. If not provided, the
            default connection method is used.
    """
    self.__connection = connection or Connection()

get_historical_tonnage_list(loading_port, vessel_class, laycan_end_in_days=None, start_date=None, end_date=None, time=None, vessel_filter=None)

Retrieves a Historical Tonnage List.

If no input dates are provided, the last 10 days will be fetched (including today).

To get a tonnage list for a specific day, set both date parameters to the desired date.

Parameters:

Name Type Description Default
loading_port Port

The loading port from which ETA will be calculated.

 required
vessel_class VesselClass

The vessel class to calculate the tonnage lists.

 required
laycan_end_in_days Optional[int]

The maximum ETA expressed as a number of days after the end date.

 None
start_date Optional[date]

The date of the earliest tonnage list in the response.

 None
end_date Optional[date]

The date of the latest tonnage list in the response.

 None
time Optional[time]

Specifies the UTC time of day for which the state of the tonnage lists will be retrieved. It can get the values 00, 06, 12, 18.

 None
vessel_filter Optional[VesselFilter]

A filter defining which vessels should be included in the response see Vessel Filter class for more details.

 None

Returns:

Type Description
HistoricalTonnageList

Given a time-range, returns a Historical Tonnage List containing a
HistoricalTonnageList

Tonnage List for every day between the start and end dates, at the
HistoricalTonnageList

requested time of day.
Source code in signal_ocean/historical_tonnage_list/historical_tonnage_list_api.py 
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def get_historical_tonnage_list(
    self,
    loading_port: Port,
    vessel_class: VesselClass,
    laycan_end_in_days: Optional[int] = None,
    start_date: Optional[date] = None,
    end_date: Optional[date] = None,
    time: Optional[time] = None,
    vessel_filter: Optional[VesselFilter] = None,
) -> HistoricalTonnageList:
    """Retrieves a Historical Tonnage List.

    If no input dates are provided, the last 10 days will be fetched
    (including today).

    To get a tonnage list for a specific day, set both date parameters to
    the desired date.

    Args:
        loading_port: The loading port from which ETA will be calculated.
        vessel_class: The vessel class to calculate the tonnage lists.
        laycan_end_in_days: The maximum ETA expressed as a number of days
            after the end date.
        start_date: The date of the earliest tonnage list in the response.
        end_date: The date of the latest tonnage list in the response.
        time: Specifies the UTC time of day for which the state of
            the tonnage lists will be retrieved.
            It can get the values 00, 06, 12, 18.
        vessel_filter: A filter defining which vessels should be included
            in the response see Vessel Filter class for more details.

    Returns:
        Given a time-range, returns a Historical Tonnage List containing a
        Tonnage List for every day between the start and end dates, at the
        requested time of day.
    """
    all_tonnage_lists: List[TonnageList] = []
    date_ranges = _DateRange(start_date, end_date).split(
        HistoricalTonnageListAPI.__MAX_DATE_RANGE_DAYS
    )

    for date_range in date_ranges:
        tonnage_lists = self._get_htl_chunk(
            loading_port,
            vessel_class,
            date_range,
            laycan_end_in_days,
            time,
            vessel_filter,
        )
        all_tonnage_lists.extend(tonnage_lists)

    return HistoricalTonnageList(all_tonnage_lists)

IndexLevel

Contains constants for available data frame index levels.

Source code in signal_ocean/historical_tonnage_list/index_level.py 
6
7
8
9
class IndexLevel(metaclass=IterableConstants):
    """Contains constants for available data frame index levels."""
    DATE = 'date'
    IMO = 'imo'

LocationTaxonomy

Contains constants for available location taxonomies.

Source code in signal_ocean/historical_tonnage_list/location_taxonomy.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
class LocationTaxonomy(metaclass=IterableConstants):
    """Contains constants for available location taxonomies."""
    PORT = 'Port'
    """
    Location Taxonomy Port.
    """
    COUNTRY = 'Country'
    """
    Location Taxonomy Country.
    """
    NARROW_AREA = 'Narrow Area'
    """
    Location Taxonomy Narrow Area.
    """
    WIDE_AREA = 'Wide Area'
    """
    Location Taxonomy Wide Area.
    """

COUNTRY = 'Country' class-attribute instance-attribute

Location Taxonomy Country.

NARROW_AREA = 'Narrow Area' class-attribute instance-attribute

Location Taxonomy Narrow Area.

PORT = 'Port' class-attribute instance-attribute

Location Taxonomy Port.

WIDE_AREA = 'Wide Area' class-attribute instance-attribute

Location Taxonomy Wide Area.

MarketDeployment

Contains constants for available market deployments.

Source code in signal_ocean/historical_tonnage_list/market_deployment.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
class MarketDeployment(metaclass=IterableConstants):
    """Contains constants for available market deployments."""
    SPOT = 'Spot'
    '''
    Vessels controlled by commercial operators that participate in the
    spot market and are advertised through Tonnage lists and
    get reported fixtures
    '''
    PROGRAM = 'Program'
    '''
    Vessels controlled by charterers like
    that do not participate in the spot market and
    are either not advertised through Tonnage lists or
    Tonnage lists report the fact that they are program
    '''
    RELET = 'Relet'
    '''
    Vessels controlled by charterers that participate in the spot market
    and are advertised through Tonnage lists and get reported fixtures
    '''
    CONTRACT = 'Contract'
    '''
    Vessels controlled by commercial operators that do not participate
    in the spot market and are typically
    doing system cargoes with repetitive trading patterns.
    '''

CONTRACT = 'Contract' class-attribute instance-attribute

Vessels controlled by commercial operators that do not participate in the spot market and are typically doing system cargoes with repetitive trading patterns.

PROGRAM = 'Program' class-attribute instance-attribute

Vessels controlled by charterers like that do not participate in the spot market and are either not advertised through Tonnage lists or Tonnage lists report the fact that they are program

RELET = 'Relet' class-attribute instance-attribute

Vessels controlled by charterers that participate in the spot market and are advertised through Tonnage lists and get reported fixtures

SPOT = 'Spot' class-attribute instance-attribute

Vessels controlled by commercial operators that participate in the spot market and are advertised through Tonnage lists and get reported fixtures

OperationalStatus

Contains constants for available operational statuses.

Source code in signal_ocean/historical_tonnage_list/operational_status.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
class OperationalStatus(metaclass=IterableConstants):
    """Contains constants for available operational statuses."""
    BALLAST_FIXED = "Ballast Fixed"
    '''
    Vessel is currently empty of cargo but fixed forward
    '''
    REPAIRS = "Repairs"
    '''
    Vessel is undergoing repairs or Drydock.
    '''
    WAITING_TO_LOAD = "Waiting to Load"
    '''
    Vessel is waiting to load
    '''
    LOADING = "Loading"
    '''
    Vessel is loading, i.e. it has entered a Jetty or is performing STS
    '''
    LADEN = "Laden"
    '''
    Vesel has loaded
    '''
    WAITING_TO_DISCHARGE = "Waiting to Discharge"
    '''
    Vessel is waiting to Discharge
    '''
    DISCHARGING = "Discharging"
    '''
    Vessel is discharging, i.e. it has entered a Jetty or is performing STS
    '''
    ACTIVE_STORAGE = "Active Storage"
    '''
    Vessel is in active storage.
    This means it acts as storage for a
    short term (compared to storage vessels).
    '''
    BALLAST_UNFIXED = "Ballast Unfixed"
    '''
    Vessel is currently free of cargo and not fixed (prompt)
    '''
    BALLAST_FIXED_IMPLIED = "Ballast Fixed (implied)"
    '''
    Vessel is currently free of cargo and her AIS destination implies a fixture
    '''

ACTIVE_STORAGE = 'Active Storage' class-attribute instance-attribute

Vessel is in active storage. This means it acts as storage for a short term (compared to storage vessels).

BALLAST_FIXED = 'Ballast Fixed' class-attribute instance-attribute

Vessel is currently empty of cargo but fixed forward

BALLAST_FIXED_IMPLIED = 'Ballast Fixed (implied)' class-attribute instance-attribute

Vessel is currently free of cargo and her AIS destination implies a fixture

BALLAST_UNFIXED = 'Ballast Unfixed' class-attribute instance-attribute

Vessel is currently free of cargo and not fixed (prompt)

DISCHARGING = 'Discharging' class-attribute instance-attribute

Vessel is discharging, i.e. it has entered a Jetty or is performing STS

LADEN = 'Laden' class-attribute instance-attribute

Vesel has loaded

LOADING = 'Loading' class-attribute instance-attribute

Vessel is loading, i.e. it has entered a Jetty or is performing STS

REPAIRS = 'Repairs' class-attribute instance-attribute

Vessel is undergoing repairs or Drydock.

WAITING_TO_DISCHARGE = 'Waiting to Discharge' class-attribute instance-attribute

Vessel is waiting to Discharge

WAITING_TO_LOAD = 'Waiting to Load' class-attribute instance-attribute

Vessel is waiting to load

PushType

Contains constants for available push types.

Source code in signal_ocean/historical_tonnage_list/push_type.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
class PushType(metaclass=IterableConstants):
    """Contains constants for available push types."""
    NOT_PUSHED = 'Not Pushed'
    '''
    vessels not pushed anymore
    '''
    PUSHED_POSS = 'Pushed POSS'
    '''
    Actively pushed in the market with notification Poss (Possibly)
    meaning that this is a broker projection
    '''
    PUSHED = 'Pushed'
    '''
    Actively pushed in the market through Tonnage lists or Positions lists
    '''

NOT_PUSHED = 'Not Pushed' class-attribute instance-attribute

vessels not pushed anymore

PUSHED = 'Pushed' class-attribute instance-attribute

Actively pushed in the market through Tonnage lists or Positions lists

PUSHED_POSS = 'Pushed POSS' class-attribute instance-attribute

Actively pushed in the market with notification Poss (Possibly) meaning that this is a broker projection

TonnageList dataclass

A tonnage list as it occurred at a certain point in time.

Attributes:

Name Type Description
date datetime

The date and time at which the tonnage list was captured.
vessels Tuple[Vessel, ...]

Vessels present in the tonnage list at the point in time
Source code in signal_ocean/historical_tonnage_list/tonnage_list.py 
10
11
12
13
14
15
16
17
18
19
20
@dataclass(frozen=True, eq=False)
class TonnageList:
    """A tonnage list as it occurred at a certain point in time.

    Attributes:
        date: The date and time at which the tonnage list was captured.
        vessels: Vessels present in the tonnage list at the point in time
        and their availability information. for more details see Vessel class.
    """
    date: datetime
    vessels: Tuple[Vessel, ...]

Vessel dataclass

Holds information for a vessel that participates in a tonnage list.

Contains both static vessel and point-in-time vessel data. All point in time data are annotated with the name _point_in_time when converted to data_frame, see column class for details

Attributes:

Name Type Description
imo int

The vessel's IMO number.
name str

The vessel's name.
vessel_class str

The vessel's class name.
ice_class Optional[str]

The vessel's ice class.
year_built int

The year the vessel has been built.
deadweight int

The vessel's deadweight.
length_overall float

The vessel's length overall.
breadth_extreme int

The vessel's breadth extreme.
market_deployment str

Market deployment of the vessel. Point in time property. See the MarketDeployment class for available values.
push_type str

Push type of the vessel. Point in time property. See the PushType class for available values.
open_port str

The vessel's open port name. Point in time property.
open_date Optional[datetime]

The vessel's open date. Point in time property.
operational_status str

Operational status of the vessel. Point in time property. See the OperationalStatus class for available values.
commercial_operator str

The vessel's commercial operator. Point in time property.
commercial_status str

Commercial status of the vessel. Point in time property. See the CommercialStatus class for available values.
eta Optional[datetime]

Estimated time of arrival. Point in time property.
latest_ais Optional[datetime]

Timestamp of the vessel's latest AIS information. Point in time property.
subclass str

The vessel's subclass. See the VesselSubclass class for available values.
willing_to_switch_subclass bool

Is the vessel willing to switch its subclass.
open_prediction_accuracy str

How accurate is the open prediction. Point in time property. i.e: if a source is specifying the port then prediction is given at port level. See the LocationTaxonomy class for available values.
open_areas Tuple[Area, ...]

A hierarchical collection of areas the vessel opens at used to filtering. Point in time property. i.e: if a vessel opens in Rotterdam you get as open areas "openAreas":[{"id":24758,"label":"Continent","taxonomy":4}, {"id":25016,"label":"UK Continent","taxonomy":5}, {"id":25025,"label":"Mediterranean / UK Continent","taxonomy":6}, {"id":25028,"label":"West","taxonomy":7}, {"id":173,"label":"Netherlands","taxonomy":3}]
availability_port_type str

If it says source it means that there is hard evidence for the specific prediction of Port, if it says prediction it means the system is predicting based on the algorithm. Point in time property.
availability_date_type str

If it says source it means that there is hard evidence for the specific prediction of the Open date, if it says prediction it means the system is predicting based on the algorithm. Point in time property.
Source code in signal_ocean/historical_tonnage_list/vessel.py 
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
@dataclass(frozen=True, eq=False)
class Vessel:
    """Holds information for a vessel that participates in a tonnage list.

    Contains both static vessel and point-in-time vessel data.
    All point in time data are annotated with the name _point_in_time
    when converted to data_frame, see column class for details

    Attributes:
        imo: The vessel's IMO number.
        name: The vessel's name.
        vessel_class: The vessel's class name.
        ice_class: The vessel's ice class.
        year_built: The year the vessel has been built.
        deadweight: The vessel's deadweight.
        length_overall: The vessel's length overall.
        breadth_extreme: The vessel's breadth extreme.
        market_deployment: Market deployment of the vessel.
             Point in time property.
             See the MarketDeployment class for available values.
        push_type: Push type of the vessel.
            Point in time property.
            See the PushType class for available values.
        open_port: The vessel's open port name.
            Point in time property.
        open_date: The vessel's open date.
            Point in time property.
        operational_status: Operational status of the vessel.
            Point in time property.
            See the OperationalStatus class for available values.
        commercial_operator: The vessel's commercial operator.
            Point in time property.
        commercial_status: Commercial status of the vessel.
            Point in time property.
            See the CommercialStatus class for available values.
        eta: Estimated time of arrival.
            Point in time property.
        latest_ais: Timestamp of the vessel's latest AIS information.
            Point in time property.
        subclass: The vessel's subclass.
            See the VesselSubclass class for available values.
        willing_to_switch_subclass: Is the vessel willing
            to switch its subclass.
        open_prediction_accuracy: How accurate is the open prediction.
            Point in time property. i.e: if a source is specifying the port
            then prediction is given at port level.
            See the LocationTaxonomy class for available values.
        open_areas: A hierarchical collection of areas the vessel opens
            at used to filtering.
            Point in time property.
            i.e: if a vessel opens in Rotterdam you get as open areas
            "openAreas":[{"id":24758,"label":"Continent","taxonomy":4},
            {"id":25016,"label":"UK Continent","taxonomy":5},
            {"id":25025,"label":"Mediterranean / UK Continent","taxonomy":6},
            {"id":25028,"label":"West","taxonomy":7},
            {"id":173,"label":"Netherlands","taxonomy":3}]
        availability_port_type: If it says source it means that there is
            hard evidence for the specific prediction of Port,
            if it says prediction it means the system is predicting
            based on the algorithm.
            Point in time property.
        availability_date_type: If it says source it means that there is
            hard evidence for
            the specific prediction of the Open date,
            if it says prediction it means the system is
            predicting based on the algorithm.
            Point in time property.
    """

    imo: int
    name: str
    vessel_class: str
    ice_class: Optional[str]
    year_built: int
    deadweight: int
    length_overall: float
    breadth_extreme: int
    market_deployment: str
    push_type: str
    open_port: str
    open_date: Optional[datetime]
    operational_status: str
    commercial_operator: str
    commercial_status: str
    eta: Optional[datetime]
    latest_ais: Optional[datetime]
    subclass: str
    willing_to_switch_subclass: bool
    open_prediction_accuracy: str
    open_areas: Tuple[Area, ...]
    availability_port_type: str
    availability_date_type: str

    def __post_init__(self) -> None:  # noqa: D105
        if self.open_areas is None:
            object.__setattr__(self, "open_areas", tuple())

    @property
    def open_country(self) -> Optional[str]:
        """Returns the vessel's open country name.

        Returns:
            The name of the open country or None if an area with
            LocationTaxonomy.COUNTRY was not present.
        """
        return self.__area_name_by_taxonomy(LocationTaxonomy.COUNTRY)

    @property
    def open_narrow_area(self) -> Optional[str]:
        """Returns the vessel's open narrow area name.

        Returns:
            The name of the open narrow area or None if an area with
            LocationTaxonomy.NARROW_AREA was not present.
        """
        return self.__area_name_by_taxonomy(LocationTaxonomy.NARROW_AREA)

    @property
    def open_wide_area(self) -> Optional[str]:
        """Returns the vessel's open wide area name.

        Returns:
            The name of the open wide area or None if an area with
            LocationTaxonomy.WIDE_AREA was not present.
        """
        return self.__area_name_by_taxonomy(LocationTaxonomy.WIDE_AREA)

    def __area_name_by_taxonomy(self, taxonomy: str) -> Optional[str]:
        for a in self.open_areas:
            if a.location_taxonomy == taxonomy:
                return a.name
        return None

open_country: Optional[str] property

Returns the vessel's open country name.

Returns:

Type Description
Optional[str]

The name of the open country or None if an area with
Optional[str]

LocationTaxonomy.COUNTRY was not present.

open_narrow_area: Optional[str] property

Returns the vessel's open narrow area name.

Returns:

Type Description
Optional[str]

The name of the open narrow area or None if an area with
Optional[str]

LocationTaxonomy.NARROW_AREA was not present.

open_wide_area: Optional[str] property

Returns the vessel's open wide area name.

Returns:

Type Description
Optional[str]

The name of the open wide area or None if an area with
Optional[str]

LocationTaxonomy.WIDE_AREA was not present.

VesselFilter dataclass

Enables vessel filtering in a Historical Tonnage List query.

All attributes in this class are optional, i.e. no filtering will be performed on attributes whose value is None.

Attributes that accept a list of values are used to perform an OR comparison. In other words, when a non-empty list of values is used, the Historical Tonnage List will contain vessels that match on any of the specified values. Using an empty list will result in no filtering at all.

VesselFilter is mutable in order to allow making adjustments to existing instances if query results are unsatisfactory.

Attributes:

Name Type Description
push_types Optional[List[str]]

Return vessels with the specified push types. Use constants defined in the PushType class for the values of this attribute.
market_deployments Optional[List[str]]

Return vessels with the specified market deployment types. Use constants defined in the MarketDeployment class for the values of this attribute.
commercial_statuses Optional[List[str]]

Return vessels with the specified commercial statuses. Use constants defined in the CommercialStatus class for the values of this attribute.
vessel_subclass Optional[str]

Return vessels of the specified subclass. Use constants defined in the VesselSubclass class for the values of this attribute.
add_willing_to_switch_subclass Optional[bool]

When True, returns vessels that do not match the subclass but are willing to switch to it.
latest_ais_since Optional[int]

The maximum age, in days, of the vessel's AIS information at the time the tonnage list was captured.
operational_statuses Optional[List[str]]

Return vessels with the specified operational statuses. Use constants defined in the OperationalStatus class for the values of this attribute.
min_liquid_capacity Optional[int]

The minimum liquid capacity, in cubic meters, the vessel should be able to hold.
max_liquid_capacity Optional[int]

The maximum liquid capacity, in cubic meters, the vessel should be able to hold.
fixture_types Optional[List[str]]

Return vessels with the specified fixture types. Use constants defined in the FixtureType class for the values of this attribute.
last_cargo_types Optional[List[str]]

Return vessels with the specified last cargo type IDs.
past_port_visits Optional[List[int]]

Return vessels with the specified past port visits.
open_port_ids Optional[List[int]]

Return vessels with the specified open port ids.
canakkale_cancelling Optional[date]

Return vessels with the specified Canakkale cancelling date.
open_date Optional[date]

Return vessels with the specified open date.
ice_classes Optional[List[str]]

Return vessels with the specified ice classes.
min_cranes_ton_capacity Optional[int]

Return vessels with the specified minimum cranes ton capacity.
max_cranes_ton_capacity Optional[int]

Return vessels with the specified maximum cranes ton capacity.
min_length_overall Optional[int]

Return vessels with the specified minimum length overall.
max_length_overall Optional[int]

Return vessels with the specified maximum length overall.
min_breadth_extreme Optional[int]

Return vessels with the specified minimum breadth extreme.
max_breadth_extreme Optional[int]

Return vessels with the specified maximum breadth extreme.
openAreas Optional[int]

Return vessels with the specified open area ids.
openCountries Optional[int]

Return vessels with the specified open country ids.
Source code in signal_ocean/historical_tonnage_list/vessel_filter.py 
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
@dataclass(eq=False)
class VesselFilter:
    """Enables vessel filtering in a Historical Tonnage List query.

    All attributes in this class are optional, i.e. no filtering will be
    performed on attributes whose value is None.

    Attributes that accept a list of values are used to perform an *OR*
    comparison. In other words, when a non-empty list of values is used,
    the Historical Tonnage List will contain vessels that match on **any**
    of the specified values. Using an empty list will result in no filtering
    at all.

    VesselFilter is mutable in order to allow making adjustments to
    existing instances if query results are unsatisfactory.

    Attributes:
        push_types: Return vessels with the specified push types.
            Use constants defined in the PushType class for the values of
            this attribute.
        market_deployments: Return vessels with the specified market
            deployment types. Use constants defined in the MarketDeployment
            class for the values of this attribute.
        commercial_statuses: Return vessels with the specified
            commercial statuses. Use constants defined in the CommercialStatus
            class for the values of this attribute.
        vessel_subclass: Return vessels of the specified subclass.
            Use constants defined in the VesselSubclass class for the values
            of this attribute.
        add_willing_to_switch_subclass: When True, returns vessels
            that do not match the subclass but are willing to switch to it.
        latest_ais_since: The maximum age, in days, of the vessel's
            AIS information at the time the tonnage list was captured.
        operational_statuses: Return vessels with the specified
            operational statuses. Use constants defined in the
            OperationalStatus class for the values of this attribute.
        min_liquid_capacity: The minimum liquid capacity, in cubic
            meters, the vessel should be able to hold.
        max_liquid_capacity: The maximum liquid capacity, in cubic
            meters, the vessel should be able to hold.
        fixture_types: Return vessels with the specified
            fixture types. Use constants defined in the FixtureType class for
            the values of this attribute.
        last_cargo_types: Return vessels with the specified last
            cargo type IDs.
        past_port_visits: Return vessels with the specified past
            port visits.
        open_port_ids: Return vessels with the specified open
            port ids.
        canakkale_cancelling: Return vessels with the specified
            Canakkale cancelling date.
        open_date: Return vessels with the specified open date.
        ice_classes: Return vessels with the specified ice classes.
        min_cranes_ton_capacity: Return vessels with the specified
            minimum cranes ton capacity.
        max_cranes_ton_capacity: Return vessels with the specified
            maximum cranes ton capacity.
        min_length_overall: Return vessels with the specified
            minimum length overall.
        max_length_overall: Return vessels with the specified
            maximum length overall.
        min_breadth_extreme: Return vessels with the specified
            minimum breadth extreme.
        max_breadth_extreme: Return vessels with the specified
            maximum breadth extreme.
        openAreas: Return vessels with the specified open area ids.
        openCountries: Return vessels with the specified open
            country ids.
    """

    push_types: Optional[List[str]] = cast(
        List[str], field(default_factory=list)
    )
    market_deployments: Optional[List[str]] = cast(
        List[str], field(default_factory=list)
    )
    commercial_statuses: Optional[List[str]] = cast(
        List[str], field(default_factory=list)
    )
    vessel_subclass: Optional[str] = VesselSubclass.ALL
    add_willing_to_switch_subclass: Optional[bool] = False
    latest_ais_since: Optional[int] = None
    operational_statuses: Optional[List[str]] = cast(
        List[str], field(default_factory=list)
    )
    min_liquid_capacity: Optional[int] = None
    max_liquid_capacity: Optional[int] = None
    fixture_types: Optional[List[str]] = cast(
        List[str], field(default_factory=list)
    )
    past_port_visits: Optional[List[int]] = cast(
        List[int], field(default_factory=list)
    )
    open_port_ids: Optional[List[int]] = cast(
        List[int], field(default_factory=list)
    )
    canakkale_cancelling: Optional[date] = None
    open_date: Optional[date] = None
    ice_classes: Optional[List[str]] = cast(
        List[str], field(default_factory=list)
    )
    min_cranes_ton_capacity: Optional[int] = None
    max_cranes_ton_capacity: Optional[int] = None
    min_length_overall: Optional[int] = None
    max_length_overall: Optional[int] = None
    min_breadth_extreme: Optional[int] = None
    max_breadth_extreme: Optional[int] = None
    open_area_ids: Optional[List[int]] = cast(
        List[int], field(default_factory=list)
    )
    open_country_ids: Optional[List[int]] = cast(
        List[int], field(default_factory=list)
    )

    def _to_query_string(self) -> QueryString:
        return {
            "pushType": self.push_types,
            "commercialStatus": self.commercial_statuses,
            "latestAisSince": self.latest_ais_since,
            "vesselSubclass": self.vessel_subclass,
            "addWillingToSwitchSubclass": self.add_willing_to_switch_subclass,
            "marketDeployment": self.market_deployments,
            "operationalStatus": self.operational_statuses,
            "minLiquidCapacity": self.min_liquid_capacity,
            "maxLiquidCapacity": self.max_liquid_capacity,
            "fixtureType": self.fixture_types,
            "pastPortVisit": self.past_port_visits,
            "openPortId": self.open_port_ids,
            "canakkaleCancelling": format_iso_date(self.canakkale_cancelling),
            "openDate": format_iso_date(self.open_date),
            "iceClass": self.ice_classes,
            "cranesTonCapacityMin": self.min_cranes_ton_capacity,
            "cranesTonCapacityMax": self.max_cranes_ton_capacity,
            "lengthOverallMin": self.min_length_overall,
            "lengthOverallMax": self.max_length_overall,
            "breadthExtremeMin": self.min_breadth_extreme,
            "breadthExtremeMax": self.max_breadth_extreme,
            "openArea": self.open_area_ids,
            "openCountry": self.open_country_ids
        }

VesselSubclass

Contains constants for available vessel subclasses.

Source code in signal_ocean/historical_tonnage_list/vessel_subclass.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
class VesselSubclass(metaclass=IterableConstants):
    """Contains constants for available vessel subclasses."""

    ALL = None
    '''
    Refers to all the vessels without any classification regarding
    the cargo type that they are carrying.
    '''
    DIRTY = 'Dirty'
    '''
    Refers to all the vessels that they classify
        to the dirty types of oil cargo.
    Applicable only for Tankers.
    '''
    CLEAN = 'Clean'
    '''
    Refers to all the vessels that they classify
        to the clean types of oil cargo.
    Applicable only for Tankers.
    '''

ALL = None class-attribute instance-attribute

Refers to all the vessels without any classification regarding the cargo type that they are carrying.

CLEAN = 'Clean' class-attribute instance-attribute

Refers to all the vessels that they classify to the clean types of oil cargo. Applicable only for Tankers.

DIRTY = 'Dirty' class-attribute instance-attribute

Refers to all the vessels that they classify to the dirty types of oil cargo. Applicable only for Tankers.