Skip to content

Supply

The Supply API tells you which vessels are available for a market segment, and how many. It has daily history since 2014 and a live view of today. You can filter on more than 150 fields: vessel class or size, open location and date, commercial status, voyage state, AIS position, custom ETAs to a port, and vessel particulars.

You need your own API key with access to the Supply API. Your subscription also sets the vessel classes that you can query. A request for a vessel class that your key cannot access fails with an error (HTTP 403).

Methods

Method Use it for Dates
get_supply_trend Vessel counts per day, for trends and charts A start date and an end date
get_historical_supply The list of vessels on one past day One day
get_live_supply The list of vessels now Always now

All three methods take the same filters (SupplyFilter), a Baltic route template, or both. Each filter needs a vessel class (vessel_class), or a size band (vessel_type, defining_size and size together).

Examples

Supply trend with filters

from datetime import date

from signal_ocean import Connection
from signal_ocean.supply import (
    CommercialAvailabilityFilter,
    FromToRange,
    GeoLocation,
    IncludeExcludeFilter,
    LocationTaxonomy,
    SupplyAPI,
    SupplyFilter,
    VesselClass,
)

api = SupplyAPI(Connection("YOUR_API_KEY"))

# Aframax tankers that open in Houston (port 3853) within 20 days,
# with commercial data updated in the last 5 days.
filters = SupplyFilter(
    vessel_class=VesselClass.AFRAMAX,
    commercial_availability=CommercialAvailabilityFilter(
        open_location=IncludeExcludeFilter(
            values=[GeoLocation(geo_id=3853, location_taxonomy=LocationTaxonomy.PORT)]
        ),
        open_date_relative_offset=FromToRange(from_=-5, to=20),
        latest_updated_date_relative_offset=FromToRange(from_=-5, to=0),
    ),
)

trend = api.get_supply_trend(date(2026, 10, 1), date(2026, 10, 31), filters=filters)
trend.to_data_frame()  # index: date, column: supply

A Baltic route template with one change

from signal_ocean.supply import MinMaxRange, VesselParticularsFilter

# TD3C, but with vessels up to 20 years old instead of 15.
# All other TD3C filters stay as they are.
trend = api.get_supply_trend(
    date(2026, 10, 1),
    date(2026, 10, 31),
    template="TD3C",
    filters=SupplyFilter(
        vessel_particulars=VesselParticularsFilter(vessel_age=MinMaxRange(max=20))
    ),
)

Live supply as a data frame

live = api.get_live_supply(template="TD25")
frame = live.to_data_frame()  # one row per vessel
frame[["imo", "open_location", "open_date_to", "eta_TD25"]]

The Column class lists the column names. Each ETA configuration adds columns named after its id, for example eta_TD25 and eta_distance_TD25.

How filters and templates combine

  • A filter field that you set replaces the template's value for that field as a whole. All other template filters stay. For example, vessel_age=MinMaxRange(min=5) replaces the template's age range, so the template's maximum age no longer applies. In the same way, open_location=IncludeExcludeFilter(values=[...]) also removes the template's excluded locations.
  • A list that you set replaces the template's list. It is not added to it.
  • Set a field to None to remove that template filter. None changes no other field.
  • vessel_class replaces the template's size band (vessel_type, defining_size and size), and a size band replaces the template's vessel_class.
  • An absolute date range, for example open_date, replaces the template's relative window for the same field.

Baltic route templates

Pass a route code as template. Codes are not case sensitive. Call api.get_supply_templates() to get the full definition of each template.

Code Template
TD1 VLCC US Gulf Supply 30 Days (TD1)
TD3C VLCC Arabian Gulf Supply 18 Days (TD3C)
TD15 VLCC West Africa Supply 20 Days (TD15)
TD23 Suezmax US Gulf Supply 20 Days (TD23)
TD20 Suezmax West Africa Supply 20 Days (TD20)
TD6 Suezmax Black Sea Supply 20 Days (TD6)
TD25 Aframax US Gulf Supply 10 Days (TD25)
TD19 Aframax Mediterranean Supply 10 Days (TD19)
TD7 Aframax Continent Supply 10 Days (TD7)
TD8 Aframax Arabian Gulf Supply 15 Days (TD8)
TC14 MR2 US Gulf Supply 7 Days (TC14)
TC2 MR2 Continent Supply 10 Days (TC2)
TC12 MR2 Far East Supply 10 Days (TC12)
TC6 MR1 Mediterranean Supply 10 Days (TC6)
TC1 LR2 Arabian Gulf Supply Next 30 Days
TC5 LR1 Arabian Gulf Supply Next 30 Days
C3 Capesize Brazil 40 days ballasters (C3)
C5 Capesize W Australia 15 days ballasters (C5)
C7 Capesize Atlantic ballasters (C7)
P6 Panamax ECSA 40 days ballasters (P6)
P1 Panamax Atlantic ballasters (P1)
P3 Panamax WCNA 20 days ballasters (P3)
P5 Panamax Marketed SE Asia open 7 days (P5)
S5 Supramax Marketed ECSA ETA 20days (S5)
S2 Supramax Marketed Far East open 10days (S2)
S10 Supramax Marketed South China open 10days (S10)
HS4 Handy Marketed USG open 20 days (HS4)
HS5 Handy Marketed SE Asia open 10 days (HS5)

TC1 and TC5 are the Baltic routes that the LR2 and LR1 Arabian Gulf templates match.

Good to know

  • Relative windows. A *_relative_offset range and eta_relative_offset count days from each snapshot day on get_supply_trend and get_historical_supply, and from today on get_live_supply. The templates use relative windows, so a template means the same on all three methods.
  • Commercial data history. Commercial availability history starts on 29 January 2026. For earlier days, the commercial filters and the ETA calculations use Signal's system-calculated values. Results before and after that day can look different.
  • Your organisation's data. From your account's start date, results show your organisation's own positions and commercial data. Before that date, results come from Signal's baseline data.
  • Hub ports on the trend. get_supply_trend always calculates ETAs to hub ports. An ETA basis port that is not a hub port is replaced by the hub port of its region, and the result's notes say so. So a trend count for an ETA template can differ a little from the live list of the same template. get_historical_supply uses the ports as given, unless you set use_only_hub_ports=True.
  • Daily limit on historical supply. Each API key can call get_historical_supply 5 times per day. For counts over a date range, use get_supply_trend.
  • HS4. Its name says 20 days, but its open window is 10 days. The SDK keeps the 10-day window of the template.
  • Errors. When the API refuses a request, the SDK raises requests.HTTPError. The error message includes the API's explanation, for example which filter is not valid.

Package Documentation

Supply API: vessel supply trend, historical supply and live supply.

Classes:

Name Description
SupplyAPI

Retrieves vessel supply.

SupplyFilter

Filters for all three supply methods.

LiveSupplyFilter

Filters for live supply, with routing restrictions.

SupplyTemplate

A Baltic route template.

SupplyTrend

Daily supply counts.

SupplySnapshot

Vessel records of one day.

AisTracking

Bases: SupplyResponseModel

AIS position, movement and destination of a vessel.

Attributes:

Name Type Description
last_movement_date_time_utc Optional[datetime]

Last time the system detected a movement of the vessel, in UTC. Shows if the vessel is stationary or underway.

days_since_latest_ais Optional[float]

Days since the last AIS message of the vessel. More than 7 days can mean that the AIS is off or out of coverage.

ais_latitude_average Optional[float]

Average latitude of the day.

ais_longitude_average Optional[float]

Average longitude of the day.

ais_draught_average Optional[float]

Average draught of the day, in metres.

ais_heading_average Optional[float]

Average heading of the day, in degrees.

ais_speed_average Optional[float]

Average speed of the day in knots. Includes the time steaming and the time stationary.

ais_seagoing_speed_average Optional[float]

Average steaming speed of the day in knots. Speeds below 5 knots are not included.

ais_current_area Optional[str]

Name of the standard area of the AIS position, for example US Gulf.

ais_current_area_id Optional[int]

Id of the standard area of the AIS position.

ais_closest_location Optional[str]

Name of the location nearest to the AIS position.

ais_closest_location_id Optional[int]

Id of the location nearest to the AIS position.

ais_destination Optional[str]

Name of the destination that the vessel reports on AIS.

ais_destination_taxonomy Optional[str]

Precision level of the AIS destination, for example Port.

ais_destination_geo_id Optional[int]

Geo id of the AIS destination. The crew enters this destination.

ais_destination_taxonomy_id Optional[int]

Precision level id of the AIS destination. See LocationTaxonomy.

eta_to_ais_destination Optional[datetime]

ETA to the AIS destination, calculated by the system. It is not the ETA that the crew reports.

miles_to_ais_destination Optional[float]

Distance to the AIS destination in nautical miles.

delays_to_ais_destination Optional[float]

Estimated delays to the AIS destination, in hours.

Source code in signal_ocean/supply/models.py
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
class AisTracking(SupplyResponseModel):
    """AIS position, movement and destination of a vessel.

    Attributes:
        last_movement_date_time_utc: Last time the system detected a
            movement of the vessel, in UTC. Shows if the vessel is
            stationary or underway.
        days_since_latest_ais: Days since the last AIS message of the
            vessel. More than 7 days can mean that the AIS is off or out of
            coverage.
        ais_latitude_average: Average latitude of the day.
        ais_longitude_average: Average longitude of the day.
        ais_draught_average: Average draught of the day, in metres.
        ais_heading_average: Average heading of the day, in degrees.
        ais_speed_average: Average speed of the day in knots. Includes the
            time steaming and the time stationary.
        ais_seagoing_speed_average: Average steaming speed of the day in
            knots. Speeds below 5 knots are not included.
        ais_current_area: Name of the standard area of the AIS position, for
            example US Gulf.
        ais_current_area_id: Id of the standard area of the AIS position.
        ais_closest_location: Name of the location nearest to the AIS
            position.
        ais_closest_location_id: Id of the location nearest to the AIS
            position.
        ais_destination: Name of the destination that the vessel reports on
            AIS.
        ais_destination_taxonomy: Precision level of the AIS destination,
            for example `Port`.
        ais_destination_geo_id: Geo id of the AIS destination. The crew
            enters this destination.
        ais_destination_taxonomy_id: Precision level id of the AIS
            destination. See `LocationTaxonomy`.
        eta_to_ais_destination: ETA to the AIS destination, calculated by
            the system. It is not the ETA that the crew reports.
        miles_to_ais_destination: Distance to the AIS destination in
            nautical miles.
        delays_to_ais_destination: Estimated delays to the AIS destination,
            in hours.
    """

    last_movement_date_time_utc: Optional[datetime] = Field(
        None, alias="lastMovementDateTimeUTC"
    )
    days_since_latest_ais: Optional[float] = None
    ais_latitude_average: Optional[float] = None
    ais_longitude_average: Optional[float] = None
    ais_draught_average: Optional[float] = None
    ais_heading_average: Optional[float] = None
    ais_speed_average: Optional[float] = None
    ais_seagoing_speed_average: Optional[float] = None
    ais_current_area: Optional[str] = None
    ais_current_area_id: Optional[int] = None
    ais_closest_location: Optional[str] = None
    ais_closest_location_id: Optional[int] = None
    ais_destination: Optional[str] = None
    ais_destination_taxonomy: Optional[str] = None
    ais_destination_geo_id: Optional[int] = None
    ais_destination_taxonomy_id: Optional[int] = None
    eta_to_ais_destination: Optional[datetime] = None
    miles_to_ais_destination: Optional[float] = None
    delays_to_ais_destination: Optional[float] = None

