Vessels API Example¶

Run this example in Colab¶

Setup

Install the Signal Ocean SDK:

In [ ]:

pip install signal-ocean

pip install signal-ocean

Import required libraries / APIs / packages:

Import Vessels API and some additional libraries

In [1]:

from signal_ocean.vessels import VesselsAPI
import pandas as pd
from datetime import datetime
from signal_ocean import Connection

from signal_ocean.vessels import VesselsAPI import pandas as pd from datetime import datetime from signal_ocean import Connection

Fill in your personal SignalOcean API subscription key acquired here and open a connection:

In [2]:

signal_ocean_api_key = '' #replace with your subscription key

signal_ocean_api_key = '' #replace with your subscription key

Create a connection

In [3]:

connection = Connection(signal_ocean_api_key)

connection = Connection(signal_ocean_api_key)

Call the vessels API¶

The Vessels API retrieves vessel information.

In [4]:

api = VesselsAPI(connection)

api = VesselsAPI(connection)

Get vessel classes¶

Retrieve information on the various vessel classes

In [5]:

vessel_classes = api.get_vessel_classes()

vessel_classes = api.get_vessel_classes()

Extract the returned information into a dataframe

In [6]:

pd.DataFrame([vc.__dict__ for vc in vessel_classes]).head()

pd.DataFrame([vc.__dict__ for vc in vessel_classes]).head()

Out[6]:

	id	vessel_type_id	from_size	to_size	name	vessel_type	defining_size	size
0	-2	-2	0	0	Not set	Not Set	NotSet	NotSet
1	-1	-1	0	0	Unknown	Unknown	Unknown	Unknown
2	60	6	70001	250000	VLGC	LPG	CubicSize	cbm
3	61	6	28001	70000	Midsize/LGC	LPG	CubicSize	cbm
4	62	6	10001	28000	Handy	LPG	CubicSize	cbm

Get vessel types¶

Retrieve information on the various vessel types

In [7]:

vessel_types = api.get_vessel_types()

vessel_types = api.get_vessel_types()

Extract the returned information into a dataframe

In [8]:

pd.DataFrame([vc.__dict__ for vc in vessel_types]).head(7)

pd.DataFrame([vc.__dict__ for vc in vessel_types]).head(7)

Out[8]:

	id	name
0	-2	Not Set
1	-1	Unknown
2	6	LPG
3	3	Dry
4	4	Container
5	1	Tanker
6	5	LNG

Get details for a specific vessel¶

In [9]:

imo = 9436006
v = api.get_vessel(imo)
print(f'{v.imo}: {v.vessel_name} ({v.vessel_class} / {v.commercial_operator})')

imo = 9436006 v = api.get_vessel(imo) print(f'{v.imo}: {v.vessel_name} ({v.vessel_class} / {v.commercial_operator})')

9436006: Samira (Aframax / Unknown)

Get details for all vessels¶

In [10]:

vessels = api.get_vessels()

vessels = api.get_vessels()

Extract the returned information into a dataframe

In [11]:

df = pd.DataFrame([x.__dict__ for x in vessels])

df = pd.DataFrame([x.__dict__ for x in vessels])

In [12]:

df[['imo', 'vessel_name', 'vessel_class']].sample(5)

df[['imo', 'vessel_name', 'vessel_class']].sample(5)

Out[12]:

	imo	vessel_name	vessel_class
21529	9121950	Ronika	Small
39179	9468152	Diamond Sea	Supramax
24506	9183843	Themsestern	Small
43464	9566435	Sanctum	Supramax
22524	9141302	San Diego	Panamax

Find fleet size per vessel class - exclude scrapped vessels¶

In [13]:

df[pd.isnull(df['scrapped_date'])]['vessel_class'].value_counts().to_frame('vessel_count').head(10)

df[pd.isnull(df['scrapped_date'])]['vessel_class'].value_counts().to_frame('vessel_count').head(10)

Out[13]:

	vessel_count
vessel_class
Small	21886
Panamax	4487
Supramax	4179
Handysize	3565
MR2	2125
Post Panamax	1959
Capesize	1804
Feeder	1662
Aframax	1406
VLCC	1113

Find the commercial operators that currently operate the largest Aframax fleets¶

In [14]:

data = df[(df['vessel_class']=='Aframax')&(pd.isnull(df['scrapped_date']))]
data['commercial_operator'].value_counts().head(10)

data = df[(df['vessel_class']=='Aframax')&(pd.isnull(df['scrapped_date']))] data['commercial_operator'].value_counts().head(10)

Out[14]:

commercial_operator
Unknown                          302
Sovcomflot                        49
Trafigura                         29
Shell                             29
Maersk                            28
Scorpio Commercial Management     25
Teekay Corp                       24
Cardiff Marine                    22
AET                               22
Thenamaris                        22
Name: count, dtype: int64

Get all vessels the name of which contains the term helen¶

In [15]:

vessels = api.get_vessels('helen')
len(vessels)

vessels = api.get_vessels('helen') len(vessels)

Out[15]:

39

Extract the returned information into a dataframe

In [16]:

