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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
__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 |
|
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 |
|
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 |
|
__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 |
|
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 |
|
IndexLevel
¶
Contains constants for available data frame index levels.
Source code in signal_ocean/historical_tonnage_list/index_level.py
6 7 8 9 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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.