MR2 ARA Supply Versus Market Rates¶
Run this example in Colab.¶
APIs Used : Supply API, Market Rates API
Description :
In this Notebook the main goal is to construct and display the vessel count per day for MR2 tankers with respect to the ARA area.
The script walks through the installation of the Signal Ocean SDK and the import of the required dependencies.
Then the parameters are set, the Supply API and the Market Rates API are called for the data, and the chart shows both as time series.
Output : Time-Series Graph displaying the supply of MR2 vessels in the ARA region versus the corresponding Market Rates.
Setup¶
!pip install signal-ocean
Import required dependencies:
from datetime import date, timedelta
import pandas as pd
import matplotlib.pyplot as plt
from signal_ocean import Connection
from signal_ocean.geos import GeosAPI
from signal_ocean.market_rates import MarketRatesAPI, CargoId
from signal_ocean.supply import (
AisTrackingFilter,
EtaConfiguration,
MinMaxRange,
SupplyAPI,
SupplyFilter,
VesselSubclass,
)
from signal_ocean.vessels import VesselsAPI
Parametrization¶
Commercial availability history in the Supply API starts on 29 January 2026, so the look-back starts on that day at the earliest.
signal_ocean_api_key = "" # Replace with your subscription key
vessel_class_name = "MR2" # Focus on the MR2 segment
load_port_name = "Rotterdam" # The basis port of the supply
days_back = 365 # Last year info
laycan_end_in_days = 7 # Laycan day window
latest_ais_since = 5 # Filtering out vessels missing recent AIS info
route_description = "MR2 - Cont/USAC" # Route Abbreviation for Market Rates retrieval later
today = date.today()
start_date = max(date(2026, 1, 29), today - timedelta(days=days_back)) # set start date for the Chart window
end_date = today - timedelta(1) # set end date for the Chart window
Get your personal Signal Ocean API subscription key (acquired here) and use it to create a Connection. Your key needs access to the Supply API for the vessel class that you query.
connection = Connection(signal_ocean_api_key)
Create instances of APIs used throughout this notebook:
supply_api = SupplyAPI(connection)
market_rate_api = MarketRatesAPI(connection)
geos_api = GeosAPI(connection)
vessels_api = VesselsAPI(connection)
For more information, see the Supply and Market Rates API sections.
Main CodeBlock¶
Fetch the supply trend¶
The Vessels API gives the vessel class id for the market rates, and the Geos API gives the load port id.
vessel_class = next(
c for c in vessels_api.get_vessel_classes()
if c.name == vessel_class_name and c.vessel_type_id == 1
)
load_port = next(p for p in geos_api.get_ports() if p.port_name == load_port_name)
vessel_class.id, load_port.port_id
(88, 3689)
Clean (product) MR2 tankers with recent AIS that can reach Rotterdam within the laycan window:
supply_filter = SupplyFilter(
vessel_class=vessel_class_name,
vessel_subclass=[VesselSubclass.PRODUCT],
ais_tracking=AisTrackingFilter(days_since_latest_ais=latest_ais_since),
eta_configuration=[
EtaConfiguration(
id="load_port",
basis_port_id=load_port.port_id,
eta_relative_offset=MinMaxRange(min=0, max=laycan_end_in_days),
)
],
)
supply_trend = supply_api.get_supply_trend(
start_date, end_date, filters=supply_filter
).to_data_frame()
supply_trend
| supply | |
|---|---|
| date | |
| 2026-01-29 | 888 |
| 2026-01-30 | 865 |
| 2026-01-31 | 885 |
| 2026-02-01 | 907 |
| 2026-02-02 | 935 |
| ... | ... |
| 2026-11-06 | 919 |
| 2026-11-07 | 937 |
| 2026-11-08 | 939 |
| 2026-11-09 | 965 |
| 2026-11-10 | 956 |
286 rows Ć 1 columns
Get daily market rates for the route of interest¶
We'll need a helper function to find our desired route for the market rates:
def return_selected_route(vessel_class, route_description):
vessel_routes = market_rate_api.get_routes(vessel_class_id=vessel_class.id)
for i, _ in enumerate(vessel_routes):
if vessel_routes[i].description == route_description:
break
return vessel_routes[i]
Which we can use to find the route object returned from the Market Rates API:
market_rate_route = return_selected_route(vessel_class, route_description)
market_rate_route
Route(id='R27', description='MR2 - Cont/USAC', unit='WS', vessel_class_id=88, cargo_id=1, load_port_id=3688, discharge_port_id=3864, load_area_id=24758, discharge_area_id=24747, load_port_2_id=None, discharge_port_2_id=None, load_area_2_id=None, discharge_area_2_id=None, deprecated_to=None, deprecated_since=None)
And use it to query for market rates:
market_rates = market_rate_api.get_market_rates(
start_date,
route_id=market_rate_route.id,
vessel_class_id=vessel_class.id,
end_date=end_date,
cargo_id=CargoId(market_rate_route.cargo_id)
)
market_rates = pd.DataFrame([vars(vr) for vr in market_rates])
market_rates["rate_date"] = pd.to_datetime(market_rates["rate_date"])
market_rates = market_rates.set_index("rate_date")
market_rates
| route_id | rate_value | unit | vessel_class_id | deprecated_to | |
|---|---|---|---|---|---|
| rate_date | |||||
| 2026-01-29 00:00:00+00:00 | R27 | 120.0 | WS | 88 | None |
| 2026-01-30 00:00:00+00:00 | R27 | 120.0 | WS | 88 | None |
| 2026-01-31 00:00:00+00:00 | R27 | 120.0 | WS | 88 | None |
| 2026-02-01 00:00:00+00:00 | R27 | 120.0 | WS | 88 | None |
| 2026-02-02 00:00:00+00:00 | R27 | 130.0 | WS | 88 | None |
| ... | ... | ... | ... | ... | ... |
| 2026-11-06 00:00:00+00:00 | R27 | 210.0 | WS | 88 | None |
| 2026-11-07 00:00:00+00:00 | R27 | 210.0 | WS | 88 | None |
| 2026-11-08 00:00:00+00:00 | R27 | 210.0 | WS | 88 | None |
| 2026-11-09 00:00:00+00:00 | R27 | 190.0 | WS | 88 | None |
| 2026-11-10 00:00:00+00:00 | R27 | 190.0 | WS | 88 | None |
286 rows Ć 5 columns
Plot the daily supply trend with market rates¶
def plot_drawing():
fig, axs = plt.subplots(figsize=(15, 6))
supply_counts = supply_trend["supply"]
supply_counts.index = supply_counts.index.strftime("%d %b %y")
# Left axis (Supply plot)
supply_plot = supply_counts.plot(ax=axs, color="#3086EF", marker="o")
supply_plot.set_ylabel(
"Vessel count", color=plt.gca().lines[-1].get_color(), fontsize=14
)
supply_plot.set_ylim(ymin=0)
# Right axis (Market rate plot)
market_rates.index = market_rates.index.strftime("%d %b %y")
mr_plot = market_rates.plot(
ax=axs, y="rate_value", secondary_y=True, color="#F06C6E", marker="d"
)
mr_plot.set_ylabel(
"Market Rates (WS)", color=plt.gca().lines[-1].get_color(), fontsize=14
)
axs.set_xlim(0, len(supply_counts) - 1)
axs.set_xlabel("")
axs.get_legend().remove()
Output¶
plot_drawing()
connection.close()