AisTrackingFilter

Bases: SupplyRequestModel

Filters on AIS position, movement and destination.

ais_current_area takes area ids as integers. ais_closest_location and ais_destination take GeoLocation values.

Attributes:

Name Type Description
days_since_latest_ais Optional[int]

Maximum number of days since the last AIS message of the vessel. More than 7 days can mean that the AIS is off or out of coverage.

ais_draught Optional[MinMaxRange]

Current AIS draught in metres. A deep draught usually means laden, a shallow draught usually means ballast.

ais_heading Optional[List[HeadingRange]]

Compass headings in degrees, 0 to 360.

ais_speed Optional[FromToRange]

Current AIS speed over ground in knots.

ais_current_area Optional[IncludeExcludeFilter]

Area ids of the current AIS position.

ais_closest_location Optional[IncludeExcludeFilter]

The named location nearest to the AIS position.

ais_destination Optional[IncludeExcludeFilter]

The destination that the vessel reports on AIS.

eta_to_ais_destination Optional[FromToRange]

ETA to the AIS destination, calculated by the system.

Source code in signal_ocean/supply/filters.py
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
class AisTrackingFilter(SupplyRequestModel):
    """Filters on AIS position, movement and destination.

    `ais_current_area` takes area ids as integers. `ais_closest_location`
    and `ais_destination` take `GeoLocation` values.

    Attributes:
        days_since_latest_ais: Maximum number of days since the last AIS
            message of the vessel. More than 7 days can mean that the AIS
            is off or out of coverage.
        ais_draught: Current AIS draught in metres. A deep draught usually
            means laden, a shallow draught usually means ballast.
        ais_heading: Compass headings in degrees, 0 to 360.
        ais_speed: Current AIS speed over ground in knots.
        ais_current_area: Area ids of the current AIS position.
        ais_closest_location: The named location nearest to the AIS
            position.
        ais_destination: The destination that the vessel reports on AIS.
        eta_to_ais_destination: ETA to the AIS destination, calculated by
            the system.
    """

    days_since_latest_ais: Optional[int] = None
    ais_draught: Optional[MinMaxRange] = None
    ais_heading: Optional[List[HeadingRange]] = None
    ais_speed: Optional[FromToRange] = None
    ais_current_area: Optional[IncludeExcludeFilter] = None
    ais_closest_location: Optional[IncludeExcludeFilter] = None
    ais_destination: Optional[IncludeExcludeFilter] = None
    eta_to_ais_destination: Optional[FromToRange] = None

AvailabilityState

Commercial availability states, for availability_state.

Source code in signal_ocean/supply/constants.py
64
65
66
67
68
69
70
71
72
class AvailabilityState(metaclass=IterableConstants):
    """Commercial availability states, for `availability_state`."""

    ON_SUBS = "OnSubs"
    FULLY_FIXED = "FullyFixed"
    FAILED = "Failed"
    CANCELLED = "Cancelled"
    AVAILABLE = "Available"
    POTENTIALLY_FIXED = "PotentiallyFixed"

Coating

Tank coating types, for coating.

Source code in signal_ocean/supply/constants.py
149
150
151
152
153
154
155
156
157
158
class Coating(metaclass=IterableConstants):
    """Tank coating types, for `coating`."""

    NONE = "None"
    STS_T_COATING = "StsTCoating"
    EPOXY_COATING = "EpoxyCoating"
    ZINC_COATING = "ZincCoating"
    MARINELINE_COATING = "MarinelineCoating"
    INTERLINE_COATING = "InterlineCoating"
    NO_COATING = "NoCoating"

Column

Column names of SupplySnapshot.to_data_frame().

After these columns come four columns per ETA configuration: eta_<id>, eta_distance_<id>, eta_basis_port_id_<id> and eta_canals_<id>. <id> is the configuration's id, or its position (0, 1, ...) when it has no id.

Source code in signal_ocean/supply/data_frame.py
 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
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
class Column(metaclass=IterableConstants):
    """Column names of `SupplySnapshot.to_data_frame()`.

    After these columns come four columns per ETA configuration:
    `eta_<id>`, `eta_distance_<id>`, `eta_basis_port_id_<id>` and
    `eta_canals_<id>`. `<id>` is the configuration's `id`, or its position
    (`0`, `1`, ...) when it has no `id`.
    """

    DAY = "day"
    """The snapshot day."""

    IMO = "imo"
    """The vessel's IMO number."""

    VESSEL_CLASS_ID = "vessel_class_id"
    """The vessel class."""

    VESSEL_CLASS = "vessel_class"
    """The vessel class name."""

    OPEN_LOCATION = "open_location"
    """Name of the location where the vessel opens."""

    OPEN_LOCATION_TAXONOMY = "open_location_taxonomy"
    """Level of the open location, for example `Port`."""

    OPEN_LOCATION_GEO_ID = "open_location_geo_id"
    """Geo id of the open location."""

    OPEN_LOCATION_TAXONOMY_ID = "open_location_taxonomy_id"
    """Level id of the open location."""

    OPEN_DATE_FROM = "open_date_from"
    """Start of the open period."""

    OPEN_DATE_TO = "open_date_to"
    """End of the open period."""

    AVAILABILITY_STATE = "availability_state"
    """Commercial availability state, for example `Available`."""

    AVAILABILITY_STATE_ID = "availability_state_id"
    """Id of the availability state."""

    MARKET_STATUS = "market_status"
    """Market push state, for example `Pushed`."""

    MARKET_STATUS_ID = "market_status_id"
    """Id of the market status."""

    MARKET_DEPLOYMENT = "market_deployment"
    """Market deployment, for example `Spot`."""

    MARKET_DEPLOYMENT_ID = "market_deployment_id"
    """Id of the market deployment."""

    POSITION_SOURCE_ORIGIN = "position_source_origin"
    """Origin of the position data, for example `Manual`."""

    POSITION_SOURCE_ORIGIN_ID = "position_source_origin_id"
    """Id of the position source origin."""

    POSITION_SOURCE_TYPE = "position_source_type"
    """Type of the position source, for example `Email`."""

    POSITION_SOURCE_TYPE_ID = "position_source_type_id"
    """Id of the position source type."""

    LAST_MARKETED_DATE = "last_marketed_date"
    """Last date the vessel was pushed to the market."""

    LATEST_UPDATED_DATE = "latest_updated_date"
    """Last update of the vessel's commercial data."""

    FORECASTED_DESTINATION_PORT = "forecasted_destination_port"
    """Name of the forecasted next port."""

    FORECASTED_DESTINATION_PORT_ID = "forecasted_destination_port_id"
    """Id of the forecasted next port."""

    VOYAGE_STATE = "voyage_state"
    """Operational voyage state, for example `Laden`."""

    VOYAGE_STATE_ID = "voyage_state_id"
    """Id of the voyage state."""

    CARGO_TYPE = "cargo_type"
    """Name of the current or last cargo type."""

    CARGO_TYPE_ID = "cargo_type_id"
    """Id of the current or last cargo type."""

    CARGO_QUANTITY = "cargo_quantity"
    """Cargo quantity in metric tons."""

    CHARTERER = "charterer"
    """Charterer name."""

    CHARTERER_ID = "charterer_id"
    """Charterer company id."""

    START_PORT = "start_port"
    """Name of the voyage leg's start port."""

    START_PORT_ID = "start_port_id"
    """Id of the voyage leg's start port."""

    LAST_VOYAGE_CARGO_TYPES = "last_voyage_cargo_types"
    """Cargo type names of the previous voyage, as a list."""

    LAST_VOYAGE_CARGO_TYPE_IDS = "last_voyage_cargo_type_ids"
    """Cargo type ids of the previous voyage, as a list."""

    LAST_CARGO_TYPES = "last_cargo_types"
    """Last cargo type names, as a list."""

    LAST_CARGO_TYPE_IDS = "last_cargo_type_ids"
    """Last cargo type ids, as a list."""

    LAST_MOVEMENT_DATE_TIME_UTC = "last_movement_date_time_utc"
    """Last time the vessel moved."""

    DAYS_SINCE_LATEST_AIS = "days_since_latest_ais"
    """Days since the last AIS message."""

    AIS_LATITUDE_AVERAGE = "ais_latitude_average"
    """Average latitude of the day."""

    AIS_LONGITUDE_AVERAGE = "ais_longitude_average"
    """Average longitude of the day."""

    AIS_DRAUGHT_AVERAGE = "ais_draught_average"
    """Average draught of the day."""

    AIS_HEADING_AVERAGE = "ais_heading_average"
    """Average heading of the day."""

    AIS_SPEED_AVERAGE = "ais_speed_average"
    """Average speed of the day, stationary time included."""

    AIS_SEAGOING_SPEED_AVERAGE = "ais_seagoing_speed_average"
    """Average speed of the day when steaming (5 knots or more)."""

    AIS_CURRENT_AREA = "ais_current_area"
    """Name of the area the vessel is in."""

    AIS_CURRENT_AREA_ID = "ais_current_area_id"
    """Id of the area the vessel is in."""

    AIS_CLOSEST_LOCATION = "ais_closest_location"
    """Name of the closest location."""

    AIS_CLOSEST_LOCATION_ID = "ais_closest_location_id"
    """Id of the closest location."""

    AIS_DESTINATION = "ais_destination"
    """Name of the destination the crew reported in AIS."""

    AIS_DESTINATION_TAXONOMY = "ais_destination_taxonomy"
    """Level of the AIS destination, for example `Port`."""

    AIS_DESTINATION_GEO_ID = "ais_destination_geo_id"
    """Geo id of the AIS destination."""

    AIS_DESTINATION_TAXONOMY_ID = "ais_destination_taxonomy_id"
    """Level id of the AIS destination."""

    ETA_TO_AIS_DESTINATION = "eta_to_ais_destination"
    """Calculated ETA to the AIS destination."""

    MILES_TO_AIS_DESTINATION = "miles_to_ais_destination"
    """Distance to the AIS destination in nautical miles."""

    DELAYS_TO_AIS_DESTINATION = "delays_to_ais_destination"
    """Estimated delay to the AIS destination in hours."""

    NOTES = "notes"
    """Your company's notes; only when live supply includes details."""

AIS_CLOSEST_LOCATION = 'ais_closest_location' class-attribute instance-attribute

Name of the closest location.

AIS_CLOSEST_LOCATION_ID = 'ais_closest_location_id' class-attribute instance-attribute

