Setup¶
Install the Signal Ocean SDK:
pip install signal-ocean
You need your own API key with access to the Supply API, for the vessel classes that you query. Get your key here: https://apis.signalocean.com/profile
In [ ]:
Copied!
!pip install signal-ocean
!pip install signal-ocean
In [2]:
Copied!
signal_ocean_api_key = '' # Replace with your subscription key
signal_ocean_api_key = '' # Replace with your subscription key
In [3]:
Copied!
from datetime import date
from signal_ocean import Connection
from signal_ocean.supply import (
CommercialAvailabilityFilter,
FromToRange,
GeoLocation,
IncludeExcludeFilter,
LocationTaxonomy,
SupplyAPI,
SupplyFilter,
VesselClass,
)
connection = Connection(signal_ocean_api_key)
api = SupplyAPI(connection)
from datetime import date
from signal_ocean import Connection
from signal_ocean.supply import (
CommercialAvailabilityFilter,
FromToRange,
GeoLocation,
IncludeExcludeFilter,
LocationTaxonomy,
SupplyAPI,
SupplyFilter,
VesselClass,
)
connection = Connection(signal_ocean_api_key)
api = SupplyAPI(connection)
Filters¶
open_location: Houston, the port with geo id 3853.open_date_relative_offset: open from 5 days ago up to 20 days ahead.latest_updated_date_relative_offset: updated in the last 5 days.
Relative offsets count days from each snapshot day on the trend, and from today on live supply.
In [4]:
Copied!
houston = GeoLocation(geo_id=3853, location_taxonomy=LocationTaxonomy.PORT)
filters = SupplyFilter(
vessel_class=VesselClass.AFRAMAX,
commercial_availability=CommercialAvailabilityFilter(
open_location=IncludeExcludeFilter(values=[houston]),
open_date_relative_offset=FromToRange(from_=-5, to=20),
latest_updated_date_relative_offset=FromToRange(from_=-5, to=0),
),
)
houston = GeoLocation(geo_id=3853, location_taxonomy=LocationTaxonomy.PORT)
filters = SupplyFilter(
vessel_class=VesselClass.AFRAMAX,
commercial_availability=CommercialAvailabilityFilter(
open_location=IncludeExcludeFilter(values=[houston]),
open_date_relative_offset=FromToRange(from_=-5, to=20),
latest_updated_date_relative_offset=FromToRange(from_=-5, to=0),
),
)
Supply trend¶
In [5]:
Copied!
trend_frame = api.get_supply_trend(date(2026, 8, 1), date(2026, 10, 31), filters=filters).to_data_frame()
trend_frame.tail()
trend_frame = api.get_supply_trend(date(2026, 8, 1), date(2026, 10, 31), filters=filters).to_data_frame()
trend_frame.tail()
Out[5]:
| supply | |
|---|---|
| date | |
| 2026-10-27 | 37 |
| 2026-10-28 | 43 |
| 2026-10-29 | 39 |
| 2026-10-30 | 38 |
| 2026-10-31 | 35 |
In [6]:
Copied!
trend_frame.plot(y="supply", figsize=(12, 5), legend=False,
title="Aframax tankers opening in Houston within 20 days", ylabel="Vessels", xlabel="")
trend_frame.plot(y="supply", figsize=(12, 5), legend=False,
title="Aframax tankers opening in Houston within 20 days", ylabel="Vessels", xlabel="")
Out[6]:
<Axes: title={'center': 'Aframax tankers opening in Houston within 20 days'}, ylabel='Vessels'>
The vessels now, by open date¶
In [7]:
Copied!
live_frame = api.get_live_supply(filters=filters).to_data_frame()
live_frame.sort_values("open_date_to")[
["imo", "open_location", "open_date_from", "open_date_to",
"availability_state", "latest_updated_date"]
]
live_frame = api.get_live_supply(filters=filters).to_data_frame()
live_frame.sort_values("open_date_to")[
["imo", "open_location", "open_date_from", "open_date_to",
"availability_state", "latest_updated_date"]
]
Out[7]:
| imo | open_location | open_date_from | open_date_to | availability_state | latest_updated_date | |
|---|---|---|---|---|---|---|
| 8 | 9439395 | US Gulf | 2026-11-11 09:24:46.000+00:00 | 2026-11-11 09:24:46.000+00:00 | PotentiallyFixed | 2026-11-11 10:16:07.920606+00:00 |
| 31 | 9645401 | US Gulf | 2026-11-11 09:32:58.000+00:00 | 2026-11-11 09:32:58.000+00:00 | OnSubs | 2026-11-11 10:04:35.328236+00:00 |
| 25 | 9624067 | US Gulf | 2026-11-11 09:39:06.000+00:00 | 2026-11-11 09:39:06.000+00:00 | Available | 2026-11-11 10:17:56.079665+00:00 |
| 15 | 9777943 | US Gulf | 2026-11-11 09:40:41.000+00:00 | 2026-11-11 09:40:41.000+00:00 | Available | 2026-11-11 10:16:26.370373+00:00 |
| 1 | 1020930 | US Gulf | 2026-11-11 09:40:54.000+00:00 | 2026-11-11 09:40:54.000+00:00 | Available | 2026-11-11 10:15:52.726078+00:00 |
| 5 | 9488023 | US Gulf | 2026-11-11 09:42:37.000+00:00 | 2026-11-11 09:42:37.000+00:00 | PotentiallyFixed | 2026-11-11 10:16:24.491805+00:00 |
| 22 | 1071434 | US Gulf | 2026-11-11 09:43:06.000+00:00 | 2026-11-11 09:43:06.000+00:00 | Available | 2026-11-11 10:16:02.770129+00:00 |
| 24 | 9518892 | US Gulf | 2026-11-11 09:44:49.000+00:00 | 2026-11-11 09:44:49.000+00:00 | Available | 2026-11-11 10:16:21.867342+00:00 |
| 2 | 9414034 | US Gulf | 2026-11-11 09:46:45.000+00:00 | 2026-11-11 09:46:45.000+00:00 | Available | 2026-11-11 10:16:06.035337+00:00 |
| 6 | 9863417 | US Gulf | 2026-11-11 09:47:16.000+00:00 | 2026-11-11 09:47:16.000+00:00 | PotentiallyFixed | 2026-11-11 10:17:26.617904+00:00 |
| 30 | 1054620 | US Gulf | 2026-11-11 09:47:29.000+00:00 | 2026-11-11 09:47:29.000+00:00 | Available | 2026-11-11 10:15:53.579747+00:00 |
| 0 | 9528043 | US Gulf | 2026-11-11 09:48:48.000+00:00 | 2026-11-11 09:48:48.000+00:00 | Available | 2026-11-11 10:16:22.051031+00:00 |
| 13 | 9683013 | US Gulf | 2026-11-11 09:51:06.000+00:00 | 2026-11-11 09:51:06.000+00:00 | OnSubs | 2026-11-11 10:16:25.953700+00:00 |
| 11 | 9787936 | US Gulf | 2026-11-11 09:51:36.000+00:00 | 2026-11-11 09:51:36.000+00:00 | Available | 2026-11-11 10:17:26.340624+00:00 |
| 21 | 9514169 | Houston | 2026-11-12 14:24:03.458+00:00 | 2026-11-12 14:24:03.458+00:00 | Available | 2026-11-11 10:16:27.219695+00:00 |
| 27 | 9947378 | US Gulf | 2026-11-15 18:05:48.791+00:00 | 2026-11-15 18:05:48.791+00:00 | Available | 2026-11-11 10:16:40.887574+00:00 |
| 14 | 9823572 | US Gulf | 2026-11-17 20:46:13.197+00:00 | 2026-11-17 20:46:13.197+00:00 | Available | 2026-11-11 10:16:28.076878+00:00 |
| 28 | 9833723 | US Gulf | 2026-11-18 00:00:00.000+00:00 | 2026-11-18 00:00:00.000+00:00 | Available | 2026-11-11 10:16:29.203239+00:00 |
| 3 | 9417892 | US Gulf | 2026-11-19 08:25:27.019+00:00 | 2026-11-19 08:25:27.019+00:00 | Available | 2026-11-11 10:16:19.553895+00:00 |
| 20 | 9802176 | US Gulf | 2026-11-19 13:10:55.608+00:00 | 2026-11-19 13:10:55.608+00:00 | FullyFixed | 2026-11-11 10:17:55.505120+00:00 |
| 18 | 9572276 | US Gulf | 2026-11-19 15:04:17.108+00:00 | 2026-11-19 15:04:17.108+00:00 | Available | 2026-11-11 10:17:59.273193+00:00 |
| 10 | 9861990 | Houston | 2026-11-19 23:59:59.000+00:00 | 2026-11-19 23:59:59.000+00:00 | FullyFixed | 2026-11-11 10:16:34.787857+00:00 |
| 16 | 9402495 | US Gulf | 2026-11-20 02:22:29.697+00:00 | 2026-11-20 02:22:29.697+00:00 | Available | 2026-11-11 10:16:05.604274+00:00 |
| 4 | 9711468 | Houston | 2026-11-20 04:42:30.817+00:00 | 2026-11-20 04:42:30.817+00:00 | Available | 2026-11-11 10:16:30.853118+00:00 |
| 26 | 9814428 | US Gulf | 2026-11-20 23:59:59.000+00:00 | 2026-11-20 23:59:59.000+00:00 | FullyFixed | 2026-11-11 04:42:10.970491+00:00 |
| 23 | 9767338 | US Gulf | 2026-11-21 04:01:36.040+00:00 | 2026-11-21 04:01:36.040+00:00 | FullyFixed | 2026-11-11 10:16:32.316887+00:00 |
| 19 | 9823560 | US Gulf | 2026-11-24 13:12:38.038+00:00 | 2026-11-24 13:12:38.038+00:00 | FullyFixed | 2026-11-11 10:16:32.880383+00:00 |
| 7 | 9703332 | US Gulf | 2026-11-25 16:49:34.162+00:00 | 2026-11-25 16:49:34.162+00:00 | FullyFixed | 2026-11-11 10:16:43.920179+00:00 |
| 9 | 9645413 | US Gulf | 2026-11-26 04:12:17.231+00:00 | 2026-11-26 04:12:17.231+00:00 | Available | 2026-11-11 10:16:25.198762+00:00 |
| 33 | 9897834 | US Gulf | 2026-11-27 04:50:13.221+00:00 | 2026-11-27 04:50:13.221+00:00 | Available | 2026-11-11 10:04:21.402894+00:00 |
| 17 | 9802152 | US Gulf | 2026-11-29 04:10:07.114+00:00 | 2026-11-29 04:10:07.114+00:00 | Available | 2026-11-11 10:16:28.046792+00:00 |
| 12 | 9397793 | US Gulf | 2026-11-29 09:10:39.649+00:00 | 2026-11-29 09:10:39.649+00:00 | FullyFixed | 2026-11-11 10:16:19.994423+00:00 |
| 29 | 9897846 | US Gulf | 2026-11-29 12:45:47.316+00:00 | 2026-11-29 12:45:47.316+00:00 | Available | 2026-11-11 10:17:27.847994+00:00 |
| 32 | 9417335 | US Gulf | 2026-11-30 10:10:09.638+00:00 | 2026-11-30 10:10:09.638+00:00 | FullyFixed | 2026-11-11 10:16:06.865721+00:00 |
In [8]:
Copied!
connection.close()
connection.close()