df = pd.DataFrame([x.__dict__ for x in vessels])
df.head()

df = pd.DataFrame([x.__dict__ for x in vessels]) df.head()

Out[16]:

	imo	vessel_type_id	built_for_trade_id	trade_id	vessel_class_id	commercial_operator_id	deadweight	breadth_extreme	gross_rated_tonnage	reduced_gross_tonnage	...	empty_parallel_body_length	stern_line	yard_number	design_model	bow_to_center_manifold	water_line_to_manifold	deck_to_center_manifold	rail_to_center_manifold	bow_chain_stoppers_fitted	sanctions_history
0	6716857	4	-1	-1	95	-1	1180	11	953	762	...	NaN	None	None	None	NaN	NaN	NaN	NaN	None	None
1	7360083	1	1	1	84	-1	274333	52	133871	98338	...	NaN	None	None	None	NaN	NaN	NaN	NaN	None	None
2	7915644	3	4	4	74	-1	69420	32	41644	33659	...	NaN	None	None	None	NaN	NaN	NaN	NaN	None	None
3	8120571	3	4	4	77	-1	34913	28	20922	16169	...	NaN	None	None	None	NaN	NaN	NaN	NaN	None	None
4	8671702	3	4	4	77	-1	26700	24	16490	16182	...	NaN	None	None	None	NaN	NaN	NaN	NaN	None	None

5 rows × 115 columns

Get Vessel Names Changes¶

You can get Vessel Name changes for all vessels or for a specific one

In [17]:

imo = 9436006
vessels_names = api.get_vessels_name_history(imo)

imo = 9436006 vessels_names = api.get_vessels_name_history(imo)

In [18]:

df = pd.DataFrame([x.__dict__ for x in vessels_names[0].history[0].values])

df = pd.DataFrame([x.__dict__ for x in vessels_names[0].history[0].values])

In [19]:

df

df

Out[19]:

	value	begin_date	end_date	name
0	Stealth Chios	1900-01-01 00:00:00+00:00	2012-01-01 23:13:55+00:00	None
1	Signal Cheetah	2012-01-01 23:13:55+00:00	2021-02-25 23:56:31+00:00	None
2	Stealth Chios	2021-02-25 23:56:31+00:00	2021-05-01 07:41:09+00:00	None
3	Paramount	2021-05-01 07:41:09+00:00	2023-03-10 18:59:11+00:00	None
4	Samsun	2023-03-10 18:59:11+00:00	2025-05-18 11:24:57+00:00	None
5	Samira	2025-05-18 11:24:57+00:00	9999-12-31 23:59:59.999999+00:00	None

Get Commercial Operator Changes¶

You can get Vessel comOpp changes for all vessels or for a specific one

In [20]:

imo = 9436006
vessels_commOps = api.get_vessels_commOp_history(imo)

imo = 9436006 vessels_commOps = api.get_vessels_commOp_history(imo)

In [21]:

df = pd.DataFrame([x.__dict__ for x in vessels_commOps[0].history[0].values])

df = pd.DataFrame([x.__dict__ for x in vessels_commOps[0].history[0].values])

In [22]:

df

df

Out[22]:

	value	begin_date	end_date	name
0	1926	1900-01-01 00:00:00+00:00	2016-06-12 13:03:12+00:00	Signal Maritime
1	1713	2016-06-12 13:03:12+00:00	2016-06-13 13:03:12+00:00	Trafigura
2	1926	2016-06-13 13:03:12+00:00	2021-02-22 00:00:00+00:00	Signal Maritime
3	1597	2021-02-22 00:00:00+00:00	2025-01-09 14:59:56+00:00	Stealth Maritime Corp
4	-1	2025-01-09 14:59:56+00:00	9999-12-31 23:59:59.999999+00:00	Unknown

Get Flag Changes¶

You can get Vessel Flag changes for all vessels or for a specific one

In [23]:

imo = 9436006
vessels_flags = api.get_vessels_flag_history(imo)

imo = 9436006 vessels_flags = api.get_vessels_flag_history(imo)

In [24]:

df = pd.DataFrame([x.__dict__ for x in vessels_flags[0].history[0].values])

df = pd.DataFrame([x.__dict__ for x in vessels_flags[0].history[0].values])

In [25]:

df

df

Out[25]:

	value	begin_date	end_date	name
0	CY	1900-01-01 00:00:00+00:00	2009-05-07 10:46:24+00:00	Cyprus
1	MH	2009-05-07 10:46:24+00:00	2009-07-06 15:53:10+00:00	Marshall Islands
2	GR	2009-07-06 15:53:10+00:00	2014-04-28 11:44:52+00:00	Greece
3	MT	2014-04-28 11:44:52+00:00	2021-02-26 14:17:30.780000+00:00	Malta
4	MH	2021-02-26 14:17:30.780000+00:00	2023-03-22 16:23:00.150000+00:00	Marshall Islands
5	PA	2023-03-22 16:23:00.150000+00:00	2025-06-18 22:14:26.711006+00:00	Panama
6	KM	2025-06-18 22:14:26.711006+00:00	9999-12-31 23:59:59.999999+00:00	Comoros