Id of the closest location.

AIS_CURRENT_AREA = 'ais_current_area' class-attribute instance-attribute

Name of the area the vessel is in.

AIS_CURRENT_AREA_ID = 'ais_current_area_id' class-attribute instance-attribute

Id of the area the vessel is in.

AIS_DESTINATION = 'ais_destination' class-attribute instance-attribute

Name of the destination the crew reported in AIS.

AIS_DESTINATION_GEO_ID = 'ais_destination_geo_id' class-attribute instance-attribute

Geo id of the AIS destination.

AIS_DESTINATION_TAXONOMY = 'ais_destination_taxonomy' class-attribute instance-attribute

Level of the AIS destination, for example Port.

AIS_DESTINATION_TAXONOMY_ID = 'ais_destination_taxonomy_id' class-attribute instance-attribute

Level id of the AIS destination.

AIS_DRAUGHT_AVERAGE = 'ais_draught_average' class-attribute instance-attribute

Average draught of the day.

AIS_HEADING_AVERAGE = 'ais_heading_average' class-attribute instance-attribute

Average heading of the day.

AIS_LATITUDE_AVERAGE = 'ais_latitude_average' class-attribute instance-attribute

Average latitude of the day.

AIS_LONGITUDE_AVERAGE = 'ais_longitude_average' class-attribute instance-attribute

Average longitude of the day.

AIS_SEAGOING_SPEED_AVERAGE = 'ais_seagoing_speed_average' class-attribute instance-attribute

Average speed of the day when steaming (5 knots or more).

AIS_SPEED_AVERAGE = 'ais_speed_average' class-attribute instance-attribute

Average speed of the day, stationary time included.

AVAILABILITY_STATE = 'availability_state' class-attribute instance-attribute

Commercial availability state, for example Available.

AVAILABILITY_STATE_ID = 'availability_state_id' class-attribute instance-attribute

Id of the availability state.

CARGO_QUANTITY = 'cargo_quantity' class-attribute instance-attribute

Cargo quantity in metric tons.

CARGO_TYPE = 'cargo_type' class-attribute instance-attribute

Name of the current or last cargo type.

CARGO_TYPE_ID = 'cargo_type_id' class-attribute instance-attribute

Id of the current or last cargo type.

CHARTERER = 'charterer' class-attribute instance-attribute

Charterer name.

CHARTERER_ID = 'charterer_id' class-attribute instance-attribute

Charterer company id.

DAY = 'day' class-attribute instance-attribute

The snapshot day.

DAYS_SINCE_LATEST_AIS = 'days_since_latest_ais' class-attribute instance-attribute

Days since the last AIS message.

DELAYS_TO_AIS_DESTINATION = 'delays_to_ais_destination' class-attribute instance-attribute

Estimated delay to the AIS destination in hours.

ETA_TO_AIS_DESTINATION = 'eta_to_ais_destination' class-attribute instance-attribute

Calculated ETA to the AIS destination.

FORECASTED_DESTINATION_PORT = 'forecasted_destination_port' class-attribute instance-attribute

Name of the forecasted next port.

FORECASTED_DESTINATION_PORT_ID = 'forecasted_destination_port_id' class-attribute instance-attribute

Id of the forecasted next port.

IMO = 'imo' class-attribute instance-attribute

The vessel's IMO number.

LAST_CARGO_TYPES = 'last_cargo_types' class-attribute instance-attribute

Last cargo type names, as a list.

LAST_CARGO_TYPE_IDS = 'last_cargo_type_ids' class-attribute instance-attribute

Last cargo type ids, as a list.

LAST_MARKETED_DATE = 'last_marketed_date' class-attribute instance-attribute

Last date the vessel was pushed to the market.

LAST_MOVEMENT_DATE_TIME_UTC = 'last_movement_date_time_utc' class-attribute instance-attribute

Last time the vessel moved.

LAST_VOYAGE_CARGO_TYPES = 'last_voyage_cargo_types' class-attribute instance-attribute

Cargo type names of the previous voyage, as a list.

LAST_VOYAGE_CARGO_TYPE_IDS = 'last_voyage_cargo_type_ids' class-attribute instance-attribute

Cargo type ids of the previous voyage, as a list.

LATEST_UPDATED_DATE = 'latest_updated_date' class-attribute instance-attribute

Last update of the vessel's commercial data.

MARKET_DEPLOYMENT = 'market_deployment' class-attribute instance-attribute

Market deployment, for example Spot.

MARKET_DEPLOYMENT_ID = 'market_deployment_id' class-attribute instance-attribute

Id of the market deployment.

MARKET_STATUS = 'market_status' class-attribute instance-attribute

Market push state, for example Pushed.

MARKET_STATUS_ID = 'market_status_id' class-attribute instance-attribute

Id of the market status.

MILES_TO_AIS_DESTINATION = 'miles_to_ais_destination' class-attribute instance-attribute

Distance to the AIS destination in nautical miles.

NOTES = 'notes' class-attribute instance-attribute

Your company's notes; only when live supply includes details.

OPEN_DATE_FROM = 'open_date_from' class-attribute instance-attribute

Start of the open period.

OPEN_DATE_TO = 'open_date_to' class-attribute instance-attribute

End of the open period.

OPEN_LOCATION = 'open_location' class-attribute instance-attribute

Name of the location where the vessel opens.

OPEN_LOCATION_GEO_ID = 'open_location_geo_id' class-attribute instance-attribute

Geo id of the open location.

OPEN_LOCATION_TAXONOMY = 'open_location_taxonomy' class-attribute instance-attribute

Level of the open location, for example Port.

OPEN_LOCATION_TAXONOMY_ID = 'open_location_taxonomy_id' class-attribute instance-attribute

Level id of the open location.

POSITION_SOURCE_ORIGIN = 'position_source_origin' class-attribute instance-attribute

Origin of the position data, for example Manual.

POSITION_SOURCE_ORIGIN_ID = 'position_source_origin_id' class-attribute instance-attribute

Id of the position source origin.

POSITION_SOURCE_TYPE = 'position_source_type' class-attribute instance-attribute

Type of the position source, for example Email.

POSITION_SOURCE_TYPE_ID = 'position_source_type_id' class-attribute instance-attribute

Id of the position source type.

START_PORT = 'start_port' class-attribute instance-attribute

Name of the voyage leg's start port.

START_PORT_ID = 'start_port_id' class-attribute instance-attribute

Id of the voyage leg's start port.

VESSEL_CLASS = 'vessel_class' class-attribute instance-attribute

The vessel class name.

VESSEL_CLASS_ID = 'vessel_class_id' class-attribute instance-attribute

The vessel class.

VOYAGE_STATE = 'voyage_state' class-attribute instance-attribute

Operational voyage state, for example Laden.

VOYAGE_STATE_ID = 'voyage_state_id' class-attribute instance-attribute

Id of the voyage state.

CommercialAvailability

Bases: SupplyResponseModel

Open location, open dates and commercial status of a vessel.

Attributes:

Name Type Description
open_location Optional[str]

Name of the location where the vessel becomes available.

open_location_taxonomy Optional[str]

Precision level of the open location, for example Port.

open_location_geo_id Optional[int]

Geo id of the open location.

open_location_taxonomy_id Optional[int]

Precision level id of the open location. See LocationTaxonomy.

open_date_from Optional[datetime]

Start of the open period: the first day of the lay range.

open_date_to Optional[datetime]

End of the open period: the last day of the lay range.

availability_state Optional[str]

Charter market status: open for new business, under negotiation, or committed. Shows if the vessel is in the live tonnage pool. See AvailabilityState.

availability_state_id Optional[int]

Id of the availability state.

market_status Optional[str]

Whether the commercial operator markets the vessel: pushed (listed), possibly pushed, or not pushed (no evidence). See MarketStatus.

market_status_id Optional[int]

Id of the market status.

market_deployment Optional[str]

How the vessel is deployed: spot (voyage by voyage), program (semi-contractual), contract (long term) or relet (sub-chartered). See MarketDeployment.

market_deployment_id Optional[int]

Id of the market deployment.

position_source_origin Optional[str]

How the position was found: entered by a user, from AIS, or calculated by the system. See PositionSourceOrigin.

position_source_origin_id Optional[int]

Id of the position source origin.

position_source_type Optional[str]

The channel that reported the position, for example email, a chat application (Slack, Teams, WhatsApp) or a model prediction. See PositionSourceType.

position_source_type_id Optional[int]

Id of the position source type.

last_marketed_date Optional[datetime]

When the operator last marketed the vessel. The number of days since this date helps to estimate if the vessel is committed or under negotiation.

latest_updated_date Optional[datetime]

When the commercial data of the vessel was last updated. Shows how recent the data is.

forecasted_destination_port Optional[str]

Name of the destination port that the system predicts.

forecasted_destination_port_id Optional[int]

Id of the next port that the system predicts from the patterns of the vessel.

Source code in signal_ocean/supply/models.py
 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
class CommercialAvailability(SupplyResponseModel):
    """Open location, open dates and commercial status of a vessel.

    Attributes:
        open_location: Name of the location where the vessel becomes
            available.
        open_location_taxonomy: Precision level of the open location, for
            example `Port`.
        open_location_geo_id: Geo id of the open location.
        open_location_taxonomy_id: Precision level id of the open location.
            See `LocationTaxonomy`.
        open_date_from: Start of the open period: the first day of the lay
            range.
        open_date_to: End of the open period: the last day of the lay range.
        availability_state: Charter market status: open for new business,
            under negotiation, or committed. Shows if the vessel is in the
            live tonnage pool. See `AvailabilityState`.
        availability_state_id: Id of the availability state.
        market_status: Whether the commercial operator markets the vessel:
            pushed (listed), possibly pushed, or not pushed (no evidence).
            See `MarketStatus`.
        market_status_id: Id of the market status.
        market_deployment: How the vessel is deployed: spot (voyage by
            voyage), program (semi-contractual), contract (long term) or
            relet (sub-chartered). See `MarketDeployment`.
        market_deployment_id: Id of the market deployment.
        position_source_origin: How the position was found: entered by a
            user, from AIS, or calculated by the system. See
            `PositionSourceOrigin`.
        position_source_origin_id: Id of the position source origin.
        position_source_type: The channel that reported the position, for
            example email, a chat application (Slack, Teams, WhatsApp) or a
            model prediction. See `PositionSourceType`.
        position_source_type_id: Id of the position source type.
        last_marketed_date: When the operator last marketed the vessel. The
            number of days since this date helps to estimate if the vessel
            is committed or under negotiation.
        latest_updated_date: When the commercial data of the vessel was last
            updated. Shows how recent the data is.
        forecasted_destination_port: Name of the destination port that the
            system predicts.
        forecasted_destination_port_id: Id of the next port that the system
            predicts from the patterns of the vessel.
    """

    open_location: Optional[str] = None
    open_location_taxonomy: Optional[str] = None
    open_location_geo_id: Optional[int] = None
    open_location_taxonomy_id: Optional[int] = None
    open_date_from: Optional[datetime] = None
    open_date_to: Optional[datetime] = None
    availability_state: Optional[str] = None
    availability_state_id: Optional[int] = None
    market_status: Optional[str] = None
    market_status_id: Optional[int] = None
    market_deployment: Optional[str] = None
    market_deployment_id: Optional[int] = None
    position_source_origin: Optional[str] = None
    position_source_origin_id: Optional[int] = None
    position_source_type: Optional[str] = None
    position_source_type_id: Optional[int] = None
    last_marketed_date: Optional[datetime] = None
    latest_updated_date: Optional[datetime] = None
    forecasted_destination_port: Optional[str] = None
    forecasted_destination_port_id: Optional[int] = None

CommercialAvailabilityFilter

Bases: SupplyRequestModel

Filters on open location, open date and commercial status.

Location filters take GeoLocation values. A *_relative_offset range counts days from each snapshot day, or from today on live supply. An absolute date and its relative offset cannot be combined.

Attributes:

Name Type Description
open_location Optional[IncludeExcludeFilter]

Where the vessel becomes available, from AIS and commercial data. Takes GeoLocation values: a port, an area (for example US Gulf) or a country.

open_date Optional[FromToRange]

When the vessel becomes available for its next charter.

open_date_relative_offset Optional[FromToRange]

Open date in days from the snapshot day. A negative value is in the past.

availability_state Optional[List[str]]

Charter market status: open for new business, under negotiation, or committed. See AvailabilityState.

market_status Optional[IncludeExcludeFilter]

Whether the commercial operator markets the vessel: pushed, possibly pushed or not pushed. See MarketStatus.

market_deployment Optional[List[str]]

How the vessel is deployed: spot, program, contract or relet. See MarketDeployment.

position_source_origin Optional[IncludeExcludeFilter]

How the position was found: entered by a user, from AIS, or calculated by the system. See PositionSourceOrigin.

position_source_type Optional[IncludeExcludeFilter]

The channel that reported the position, for example email or a model prediction. See PositionSourceType.

last_marketed_date Optional[FromToRange]

When the operator last marketed the vessel.

last_marketed_date_relative_offset Optional[FromToRange]

Last marketed date in days from the snapshot day.

latest_updated_date Optional[FromToRange]

When the commercial data of the vessel was last updated. Shows how recent the position is.

latest_updated_date_relative_offset Optional[FromToRange]

Latest update in days from the snapshot day.

forecasted_destination Optional[IncludeExcludeFilter]

The destination that the system predicts. Takes GeoLocation values. It is not the AIS destination.

Source code in signal_ocean/supply/filters.py
 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
class CommercialAvailabilityFilter(SupplyRequestModel):
    """Filters on open location, open date and commercial status.

    Location filters take `GeoLocation` values. A `*_relative_offset`
    range counts days from each snapshot day, or from today on live supply.
    An absolute date and its relative offset cannot be combined.

    Attributes:
        open_location: Where the vessel becomes available, from AIS and
            commercial data. Takes `GeoLocation` values: a port, an area
            (for example US Gulf) or a country.
        open_date: When the vessel becomes available for its next charter.
        open_date_relative_offset: Open date in days from the snapshot day.
            A negative value is in the past.
        availability_state: Charter market status: open for new business,
            under negotiation, or committed. See `AvailabilityState`.
        market_status: Whether the commercial operator markets the vessel:
            pushed, possibly pushed or not pushed. See `MarketStatus`.
        market_deployment: How the vessel is deployed: spot, program,
            contract or relet. See `MarketDeployment`.
        position_source_origin: How the position was found: entered by a
            user, from AIS, or calculated by the system. See
            `PositionSourceOrigin`.
        position_source_type: The channel that reported the position, for
            example email or a model prediction. See `PositionSourceType`.
        last_marketed_date: When the operator last marketed the vessel.
        last_marketed_date_relative_offset: Last marketed date in days from
            the snapshot day.
        latest_updated_date: When the commercial data of the vessel was last
            updated. Shows how recent the position is.
        latest_updated_date_relative_offset: Latest update in days from the
            snapshot day.
        forecasted_destination: The destination that the system predicts.
            Takes `GeoLocation` values. It is not the AIS destination.
    """

    open_location: Optional[IncludeExcludeFilter] = None
    open_date: Optional[FromToRange] = None
    open_date_relative_offset: Optional[FromToRange] = None
    availability_state: Optional[List[str]] = None
    market_status: Optional[IncludeExcludeFilter] = None
    market_deployment: Optional[List[str]] = None
    position_source_origin: Optional[IncludeExcludeFilter] = None
    position_source_type: Optional[IncludeExcludeFilter] = None
    last_marketed_date: Optional[FromToRange] = None
    last_marketed_date_relative_offset: Optional[FromToRange] = None
    latest_updated_date: Optional[FromToRange] = None
    latest_updated_date_relative_offset: Optional[FromToRange] = None
    forecasted_destination: Optional[IncludeExcludeFilter] = None

DailySupply

Bases: SupplyResponseModel

The supply count of one day.

Attributes:

Name Type Description
date datetime

The snapshot day.

supply int

Number of vessels that match the filters on that day.

Source code in signal_ocean/supply/models.py
23
24
25
26
27
28
29
30
31
32
class DailySupply(SupplyResponseModel):
    """The supply count of one day.

    Attributes:
        date: The snapshot day.
        supply: Number of vessels that match the filters on that day.
    """

    date: datetime
    supply: int

DefiningSize

Size units, for defining_size.

Source code in signal_ocean/supply/constants.py
43
44
45
46
47
class DefiningSize(metaclass=IterableConstants):
    """Size units, for `defining_size`."""

    DEADWEIGHT = "Deadweight"
    CUBIC_SIZE = "CubicSize"

EtaCalculationBasis

Start position and date of an ETA calculation.

Source code in signal_ocean/supply/constants.py
128
129
130
131
132
133
134
class EtaCalculationBasis(metaclass=IterableConstants):
    """Start position and date of an ETA calculation."""

    DEFAULT = "Default"
    LATEST_OPEN_DATE = "LatestOpenDate"
    EARLIEST_OPEN_DATE = "EarliestOpenDate"
    LATEST_AIS_LOCATION = "LatestAisLocation"

EtaConfiguration

Bases: _EtaConfigurationFields

A custom ETA calculation, for supply trend and historical supply.

Attributes:

Name Type Description
basis_port_id int

The port to calculate the ETA to.

speed Optional[float]

Speed in knots. The API uses 12 when not set.

sea_margin Optional[float]

Extra time in percent, for example 10 for 10%.

eta_calculation_basis Optional[str]

See EtaCalculationBasis.

eta Optional[MinMaxRange]

Absolute ETA range. Cannot be combined with eta_relative_offset.

eta_relative_offset Optional[MinMaxRange]

ETA range in days from the snapshot day.

id Optional[str]

Identifier returned in each vessel's eta_details.

Source code in signal_ocean/supply/filters.py
359
360
361
362
363
364
365
366
367
368
369
370
371
class EtaConfiguration(_EtaConfigurationFields):
    """A custom ETA calculation, for supply trend and historical supply.

    Attributes:
        basis_port_id: The port to calculate the ETA to.
        speed: Speed in knots. The API uses 12 when not set.
        sea_margin: Extra time in percent, for example 10 for 10%.
        eta_calculation_basis: See `EtaCalculationBasis`.
        eta: Absolute ETA range. Cannot be combined with
            `eta_relative_offset`.
        eta_relative_offset: ETA range in days from the snapshot day.
        id: Identifier returned in each vessel's `eta_details`.
    """

EtaConfigurationWithRestrictions

Bases: _EtaConfigurationFields

A custom ETA calculation with routing restrictions, for live supply.

Attributes:

Name Type Description
restrictions Optional[str]

See Restrictions. The other attributes are the same as in EtaConfiguration.

Source code in signal_ocean/supply/filters.py
374
375
376
377
378
379
380
381
382
class EtaConfigurationWithRestrictions(_EtaConfigurationFields):
    """A custom ETA calculation with routing restrictions, for live supply.

    Attributes:
        restrictions: See `Restrictions`. The other attributes are the same
            as in `EtaConfiguration`.
    """

    restrictions: Optional[str] = None

FromToRange

Bases: SupplyRequestModel

Inclusive range with from and to bounds.

Attributes:

Name Type Description
from_ Any

Lower bound, sent as from. A number, a date or a datetime.

to Any

Upper bound. A number, a date or a datetime.

Source code in signal_ocean/supply/filters.py
14
15
16
17
18
19
20
21
22
23
24
25
26
class FromToRange(SupplyRequestModel):
    """Inclusive range with `from` and `to` bounds.

    Attributes:
        from_: Lower bound, sent as `from`. A number, a date or a datetime.
        to: Upper bound. A number, a date or a datetime.
    """

    # Not `alias`: type checkers would then expect the keyword `from`.
    from_: Any = Field(
        None, validation_alias="from", serialization_alias="from"
    )
    to: Any = None

GeoLocation

Bases: SupplyRequestModel

A location for the location filters.

Attributes:

Name Type Description
geo_id int

The Signal geo identifier.

location_taxonomy int

The location level. See LocationTaxonomy.

Source code in signal_ocean/supply/filters.py
65
66
67
68
69
70
71
72
73
74
class GeoLocation(SupplyRequestModel):
    """A location for the location filters.

    Attributes:
        geo_id: The Signal geo identifier.
        location_taxonomy: The location level. See `LocationTaxonomy`.
    """

    geo_id: int
    location_taxonomy: int

HeadingRange

Bases: SupplyRequestModel

Compass heading range in degrees, with start <= end.

Attributes:

Name Type Description
start float

First heading, 0 to 360.

end float

Last heading, 0 to 360.

Source code in signal_ocean/supply/filters.py
53
54
55
56
57
58
59
60
61
62
class HeadingRange(SupplyRequestModel):
    """Compass heading range in degrees, with `start` <= `end`.

    Attributes:
        start: First heading, 0 to 360.
        end: Last heading, 0 to 360.
    """

    start: float
    end: float

ImoType

IMO ship types, for imo_type.

Source code in signal_ocean/supply/constants.py
161
162
163
164
165
166
167
168
class ImoType(metaclass=IterableConstants):
    """IMO ship types, for `imo_type`."""

    NONE = "None"
    TYPE1 = "Type1"
    TYPE2 = "Type2"
    TYPE3 = "Type3"
    NO_IMO_TYPE = "NoImoType"

IncludeExcludeFilter

Bases: SupplyRequestModel

Values to include and values to exclude.

Attributes:

Name Type Description
values Optional[List[Any]]

Values to include.

excluded Optional[List[Any]]

Values to exclude. A value cannot be in both lists.

Source code in signal_ocean/supply/filters.py
41
42
43
44
45
46
47
48
49
50
class IncludeExcludeFilter(SupplyRequestModel):
    """Values to include and values to exclude.

    Attributes:
        values: Values to include.
        excluded: Values to exclude. A value cannot be in both lists.
    """

    values: Optional[List[Any]] = None
    excluded: Optional[List[Any]] = None

LiveSupplyFilter

Bases: _SupplyFilterFields

Filters for live supply, where ETA calculations take restrictions.

The attributes are the same as in SupplyFilter, except that eta_configuration also accepts EtaConfigurationWithRestrictions.

Source code in signal_ocean/supply/filters.py
426
427
428
429
430
431
432
433
434
435
class LiveSupplyFilter(_SupplyFilterFields):
    """Filters for live supply, where ETA calculations take restrictions.

    The attributes are the same as in `SupplyFilter`, except that
    `eta_configuration` also accepts `EtaConfigurationWithRestrictions`.
    """

    eta_configuration: Optional[
        List[Union[EtaConfiguration, EtaConfigurationWithRestrictions]]
    ] = None

LocationTaxonomy

Location levels, for GeoLocation.location_taxonomy.

Source code in signal_ocean/supply/constants.py
171
172
173
174
175
176
177
178
class LocationTaxonomy(metaclass=IterableConstants):
    """Location levels, for `GeoLocation.location_taxonomy`."""

    GEO_ASSET = 1
    PORT = 2
    COUNTRY = 3
    LEVEL0 = 4
    LEVEL1 = 5

MarketDeployment

Market deployment types, for market_deployment.

Source code in signal_ocean/supply/constants.py
83
84
85
86
87
88
89
class MarketDeployment(metaclass=IterableConstants):
    """Market deployment types, for `market_deployment`."""

    SPOT = "Spot"
    PROGRAM = "Program"
    RELET = "Relet"
    CONTRACT = "Contract"

MarketStatus

Market push states, for market_status.

Source code in signal_ocean/supply/constants.py
75
76
77
78
79
80
class MarketStatus(metaclass=IterableConstants):
    """Market push states, for `market_status`."""

    NOT_PUSHED = "NotPushed"
    POSS_PUSHED = "PossPushed"
    PUSHED = "Pushed"

MinMaxRange

Bases: SupplyRequestModel

Inclusive range with min and max bounds.

Attributes:

Name Type Description
min Any

Lower bound. A number, a date or a datetime.

max Any

Upper bound. A number, a date or a datetime.

Source code in signal_ocean/supply/filters.py
29
30
31
32
33
34
35
36
37
38
class MinMaxRange(SupplyRequestModel):
    """Inclusive range with `min` and `max` bounds.

    Attributes:
        min: Lower bound. A number, a date or a datetime.
        max: Upper bound. A number, a date or a datetime.
    """

    min: Any = None
    max: Any = None

PositionSourceOrigin

Position data origins, for position_source_origin.

Source code in signal_ocean/supply/constants.py
92
93
94
95
96
97
98
class PositionSourceOrigin(metaclass=IterableConstants):
    """Position data origins, for `position_source_origin`."""

    NONE = "None"
    MANUAL = "Manual"
    LATEST_POSITION = "LatestPosition"
    SYSTEM = "System"

PositionSourceType

Position data origin types, for position_source_type.

Source code in signal_ocean/supply/constants.py
101
102
103
104
105
106
107
108
109
110
class PositionSourceType(metaclass=IterableConstants):
    """Position data origin types, for `position_source_type`."""

    NONE = "None"
    MODEL_PREDICTION = "ModelPrediction"
    EMAIL = "Email"
    SLACK = "Slack"
    WHATS_APP = "WhatsApp"
    TEAMS = "Teams"
    DATA_PREDICTION = "DataPrediction"

Restrictions

Routing restrictions of a live ETA calculation.

Source code in signal_ocean/supply/constants.py
137
138
139
140
141
142
143
144
145
146
class Restrictions(metaclass=IterableConstants):
    """Routing restrictions of a live ETA calculation."""

    NONE = "None"
    MESSINA = "Messina"
    ORESUND = "Oresund"
    PANAMA = "Panama"
    SUEZ = "Suez"
    SUEZ_OPEN_ONLY_NORTH_BOUND = "SuezOpenOnlyNorthBound"
    ALL = "All"

SupplyAPI

Retrieves vessel supply: daily counts, one day's vessels, live.

Source code in signal_ocean/supply/api.py
 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
class SupplyAPI:
    """Retrieves vessel supply: daily counts, one day's vessels, live."""

    relative_url = "supply-api/v1/supply/"

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

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

    def get_supply_trend(
        self,
        start_date: date,
        end_date: date,
        template: Optional[str] = None,
        filters: Optional[SupplyFilter] = None,
    ) -> SupplyTrend:
        """Count the vessels that match the filters on each day of a range.

        Args:
            start_date: First day of the range.
            end_date: Last day of the range.
            template: A Baltic route code, for example `TD3C`. See
                `get_supply_templates`.
            filters: Filters. A field set here replaces the template's
                value for that field.

        Returns:
            One count per day, and the API's notes.
        """
        body = {
            "startDate": start_date.isoformat(),
            "endDate": end_date.isoformat(),
            **_filter_body(template, filters),
        }
        data = self.__post("supply-trend", body)
        return SupplyTrend.model_validate(data)

    def get_historical_supply(
        self,
        day: date,
        template: Optional[str] = None,
        filters: Optional[SupplyFilter] = None,
        use_only_hub_ports: Optional[bool] = None,
    ) -> SupplySnapshot:
        """Get the vessels that matched the filters on one past day.

        Each subscription key can make a limited number of these calls per
        day.

        Args:
            day: The snapshot day.
            template: A Baltic route code, for example `TD3C`.
            filters: Filters. A field set here replaces the template's
                value for that field.
            use_only_hub_ports: True remaps each ETA basis port that is not
                a hub port to the hub port of its region. False uses the
                ports as given. None sends nothing, so the API default
                (False) applies.

        Returns:
            One record per vessel.
        """
        body = {
            "startDate": day.isoformat(),
            "endDate": day.isoformat(),
            **_filter_body(template, filters),
        }
        headers = None
        if use_only_hub_ports is not None:
            headers = {"UseOnlyHubPorts": str(use_only_hub_ports).lower()}
        data = self.__post("historical-raw-data", body, headers)
        return SupplySnapshot.model_validate(data)

    def get_live_supply(
        self,
        template: Optional[str] = None,
        filters: Optional[Union[SupplyFilter, LiveSupplyFilter]] = None,
        include_details: bool = False,
    ) -> SupplySnapshot:
        """Get the vessels that match the filters now.

        Args:
            template: A Baltic route code, for example `TD3C`.
            filters: Filters. Use `LiveSupplyFilter` for ETA calculations
                with routing restrictions.
            include_details: True adds your company's notes to each record.

        Returns:
            One record per vessel.
        """
        body: Dict[str, Any] = dict(_filter_body(template, filters))
        if include_details:
            body["includeDetails"] = True
        data = self.__post("supply", body)
        snapshot = SupplySnapshot.model_validate(data)
        return snapshot.model_copy(update={"include_details": include_details})

    def get_supply_templates(self) -> Tuple[SupplyTemplate, ...]:
        """Get the Baltic route templates.

        Returns:
            The templates. Pass a template's `code` as `template`.
        """
        return get_supply_templates()

    def __post(
        self,
        operation: str,
        body: Dict[str, Any],
        headers: Optional[Dict[str, str]] = None,
    ) -> Any:
        response = self.__connection._make_post_request(
            self.relative_url + operation, body, headers=headers
        )
        _raise_for_status(response)
        return response.json()

__init__(connection=None)

Initializes the Supply API.

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/supply/api.py
23
24
25
26
27
28
29
30
def __init__(self, connection: Optional[Connection] = None):
    """Initializes the Supply API.

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

get_historical_supply(day, template=None, filters=None, use_only_hub_ports=None)

Get the vessels that matched the filters on one past day.

Each subscription key can make a limited number of these calls per day.

Parameters:

Name Type Description Default
day date

The snapshot day.

required
template Optional[str]

A Baltic route code, for example TD3C.

None
filters Optional[SupplyFilter]

Filters. A field set here replaces the template's value for that field.

None
use_only_hub_ports Optional[bool]

True remaps each ETA basis port that is not a hub port to the hub port of its region. False uses the ports as given. None sends nothing, so the API default (False) applies.

None

Returns:

Type Description
SupplySnapshot

One record per vessel.

Source code in signal_ocean/supply/api.py
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
def get_historical_supply(
    self,
    day: date,
    template: Optional[str] = None,
    filters: Optional[SupplyFilter] = None,
    use_only_hub_ports: Optional[bool] = None,
) -> SupplySnapshot:
    """Get the vessels that matched the filters on one past day.

    Each subscription key can make a limited number of these calls per
    day.

    Args:
        day: The snapshot day.
        template: A Baltic route code, for example `TD3C`.
        filters: Filters. A field set here replaces the template's
            value for that field.
        use_only_hub_ports: True remaps each ETA basis port that is not
            a hub port to the hub port of its region. False uses the
            ports as given. None sends nothing, so the API default
            (False) applies.

    Returns:
        One record per vessel.
    """
    body = {
        "startDate": day.isoformat(),
        "endDate": day.isoformat(),
        **_filter_body(template, filters),
    }
    headers = None
    if use_only_hub_ports is not None:
        headers = {"UseOnlyHubPorts": str(use_only_hub_ports).lower()}
    data = self.__post("historical-raw-data", body, headers)
    return SupplySnapshot.model_validate(data)

get_live_supply(template=None, filters=None, include_details=False)

Get the vessels that match the filters now.

Parameters:

Name Type Description Default
template Optional[str]

A Baltic route code, for example TD3C.

None
filters Optional[Union[SupplyFilter, LiveSupplyFilter]]

Filters. Use LiveSupplyFilter for ETA calculations with routing restrictions.

None
include_details bool

True adds your company's notes to each record.

False

Returns:

Type Description
SupplySnapshot

One record per vessel.

Source code in signal_ocean/supply/api.py
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
def get_live_supply(
    self,
    template: Optional[str] = None,
    filters: Optional[Union[SupplyFilter, LiveSupplyFilter]] = None,
    include_details: bool = False,
) -> SupplySnapshot:
    """Get the vessels that match the filters now.

    Args:
        template: A Baltic route code, for example `TD3C`.
        filters: Filters. Use `LiveSupplyFilter` for ETA calculations
            with routing restrictions.
        include_details: True adds your company's notes to each record.

    Returns:
        One record per vessel.
    """
    body: Dict[str, Any] = dict(_filter_body(template, filters))
    if include_details:
        body["includeDetails"] = True
    data = self.__post("supply", body)
    snapshot = SupplySnapshot.model_validate(data)
    return snapshot.model_copy(update={"include_details": include_details})

get_supply_templates()

Get the Baltic route templates.

Returns:

Type Description
Tuple[SupplyTemplate, ...]

The templates. Pass a template's code as template.

Source code in signal_ocean/supply/api.py
120
121
122
123
124
125
126
def get_supply_templates(self) -> Tuple[SupplyTemplate, ...]:
    """Get the Baltic route templates.

    Returns:
        The templates. Pass a template's `code` as `template`.
    """
    return get_supply_templates()

get_supply_trend(start_date, end_date, template=None, filters=None)

Count the vessels that match the filters on each day of a range.

Parameters:

Name Type Description Default
start_date date

First day of the range.

required
end_date date

Last day of the range.

required
template Optional[str]

A Baltic route code, for example TD3C. See get_supply_templates.

None
filters Optional[SupplyFilter]

Filters. A field set here replaces the template's value for that field.

None

Returns:

Type Description
SupplyTrend

One count per day, and the API's notes.

Source code in signal_ocean/supply/api.py
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
def get_supply_trend(
    self,
    start_date: date,
    end_date: date,
    template: Optional[str] = None,
    filters: Optional[SupplyFilter] = None,
) -> SupplyTrend:
    """Count the vessels that match the filters on each day of a range.

    Args:
        start_date: First day of the range.
        end_date: Last day of the range.
        template: A Baltic route code, for example `TD3C`. See
            `get_supply_templates`.
        filters: Filters. A field set here replaces the template's
            value for that field.

    Returns:
        One count per day, and the API's notes.
    """
    body = {
        "startDate": start_date.isoformat(),
        "endDate": end_date.isoformat(),
        **_filter_body(template, filters),
    }
    data = self.__post("supply-trend", body)
    return SupplyTrend.model_validate(data)

SupplyEta

Bases: SupplyResponseModel

The result of one custom ETA calculation for a vessel.

Attributes:

Name Type Description
basis_port_id Optional[int]

The port of the ETA calculation.

eta Optional[datetime]

The estimated time of arrival.

distance Optional[float]

Distance to the port in nautical miles.

id Optional[str]

The id of the ETA configuration in the request.

canals Optional[Tuple[str, ...]]

Canals on the route.

Source code in signal_ocean/supply/models.py
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
class SupplyEta(SupplyResponseModel):
    """The result of one custom ETA calculation for a vessel.

    Attributes:
        basis_port_id: The port of the ETA calculation.
        eta: The estimated time of arrival.
        distance: Distance to the port in nautical miles.
        id: The `id` of the ETA configuration in the request.
        canals: Canals on the route.
    """

    basis_port_id: Optional[int] = None
    eta: Optional[datetime] = None
    distance: Optional[float] = None
    id: Optional[str] = None
    canals: Optional[Tuple[str, ...]] = None

SupplyFilter

Bases: _SupplyFilterFields

Filters for supply trend, historical supply and live supply.

Give either vessel_class, or all of vessel_type, defining_size and size. The API refuses a request with neither, or with both.

Attributes:

Name Type Description
vessel_class Optional[Union[int, str]]

Class name (see VesselClass) or class id.

vessel_type Optional[Union[int, str]]

Type name (see VesselType) or type id.

size Optional[FromToRange]

Size range, in the unit of defining_size.

defining_size Optional[str]

See DefiningSize.

vessel_subclass Optional[List[str]]

See VesselSubclass.

add_willing_to_switch_subclass Optional[bool]

Also include vessels willing to switch into vessel_subclass.

imo Optional[List[int]]

IMO numbers.

search_text Optional[str]

Text to find in vessel or company names.

commercial_availability Optional[CommercialAvailabilityFilter]

See CommercialAvailabilityFilter.

voyage_details Optional[VoyageDetailsFilter]

See VoyageDetailsFilter.

ais_tracking Optional[AisTrackingFilter]

See AisTrackingFilter.

vessel_particulars Optional[VesselParticularsFilter]

See VesselParticularsFilter.

eta_configuration Optional[List[EtaConfiguration]]

Custom ETA calculations.

Source code in signal_ocean/supply/filters.py
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
class SupplyFilter(_SupplyFilterFields):
    """Filters for supply trend, historical supply and live supply.

    Give either `vessel_class`, or all of `vessel_type`, `defining_size`
    and `size`. The API refuses a request with neither, or with both.

    Attributes:
        vessel_class: Class name (see `VesselClass`) or class id.
        vessel_type: Type name (see `VesselType`) or type id.
        size: Size range, in the unit of `defining_size`.
        defining_size: See `DefiningSize`.
        vessel_subclass: See `VesselSubclass`.
        add_willing_to_switch_subclass: Also include vessels willing to
            switch into `vessel_subclass`.
        imo: IMO numbers.
        search_text: Text to find in vessel or company names.
        commercial_availability: See `CommercialAvailabilityFilter`.
        voyage_details: See `VoyageDetailsFilter`.
        ais_tracking: See `AisTrackingFilter`.
        vessel_particulars: See `VesselParticularsFilter`.
        eta_configuration: Custom ETA calculations.
    """

    eta_configuration: Optional[List[EtaConfiguration]] = None

SupplyRecord

Bases: SupplyResponseModel

The state of one vessel on one day.

Attributes:

Name Type Description
day Optional[datetime]

The snapshot day.

imo Optional[int]

The vessel's IMO number.

vessel_class_id Optional[Union[int, str]]

The vessel class.

vessel_class Optional[str]

The vessel class name.

commercial_availability Optional[CommercialAvailability]

Open location, dates and status.

voyage_details Optional[VoyageDetails]

Voyage state and cargo.

ais_tracking Optional[AisTracking]

AIS position and destination.

eta_details Annotated[Tuple[SupplyEta, ...], _EMPTY_IF_NULL]

One entry per ETA configuration in the request.

details Optional[VesselDetails]

Extra details, only when live supply includes details.

Source code in signal_ocean/supply/models.py
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
class SupplyRecord(SupplyResponseModel):
    """The state of one vessel on one day.

    Attributes:
        day: The snapshot day.
        imo: The vessel's IMO number.
        vessel_class_id: The vessel class.
        vessel_class: The vessel class name.
        commercial_availability: Open location, dates and status.
        voyage_details: Voyage state and cargo.
        ais_tracking: AIS position and destination.
        eta_details: One entry per ETA configuration in the request.
        details: Extra details, only when live supply includes details.
    """

    day: Optional[datetime] = None
    imo: Optional[int] = None
    vessel_class_id: Optional[Union[int, str]] = None
    vessel_class: Optional[str] = None
    commercial_availability: Optional[CommercialAvailability] = None
    voyage_details: Optional[VoyageDetails] = None
    ais_tracking: Optional[AisTracking] = None
    eta_details: Annotated[Tuple[SupplyEta, ...], _EMPTY_IF_NULL] = ()
    details: Optional[VesselDetails] = None

SupplySnapshot

Bases: SupplyResponseModel

Vessel records of one day, from historical or live supply.

Attributes:

Name Type Description
data Annotated[Tuple[SupplyRecord, ...], _EMPTY_IF_NULL]

One record per vessel.

include_details bool

True when the live request asked for details.

Source code in signal_ocean/supply/models.py
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
class SupplySnapshot(SupplyResponseModel):
    """Vessel records of one day, from historical or live supply.

    Attributes:
        data: One record per vessel.
        include_details: True when the live request asked for details.
    """

    data: Annotated[Tuple[SupplyRecord, ...], _EMPTY_IF_NULL] = ()
    include_details: bool = Field(False, exclude=True)

    def to_data_frame(self) -> pd.DataFrame:
        """Return the records as a data frame with one row per vessel.

        Returns:
            A data frame. See `Column` for the column names.
        """
        return snapshot_to_data_frame(self)

to_data_frame()

Return the records as a data frame with one row per vessel.

Returns:

Type Description
DataFrame

A data frame. See Column for the column names.

Source code in signal_ocean/supply/models.py
293
294
295
296
297
298
299
def to_data_frame(self) -> pd.DataFrame:
    """Return the records as a data frame with one row per vessel.

    Returns:
        A data frame. See `Column` for the column names.
    """
    return snapshot_to_data_frame(self)

SupplyTemplate

Bases: SupplyResponseModel

A Baltic route template.

Attributes:

Name Type Description
code str

The route code, for example TD3C.

name str

The template name.

description str

What the template selects.

segment str

Tanker or Dry.

list_type str

The kind of list the template was designed for.

filters SupplyFilter

The filters the template sends.

Source code in signal_ocean/supply/templates.py
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
class SupplyTemplate(SupplyResponseModel):
    """A Baltic route template.

    Attributes:
        code: The route code, for example `TD3C`.
        name: The template name.
        description: What the template selects.
        segment: `Tanker` or `Dry`.
        list_type: The kind of list the template was designed for.
        filters: The filters the template sends.
    """

    code: str
    name: str
    description: str
    segment: str
    list_type: str
    filters: SupplyFilter

SupplyTrend

Bases: SupplyResponseModel

The result of a supply trend request.

Attributes:

Name Type Description
supply_per_day Annotated[Tuple[DailySupply, ...], _EMPTY_IF_NULL]

One count per day of the requested range.

notes Annotated[Tuple[str, ...], _EMPTY_IF_NULL]

Messages from the API, for example about ETA basis ports that were remapped to hub ports.

Source code in signal_ocean/supply/models.py
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
class SupplyTrend(SupplyResponseModel):
    """The result of a supply trend request.

    Attributes:
        supply_per_day: One count per day of the requested range.
        notes: Messages from the API, for example about ETA basis ports
            that were remapped to hub ports.
    """

    supply_per_day: Annotated[
        Tuple[DailySupply, ...], _EMPTY_IF_NULL
    ] = ()
    notes: Annotated[Tuple[str, ...], _EMPTY_IF_NULL] = ()

    def to_data_frame(self) -> pd.DataFrame:
        """Return the counts as a data frame.

        Returns:
            A data frame indexed by `date`, oldest day first, with one
            column `supply`.
        """
        return trend_to_data_frame(self)

to_data_frame()

Return the counts as a data frame.

Returns:

Type Description
DataFrame

A data frame indexed by date, oldest day first, with one

DataFrame

column supply.

Source code in signal_ocean/supply/models.py
49
50
51
52
53
54
55
56
def to_data_frame(self) -> pd.DataFrame:
    """Return the counts as a data frame.

    Returns:
        A data frame indexed by `date`, oldest day first, with one
        column `supply`.
    """
    return trend_to_data_frame(self)

VesselClass

Vessel classes, for vessel_class.

Source code in signal_ocean/supply/constants.py
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
class VesselClass(metaclass=IterableConstants):
    """Vessel classes, for `vessel_class`."""

    VLCC = "VLCC"
    SUEZMAX = "Suezmax"
    AFRAMAX = "Aframax"
    PANAMAX_TANKER = "PanamaxTanker"
    MR2 = "MR2"
    MR1 = "MR1"
    SMALL = "Small"
    VLOC = "VLOC"
    CAPESIZE = "Capesize"
    POST_PANAMAX_DRY = "PostPanamaxDry"
    PANAMAX_DRY = "PanamaxDry"
    SUPRAMAX = "Supramax"
    HANDYMAX = "Handymax"
    HANDYSIZE = "Handysize"
    SMALL_DRY = "SmallDry"
    LNG = "LNGLng"
    VLGC_LPG = "VLGCLpg"
    MIDSIZE_LPG = "MidsizeLpg"
    HANDY_LPG = "HandyLpg"
    SMALL_LPG = "SmallLpg"

VesselDetails

Bases: SupplyResponseModel

Extra vessel details, returned when live supply includes details.

Attributes:

Name Type Description
notes Optional[str]

Your company's notes on the vessel.

Source code in signal_ocean/supply/models.py
246
247
248
249
250
251
252
253
class VesselDetails(SupplyResponseModel):
    """Extra vessel details, returned when live supply includes details.

    Attributes:
        notes: Your company's notes on the vessel.
    """

    notes: Optional[str] = None

VesselParticularsFilter

Bases: SupplyRequestModel

Filters on vessel characteristics, ownership and sanctions.

Attributes:

Name Type Description
commercial_operator Optional[IncludeExcludeFilter]

Company ids of the commercial operator, the company that decides the employment of the vessel.

liquid_capacity Optional[MinMaxRange]

Liquid capacity in cubic metres.

ice_class Optional[List[str]]

Ice class names.

cranes_ton_capacity Optional[MinMaxRange]

Crane capacity in tonnes.

length_overall Optional[MinMaxRange]

Length overall (LOA) in metres.

breadth_extreme Optional[MinMaxRange]

Breadth in metres.

air_draught Optional[MinMaxRange]

Air draught in metres.

ballast_parallel_body_length Optional[MinMaxRange]

Parallel body length in ballast, in metres.

bow_to_center_manifold Optional[MinMaxRange]

Bow to center manifold, in metres.

class_renewal_date Optional[MinMaxRange]

Class renewal date.

built_country_code Optional[IncludeExcludeFilter]

ISO codes of the build country.

built_country_name Optional[IncludeExcludeFilter]

Names of the build country.

crude_oil_washing Optional[bool]

Crude oil washing system.

delivery_date Optional[MinMaxRange]

Delivery date.

flag_code Optional[IncludeExcludeFilter]

ISO codes of the flag state.

heating_coils_fitted Optional[bool]

Heating coils fitted.

inert_gas_system Optional[bool]

Inert gas system.

lightship_tonnes Optional[MinMaxRange]

Lightship weight in tonnes.

main_engine_manufacturer_id Optional[IncludeExcludeFilter]

Main engine manufacturer ids.

main_engine_manufacturer Optional[List[str]]

Main engine manufacturer names.

main_engine_kw Optional[MinMaxRange]

Main engine power in kW.

main_engine_rpm Optional[MinMaxRange]

Main engine RPM.

moulded_depth Optional[MinMaxRange]

Moulded depth in metres.

parallel_body_length Optional[MinMaxRange]

Parallel body length in metres.

reduced_gross_tonnage Optional[MinMaxRange]

Reduced gross tonnage.

shipyard_built_id Optional[IncludeExcludeFilter]

Ids of the shipyard that built the vessel.

stern_line Optional[bool]

Stern line fitted.

water_line_to_manifold Optional[MinMaxRange]

Waterline to manifold, in metres.

built_for_trade_ids Optional[List[int]]

Ids of the trades that the vessel was built for.

bale_capacity Optional[MinMaxRange]

Bale capacity in cubic metres.

co2_fitted Optional[bool]

CO2 system fitted.

grain_capacity Optional[MinMaxRange]

Grain capacity in cubic metres.

neo_panama_locks Optional[bool]

Fits the Neo-Panamax locks.

number_of_holds Optional[MinMaxRange]

Number of holds.

australian_ladder Optional[bool]

Australian ladder fitted.

log_fitted Optional[bool]

Log fitted.

open_hatch Optional[bool]

Open hatch design.

a60_bulkhead Optional[bool]

A60 bulkhead.

gross_registered_tonnage Optional[MinMaxRange]

Gross registered tonnage (GRT).

net_registered_tonnage Optional[MinMaxRange]

Net registered tonnage (NRT).

head_owner_id Optional[IncludeExcludeFilter]

Company ids of the head owner, the owner at the top of the ownership structure.

ballast_water_treatment Optional[bool]

Ballast water treatment system.

draught Optional[MinMaxRange]

Draught in metres.

geared Optional[bool]

Has cranes or other cargo gear. A geared vessel can load and discharge without port cranes.

classification_register_id Optional[IncludeExcludeFilter]

Classification society ids.

vessel_age Optional[MinMaxRange]

Vessel age in years. An alternative to year_built.

coating Optional[str]

Tank coating. See Coating.

imo_type Optional[str]

IMO ship type. See ImoType.

crane_max_out_reach Optional[MinMaxRange]

Maximum crane outreach in metres.

crane_lifting_capacity Optional[MinMaxRange]

Crane lifting capacity in tonnes.

number_of_cranes Optional[MinMaxRange]

Number of cranes.

box_shaped_holds Optional[bool]

Box-shaped holds.

hold_length Optional[MinMaxRange]

Hold length in metres.

hold_height Optional[MinMaxRange]

Hold height in metres.

hold_breadth Optional[MinMaxRange]

Hold breadth in metres.

number_of_hatches Optional[MinMaxRange]

Number of hatches.

has_hatches Optional[bool]

Has hatches.

hatch_length Optional[MinMaxRange]

Hatch length in metres.

hatch_breadth Optional[MinMaxRange]

Hatch breadth in metres.

number_of_grabs Optional[MinMaxRange]

Number of grabs.

has_grabs Optional[bool]

Has grabs.

grab_lifting_capacity Optional[MinMaxRange]

Grab lifting capacity in tonnes.

grab_max_lifting_weight Optional[MinMaxRange]

Maximum grab lifting weight in tonnes.

scrubbers Optional[bool]

Exhaust gas scrubbers fitted. A vessel with scrubbers can burn high-sulphur fuel oil.

year_built Optional[MinMaxRange]

Year built.

number_of_bow_thrusters Optional[MinMaxRange]

Number of bow thrusters.

number_of_bow_chain_stoppers Optional[MinMaxRange]

Number of bow chain stoppers.

propulsion_type Optional[IncludeExcludeFilter]

Propulsion type ids.

gas_containment_type Optional[IncludeExcludeFilter]

Gas containment type ids, for LNG and LPG vessels.

summer_tpc Optional[MinMaxRange]

Summer tonnes per centimetre immersion (TPC).

design_model Optional[IncludeExcludeFilter]

Names of the vessel design model.

sanction_status Optional[IncludeExcludeFilter]

Sanction status ids. Use it to find or remove sanctioned vessels.

trade Optional[IncludeExcludeFilter]

The sub-segment of the vessel within its class. Includes the manual changes of your company.

Source code in signal_ocean/supply/filters.py
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
class VesselParticularsFilter(SupplyRequestModel):
    """Filters on vessel characteristics, ownership and sanctions.

    Attributes:
        commercial_operator: Company ids of the commercial operator, the
            company that decides the employment of the vessel.
        liquid_capacity: Liquid capacity in cubic metres.
        ice_class: Ice class names.
        cranes_ton_capacity: Crane capacity in tonnes.
        length_overall: Length overall (LOA) in metres.
        breadth_extreme: Breadth in metres.
        air_draught: Air draught in metres.
        ballast_parallel_body_length: Parallel body length in ballast, in
            metres.
        bow_to_center_manifold: Bow to center manifold, in metres.
        class_renewal_date: Class renewal date.
        built_country_code: ISO codes of the build country.
        built_country_name: Names of the build country.
        crude_oil_washing: Crude oil washing system.
        delivery_date: Delivery date.
        flag_code: ISO codes of the flag state.
        heating_coils_fitted: Heating coils fitted.
        inert_gas_system: Inert gas system.
        lightship_tonnes: Lightship weight in tonnes.
        main_engine_manufacturer_id: Main engine manufacturer ids.
        main_engine_manufacturer: Main engine manufacturer names.
        main_engine_kw: Main engine power in kW.
        main_engine_rpm: Main engine RPM.
        moulded_depth: Moulded depth in metres.
        parallel_body_length: Parallel body length in metres.
        reduced_gross_tonnage: Reduced gross tonnage.
        shipyard_built_id: Ids of the shipyard that built the vessel.
        stern_line: Stern line fitted.
        water_line_to_manifold: Waterline to manifold, in metres.
        built_for_trade_ids: Ids of the trades that the vessel was built
            for.
        bale_capacity: Bale capacity in cubic metres.
        co2_fitted: CO2 system fitted.
        grain_capacity: Grain capacity in cubic metres.
        neo_panama_locks: Fits the Neo-Panamax locks.
        number_of_holds: Number of holds.
        australian_ladder: Australian ladder fitted.
        log_fitted: Log fitted.
        open_hatch: Open hatch design.
        a60_bulkhead: A60 bulkhead.
        gross_registered_tonnage: Gross registered tonnage (GRT).
        net_registered_tonnage: Net registered tonnage (NRT).
        head_owner_id: Company ids of the head owner, the owner at the top
            of the ownership structure.
        ballast_water_treatment: Ballast water treatment system.
        draught: Draught in metres.
        geared: Has cranes or other cargo gear. A geared vessel can load and
            discharge without port cranes.
        classification_register_id: Classification society ids.
        vessel_age: Vessel age in years. An alternative to `year_built`.
        coating: Tank coating. See `Coating`.
        imo_type: IMO ship type. See `ImoType`.
        crane_max_out_reach: Maximum crane outreach in metres.
        crane_lifting_capacity: Crane lifting capacity in tonnes.
        number_of_cranes: Number of cranes.
        box_shaped_holds: Box-shaped holds.
        hold_length: Hold length in metres.
        hold_height: Hold height in metres.
        hold_breadth: Hold breadth in metres.
        number_of_hatches: Number of hatches.
        has_hatches: Has hatches.
        hatch_length: Hatch length in metres.
        hatch_breadth: Hatch breadth in metres.
        number_of_grabs: Number of grabs.
        has_grabs: Has grabs.
        grab_lifting_capacity: Grab lifting capacity in tonnes.
        grab_max_lifting_weight: Maximum grab lifting weight in tonnes.
        scrubbers: Exhaust gas scrubbers fitted. A vessel with scrubbers can
            burn high-sulphur fuel oil.
        year_built: Year built.
        number_of_bow_thrusters: Number of bow thrusters.
        number_of_bow_chain_stoppers: Number of bow chain stoppers.
        propulsion_type: Propulsion type ids.
        gas_containment_type: Gas containment type ids, for LNG and LPG
            vessels.
        summer_tpc: Summer tonnes per centimetre immersion (TPC).
        design_model: Names of the vessel design model.
        sanction_status: Sanction status ids. Use it to find or remove
            sanctioned vessels.
        trade: The sub-segment of the vessel within its class. Includes
            the manual changes of your company.
    """

    commercial_operator: Optional[IncludeExcludeFilter] = None
    liquid_capacity: Optional[MinMaxRange] = None
    ice_class: Optional[List[str]] = None
    cranes_ton_capacity: Optional[MinMaxRange] = None
    length_overall: Optional[MinMaxRange] = None
    breadth_extreme: Optional[MinMaxRange] = None
    air_draught: Optional[MinMaxRange] = None
    ballast_parallel_body_length: Optional[MinMaxRange] = None
    bow_to_center_manifold: Optional[MinMaxRange] = None
    class_renewal_date: Optional[MinMaxRange] = None
    built_country_code: Optional[IncludeExcludeFilter] = None
    built_country_name: Optional[IncludeExcludeFilter] = None
    crude_oil_washing: Optional[bool] = None
    delivery_date: Optional[MinMaxRange] = None
    flag_code: Optional[IncludeExcludeFilter] = None
    heating_coils_fitted: Optional[bool] = None
    inert_gas_system: Optional[bool] = None
    lightship_tonnes: Optional[MinMaxRange] = None
    main_engine_manufacturer_id: Optional[IncludeExcludeFilter] = None
    main_engine_manufacturer: Optional[List[str]] = None
    main_engine_kw: Optional[MinMaxRange] = None
    main_engine_rpm: Optional[MinMaxRange] = None
    moulded_depth: Optional[MinMaxRange] = None
    parallel_body_length: Optional[MinMaxRange] = None
    reduced_gross_tonnage: Optional[MinMaxRange] = None
    shipyard_built_id: Optional[IncludeExcludeFilter] = None
    stern_line: Optional[bool] = None
    water_line_to_manifold: Optional[MinMaxRange] = None
    built_for_trade_ids: Optional[List[int]] = None
    bale_capacity: Optional[MinMaxRange] = None
    co2_fitted: Optional[bool] = None
    grain_capacity: Optional[MinMaxRange] = None
    neo_panama_locks: Optional[bool] = None
    number_of_holds: Optional[MinMaxRange] = None
    australian_ladder: Optional[bool] = None
    log_fitted: Optional[bool] = None
    open_hatch: Optional[bool] = None
    a60_bulkhead: Optional[bool] = None
    gross_registered_tonnage: Optional[MinMaxRange] = None
    net_registered_tonnage: Optional[MinMaxRange] = None
    head_owner_id: Optional[IncludeExcludeFilter] = None
    ballast_water_treatment: Optional[bool] = None
    draught: Optional[MinMaxRange] = None
    geared: Optional[bool] = None
    classification_register_id: Optional[IncludeExcludeFilter] = None
    vessel_age: Optional[MinMaxRange] = None
    coating: Optional[str] = None
    imo_type: Optional[str] = None
    crane_max_out_reach: Optional[MinMaxRange] = None
    crane_lifting_capacity: Optional[MinMaxRange] = None
    number_of_cranes: Optional[MinMaxRange] = None
    box_shaped_holds: Optional[bool] = None
    hold_length: Optional[MinMaxRange] = None
    hold_height: Optional[MinMaxRange] = None
    hold_breadth: Optional[MinMaxRange] = None
    number_of_hatches: Optional[MinMaxRange] = None
    has_hatches: Optional[bool] = None
    hatch_length: Optional[MinMaxRange] = None
    hatch_breadth: Optional[MinMaxRange] = None
    number_of_grabs: Optional[MinMaxRange] = None
    has_grabs: Optional[bool] = None
    grab_lifting_capacity: Optional[MinMaxRange] = None
    grab_max_lifting_weight: Optional[MinMaxRange] = None
    scrubbers: Optional[bool] = None
    year_built: Optional[MinMaxRange] = None
    number_of_bow_thrusters: Optional[MinMaxRange] = None
    number_of_bow_chain_stoppers: Optional[MinMaxRange] = None
    propulsion_type: Optional[IncludeExcludeFilter] = None
    gas_containment_type: Optional[IncludeExcludeFilter] = None
    summer_tpc: Optional[MinMaxRange] = None
    design_model: Optional[IncludeExcludeFilter] = None
    sanction_status: Optional[IncludeExcludeFilter] = None
    trade: Optional[IncludeExcludeFilter] = None

VesselSubclass

Vessel subclasses, for vessel_subclass.

Source code in signal_ocean/supply/constants.py
50
51
52
53
54
55
56
57
58
59
60
61
class VesselSubclass(metaclass=IterableConstants):
    """Vessel subclasses, for `vessel_subclass`."""

    CRUDE = "Crude"
    PRODUCT = "Product"
    CHEMICAL = "Chemical"
    BULK = "Bulk"
    GENERAL_CARGO = "GeneralCargo"
    REFRIGERATED = "Refrigerated"
    PRESSURIZED = "Pressurized"
    SEMI_PRESSURIZED = "SemiPressurized"
    VLEC = "Vlec"

VesselType

Vessel types, for vessel_type.

Source code in signal_ocean/supply/constants.py
 9
10
11
12
13
14
15
class VesselType(metaclass=IterableConstants):
    """Vessel types, for `vessel_type`."""

    TANKER = "Tanker"
    DRY = "Dry"
    LNG = "LNG"
    LPG = "LPG"

VoyageDetails

Bases: SupplyResponseModel

Voyage state, cargo and recent cargo history of a vessel.

Attributes:

Name Type Description
voyage_state Optional[str]

The phase of the current voyage, for example ballast (empty), laden (with cargo), loading or discharging. See VoyageState.

voyage_state_id Optional[int]

Id of the voyage state.

cargo_type Optional[str]

Name of the current or last cargo type.

cargo_type_id Optional[int]

Id of the current or last cargo type.

cargo_quantity Optional[int]

Cargo quantity in metric tonnes.

charterer Optional[str]

Charterer company name.

charterer_id Optional[int]

Charterer company id.

start_port Optional[str]

Name of the start (load) port of the voyage leg.

start_port_id Optional[int]

Id of the start (load) port of the voyage leg.

last_voyage_cargo_types Optional[Tuple[str, ...]]

Cargo type names of the previous voyage.

last_voyage_cargo_type_ids Optional[Tuple[int, ...]]

Cargo type ids of the previous voyage.

last_cargo_types Optional[Tuple[str, ...]]

Names of the last cargo types, up to 3. The recent cargo history of the vessel.

last_cargo_type_ids Optional[Tuple[int, ...]]

Ids of the last cargo types, up to 3. The recent cargo history of the vessel.

Source code in signal_ocean/supply/models.py
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
151
152
153
154
155
156
157
158
159
160
161
class VoyageDetails(SupplyResponseModel):
    """Voyage state, cargo and recent cargo history of a vessel.

    Attributes:
        voyage_state: The phase of the current voyage, for example ballast
            (empty), laden (with cargo), loading or discharging. See
            `VoyageState`.
        voyage_state_id: Id of the voyage state.
        cargo_type: Name of the current or last cargo type.
        cargo_type_id: Id of the current or last cargo type.
        cargo_quantity: Cargo quantity in metric tonnes.
        charterer: Charterer company name.
        charterer_id: Charterer company id.
        start_port: Name of the start (load) port of the voyage leg.
        start_port_id: Id of the start (load) port of the voyage leg.
        last_voyage_cargo_types: Cargo type names of the previous voyage.
        last_voyage_cargo_type_ids: Cargo type ids of the previous voyage.
        last_cargo_types: Names of the last cargo types, up to 3. The recent
            cargo history of the vessel.
        last_cargo_type_ids: Ids of the last cargo types, up to 3. The recent
            cargo history of the vessel.
    """

    voyage_state: Optional[str] = None
    voyage_state_id: Optional[int] = None
    cargo_type: Optional[str] = None
    cargo_type_id: Optional[int] = None
    cargo_quantity: Optional[int] = None
    charterer: Optional[str] = None
    charterer_id: Optional[int] = None
    start_port: Optional[str] = None
    start_port_id: Optional[int] = None
    last_voyage_cargo_types: Optional[Tuple[str, ...]] = None
    last_voyage_cargo_type_ids: Optional[Tuple[int, ...]] = None
    last_cargo_types: Optional[Tuple[str, ...]] = None
    last_cargo_type_ids: Optional[Tuple[int, ...]] = None

VoyageDetailsFilter

Bases: SupplyRequestModel

Filters on voyage state, cargo, start port and charterer.

start_port takes GeoLocation values; the id filters take integers.

Attributes:

Name Type Description
voyage_state Optional[List[str]]

The phase of the current voyage, for example ballast, laden, loading or discharging. See VoyageState.

reported_last_cargo_type_id Optional[IncludeExcludeFilter]

Cargo type ids of the last reported cargoes, up to 3.

cargo_type_id Optional[IncludeExcludeFilter]

Cargo type id on the current voyage.

last_voyage_cargo_type_id Optional[IncludeExcludeFilter]

Cargo type ids of the previous voyage.

start_port Optional[IncludeExcludeFilter]

The load port of the voyage leg.

cargo_quantity Optional[FromToRange]

Cargo quantity in metric tonnes.

charterer Optional[IncludeExcludeFilter]

Charterer company ids.

Source code in signal_ocean/supply/filters.py
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
class VoyageDetailsFilter(SupplyRequestModel):
    """Filters on voyage state, cargo, start port and charterer.

    `start_port` takes `GeoLocation` values; the id filters take integers.

    Attributes:
        voyage_state: The phase of the current voyage, for example ballast,
            laden, loading or discharging. See `VoyageState`.
        reported_last_cargo_type_id: Cargo type ids of the last reported
            cargoes, up to 3.
        cargo_type_id: Cargo type id on the current voyage.
        last_voyage_cargo_type_id: Cargo type ids of the previous voyage.
        start_port: The load port of the voyage leg.
        cargo_quantity: Cargo quantity in metric tonnes.
        charterer: Charterer company ids.
    """

    voyage_state: Optional[List[str]] = None
    reported_last_cargo_type_id: Optional[IncludeExcludeFilter] = None
    cargo_type_id: Optional[IncludeExcludeFilter] = None
    last_voyage_cargo_type_id: Optional[IncludeExcludeFilter] = None
    start_port: Optional[IncludeExcludeFilter] = None
    cargo_quantity: Optional[FromToRange] = None
    charterer: Optional[IncludeExcludeFilter] = None

VoyageState

Operational voyage states, for voyage_state.

Source code in signal_ocean/supply/constants.py
113
114
115
116
117
118
119
120
121
122
123
124
125
class VoyageState(metaclass=IterableConstants):
    """Operational voyage states, for `voyage_state`."""

    BALLAST_FIXED = "BallastFixed"
    REPAIRS = "Repairs"
    WAIT_TO_LOAD = "WaitToLoad"
    LOADING = "Loading"
    LADEN = "Laden"
    WAIT_TO_DISCHARGE = "WaitToDischarge"
    DISCHARGING = "Discharging"
    ACTIVE_STORAGE = "ActiveStorage"
    BALLAST_FIXED_IMPLIED = "BallastFixedImplied"
    BALLAST_UNFIXED = "BallastUnfixed"