Voyages Market Data API Example

Run this example in :

Colab

This Notbook demonstrates some examples of calling the basic API endpoints and the advanced endpoint that provides advanced filtering options.

For the basic endpoints, you can use one of the following :

• a specific imo
• a specific voyage_id
• a specific vessel_class_id
• a specific vessel_type_id

and use the following (optional) parameters : include_vessel_details, include_fixtures, include_lineups, include_positions, include_matched_fixture, include_labels

The advanced endpoint provides you with more options, like :

• imos: provide a list of IMOs
• voyage_ids: provide a list of voyage IDs
• vessel_class_ids: provide a list of vessel class IDs
• trade_id
• fixture_date_from, fixture_date_to, laycan_date_from, laycan_date_to: return market data for the given dates
• charterer_ids_include, charterer_ids_exclude: include/exclude specific charterer IDs
• cargo_type_ids_include, cargo_type_ids_exclude: include/exclude specific cargoes
• sources_include, sources_exclude: include/exclude specific sources
• include_vessel_details, include_fixtures, include_lineups, include_positions, include_matched_fixture, include_labels

Setup

Install the Signal Ocean SDK:

In [ ]:

pip install signal-ocean

pip install signal-ocean

Import Voyages Market Data API and some additional libraries

In [1]:

import pandas as pd
import seaborn as sns

from signal_ocean import Connection
from signal_ocean.voyages_market_data import VoyagesMarketDataAPI

import pandas as pd import seaborn as sns from signal_ocean import Connection from signal_ocean.voyages_market_data import VoyagesMarketDataAPI

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)
api = VoyagesMarketDataAPI(connection)

connection = Connection(signal_ocean_api_key) api = VoyagesMarketDataAPI(connection)

Get market data including matched fixtures for a given vessel class (VLCCs)

In [2]:

result = api.get_voyage_market_data(vessel_class_id=84, include_matched_fixture = True, include_vessel_details = True, include_labels = True, filter_by_matched_fixture = True)

result = api.get_voyage_market_data(vessel_class_id=84, include_matched_fixture = True, include_vessel_details = True, include_labels = True, filter_by_matched_fixture = True)

In [3]:

## Get return data into a dataframe
voyages_market_data = pd.DataFrame([r.__dict__ for r in result])
voyages_market_data.head()

## Get return data into a dataframe voyages_market_data = pd.DataFrame([r.__dict__ for r in result]) voyages_market_data.head()

Out[3]:

	id	voyage_id	imo	voyage_number	vessel_name	vessel_type_id	vessel_type	vessel_class_id	vessel_class	trade_id	trade	commercial_operator_id	commercial_operator	deadweight	year_built	matched_fixture	fixtures
0	MI8A2F75VED1A16F00	I8A2F75VED1A16F00	9056117	50	Symeon II	1	Tanker	84	VLCC	1	Crude	1299.0	Polembros Shipping	277095	1994	MatchedFixture(fixture_status_id=1, fixture_st...	None
1	MI8B5F18VED1A16F00	I8B5F18VED1A16F00	9133848	69	S Tajimare	1	Tanker	84	VLCC	1	Crude	435.0	Dynacom Tankers	265539	1996	MatchedFixture(fixture_status_id=1, fixture_st...	None
2	MI8B98DBVED179E200	I8B98DBVED179E200	9148635	34	DS Velvet	1	Tanker	84	VLCC	1	Crude	510.0	Nayara	301438	1999	MatchedFixture(fixture_status_id=1, fixture_st...	None
3	MI8BC5FEVED1944000	I8BC5FEVED1944000	9160190	41	Kym	1	Tanker	84	VLCC	1	Crude	1906.0	Embiricos Group	298324	1998	MatchedFixture(fixture_status_id=1, fixture_st...	None
4	MI8BC5FEVED1C8FC00	I8BC5FEVED1C8FC00	9160190	42	Kym	1	Tanker	84	VLCC	1	Crude	1906.0	Embiricos Group	298324	1998	MatchedFixture(fixture_status_id=1, fixture_st...	None

In [4]:

## Get matched fixtures seperately into a dataframe
matched_fixtures = pd.DataFrame([r.matched_fixture.__dict__ for r in result])
matched_fixtures.head()

## Get matched fixtures seperately into a dataframe matched_fixtures = pd.DataFrame([r.matched_fixture.__dict__ for r in result]) matched_fixtures.head()

Out[4]:

	fixture_status_id	fixture_status	charter_type_id	charter_type	fixture_date	charterer_id	charterer	laycan_from	laycan_to	load_geo_id	...	redelivery_to_taxonomy_id	redelivery_to_taxonomy	user_entries	full_fixtures	partial_fixtures	is_coa	is_owners_option	is_hold	is_fio	sources
0	1	FullyFixed	0	Voyage	2017-11-24 18:43:41.780000+00:00	180.0	Bharat Oman Refineries	2017-11-28 00:00:00+00:00	2017-11-28 23:59:59+00:00	24777.0	...	None	None	0	2	0	None	None	None	None	(TI app,)
1	1	FullyFixed	0	Voyage	2018-01-09 16:31:15.390000+00:00	718.0	Indian Oil	2018-01-16 00:00:00+00:00	2018-01-17 23:59:59+00:00	24777.0	...	None	None	0	8	0	None	None	None	None	(TI app,)
2	1	FullyFixed	0	Voyage	2017-12-15 00:00:00+00:00	2108.0	Mangalore Refinery and Petrochemicals	2017-12-27 00:00:00+00:00	2017-12-28 23:59:59+00:00	24777.0	...	None	None	0	1	0	None	None	None	None	(TI app,)
3	1	FullyFixed	0	Voyage	2017-11-17 00:00:00+00:00	180.0	Bharat Oman Refineries	2017-12-03 00:00:00+00:00	2017-12-03 23:59:59+00:00	24777.0	...	None	None	0	2	0	None	None	None	None	(TI app,)
4	1	FullyFixed	0	Voyage	2017-12-08 12:34:17.167000+00:00	180.0	Bharat Oman Refineries	2017-12-29 00:00:00+00:00	2017-12-29 23:59:59+00:00	24777.0	...	None	None	0	8	0	None	None	None	None	(TI app,)

5 rows × 57 columns

Get market data including fixtures for a given vessel class (VLCCs)

In [5]:

result = api.get_voyage_market_data(vessel_class_id=84, include_fixtures = True, include_vessel_details = True,
        include_labels = True)

result = api.get_voyage_market_data(vessel_class_id=84, include_fixtures = True, include_vessel_details = True, include_labels = True)

In [6]:

## Get return data into a dataframe
voyages_market_data = pd.DataFrame([r.__dict__ for r in result])
voyages_market_data.head()

## Get return data into a dataframe voyages_market_data = pd.DataFrame([r.__dict__ for r in result]) voyages_market_data.head()

Out[6]:

	id	voyage_id	imo	voyage_number	vessel_name	vessel_type_id	vessel_type	vessel_class_id	vessel_class	trade_id	trade	commercial_operator_id	commercial_operator	deadweight	year_built	matched_fixture	fixtures
0	MI8A2F75VED1A16F00	I8A2F75VED1A16F00	9056117	50	Symeon II	1	Tanker	84	VLCC	1	Crude	1299.0	Polembros Shipping	277095	1994	None	(Fixture(fixture_id=3546721, is_matched=True, ...
1	MI8B5F18VED1A16F00	I8B5F18VED1A16F00	9133848	69	S Tajimare	1	Tanker	84	VLCC	1	Crude	435.0	Dynacom Tankers	265539	1996	None	(Fixture(fixture_id=6250780, is_matched=True, ...
2	MI8B98DBVED179E200	I8B98DBVED179E200	9148635	34	DS Velvet	1	Tanker	84	VLCC	1	Crude	510.0	Nayara	301438	1999	None	(Fixture(fixture_id=6285170, is_matched=True, ...
3	MI8B98DBVED1C8FC00	I8B98DBVED1C8FC00	9148635	35	DS Velvet	1	Tanker	84	VLCC	1	Crude	248.0	Carl F Peters	301438	1999	None	(Fixture(fixture_id=6353657, is_matched=None, ...
4	MI8BC5FEVED1944000	I8BC5FEVED1944000	9160190	41	Kym	1	Tanker	84	VLCC	1	Crude	1906.0	Embiricos Group	298324	1998	None	(Fixture(fixture_id=3533624, is_matched=True, ...

In [7]:

## Get fixtures seperately into a dataframe
fixtures = pd.DataFrame(f.__dict__ for fixtures in voyages_market_data['fixtures'].dropna() for f in fixtures)
fixtures.head()

## Get fixtures seperately into a dataframe fixtures = pd.DataFrame(f.__dict__ for fixtures in voyages_market_data['fixtures'].dropna() for f in fixtures) fixtures.head()

Out[7]:

	fixture_id	is_matched	is_load_matched	is_discharge_matched	fixture_status_id	fixture_status
0	3546721	True	True	True	NaN	None
1	4151663	True	True	True	NaN	None
2	6250780	True	True	True	0.0	OnSubs
3	6251766	True	True	True	0.0	OnSubs
4	6253238	True	True	True	0.0	OnSubs

In [8]:

# Expand the dataframe to have one row per fixture
voyages_market_data=voyages_market_data.explode('fixtures').reset_index(drop=True)
voyages_market_data.head()

# Expand the dataframe to have one row per fixture voyages_market_data=voyages_market_data.explode('fixtures').reset_index(drop=True) voyages_market_data.head()

Out[8]:

	id	voyage_id	imo	voyage_number	vessel_name	vessel_type_id	vessel_type	vessel_class_id	vessel_class	trade_id	trade	commercial_operator_id	commercial_operator	deadweight	year_built	matched_fixture	fixtures
0	MI8A2F75VED1A16F00	I8A2F75VED1A16F00	9056117	50	Symeon II	1	Tanker	84	VLCC	1	Crude	1299.0	Polembros Shipping	277095	1994	None	Fixture(fixture_id=3546721, is_matched=True, i...
1	MI8A2F75VED1A16F00	I8A2F75VED1A16F00	9056117	50	Symeon II	1	Tanker	84	VLCC	1	Crude	1299.0	Polembros Shipping	277095	1994	None	Fixture(fixture_id=4151663, is_matched=True, i...
2	MI8B5F18VED1A16F00	I8B5F18VED1A16F00	9133848	69	S Tajimare	1	Tanker	84	VLCC	1	Crude	435.0	Dynacom Tankers	265539	1996	None	Fixture(fixture_id=6250780, is_matched=True, i...
3	MI8B5F18VED1A16F00	I8B5F18VED1A16F00	9133848	69	S Tajimare	1	Tanker	84	VLCC	1	Crude	435.0	Dynacom Tankers	265539	1996	None	Fixture(fixture_id=6251766, is_matched=True, i...
4	MI8B5F18VED1A16F00	I8B5F18VED1A16F00	9133848	69	S Tajimare	1	Tanker	84	VLCC	1	Crude	435.0	Dynacom Tankers	265539	1996	None	Fixture(fixture_id=6253238, is_matched=True, i...

Get market data for a given Vessel

In [9]:

result = api.get_voyage_market_data(imo = 9890965, include_fixtures = True, include_matched_fixture = True, include_labels = True)

result = api.get_voyage_market_data(imo = 9890965, include_fixtures = True, include_matched_fixture = True, include_labels = True)

In [10]:

## Get return data into a dataframe
voyages_market_data = pd.DataFrame([r.__dict__ for r in result])

## Get return data into a dataframe voyages_market_data = pd.DataFrame([r.__dict__ for r in result])

Get market data using the advanced endpoint

In [11]:

# Get market data for vessels classes [84, 85], with laycan date from '2023-01-01'
result = api.get_voyage_market_data_advanced(vessel_class_ids = [84, 85], include_vessel_details = True,
        include_fixtures = True, include_lineups = True, include_positions = True, include_matched_fixture = True,
        include_labels = True, laycan_date_from = '2023-01-01')

# Get market data for vessels classes [84, 85], with laycan date from '2023-01-01' result = api.get_voyage_market_data_advanced(vessel_class_ids = [84, 85], include_vessel_details = True, include_fixtures = True, include_lineups = True, include_positions = True, include_matched_fixture = True, include_labels = True, laycan_date_from = '2023-01-01')

In [12]:

voyages_market_data = pd.DataFrame([r.__dict__ for r in result])
voyages_market_data.head()

voyages_market_data = pd.DataFrame([r.__dict__ for r in result]) voyages_market_data.head()

Out[12]:

	id	voyage_id	imo	voyage_number	vessel_name	vessel_type_id	vessel_type	vessel_class_id	vessel_class	trade_id	trade	commercial_operator_id	commercial_operator	deadweight	year_built	matched_fixture	fixtures
0	MI8C9C3CVEDB359500	I8C9C3CVEDB359500	9215036	142	Chafa	1	Tanker	85	Suezmax	1	Crude	2386	LMCS Maritime	150678	2001	MatchedFixture(fixture_status_id=1, fixture_st...	(Fixture(fixture_id=104321600, is_matched=True...
1	MI8C9C3CVEDB5D2200	I8C9C3CVEDB5D2200	9215036	143	Chafa	1	Tanker	85	Suezmax	1	Crude	2386	LMCS Maritime	150678	2001	MatchedFixture(fixture_status_id=1, fixture_st...	(Fixture(fixture_id=105207913, is_matched=True...
2	MI8D1456VEDB359500	I8D1456VEDB359500	9245782	78	Cosglory Lake	1	Tanker	84	VLCC	1	Crude	356	COSCO	299145	2003	MatchedFixture(fixture_status_id=1, fixture_st...	(Fixture(fixture_id=105504298, is_matched=True...
3	MI8D1E99VEDB359500	I8D1E99VEDB359500	9248409	83	Seoul Spirit	1	Tanker	85	Suezmax	1	Crude	1663	Teekay Corp	159966	2005	MatchedFixture(fixture_status_id=1, fixture_st...	(Fixture(fixture_id=105311802, is_matched=True...
4	MI8D40BDVEDB0E0800	I8D40BDVEDB0E0800	9257149	75	Elizabeth I.A.	1	Tanker	84	VLCC	1	Crude	917	Maran Tankers Management	306229	2004	MatchedFixture(fixture_status_id=1, fixture_st...	(Fixture(fixture_id=104633101, is_matched=True...

In [13]:

matched_fixtures = pd.DataFrame([r.matched_fixture.__dict__ for r in result])
matched_fixtures.head()

matched_fixtures = pd.DataFrame([r.matched_fixture.__dict__ for r in result]) matched_fixtures.head()

Out[13]:

	fixture_status_id	fixture_status	charter_type_id	charter_type	fixture_date	charterer_id	charterer	laycan_from	laycan_to	load_geo_id	...	redelivery_to_taxonomy_id	redelivery_to_taxonomy	user_entries	full_fixtures	partial_fixtures	is_coa	is_owners_option	is_hold	is_fio	sources
0	1	FullyFixed	0	Voyage	2022-12-19 17:00:42+00:00	180.0	Bharat Oman Refineries	2023-01-05 00:00:00+00:00	2023-01-05 00:00:00+00:00	3778	...	None	None	0	8	0	None	None	None	None	(galbraiths.co.uk, ssysin.com.sg, ssy.co.uk, s...
1	1	FullyFixed	0	Voyage	2023-01-06 14:40:33+00:00	718.0	Indian Oil	2023-01-26 00:00:00+00:00	2023-01-26 00:00:00+00:00	3778	...	None	None	0	10	0	None	None	None	None	(southportmaritime.com, ssy.co.uk, galbraiths....
2	1	FullyFixed	0	Voyage	2023-01-10 16:57:45+00:00	NaN	None	2023-01-23 00:00:00+00:00	2023-01-23 00:00:00+00:00	24777	...	None	None	0	2	0	None	None	None	None	(galbraiths.co.uk, Signal Ocean)
3	1	FullyFixed	0	Voyage	2023-01-09 09:59:01+00:00	1237.0	Petraco	2023-01-25 00:00:00+00:00	2023-01-25 00:00:00+00:00	9763	...	None	None	0	4	8	None	None	None	None	(southportmaritime.com, ssy.co.uk, Signal Ocea...
4	1	FullyFixed	0	Voyage	2022-12-22 18:03:02+00:00	1928.0	Unipec	2023-01-04 00:00:00+00:00	2023-01-04 00:00:00+00:00	24777	...	None	None	0	2	0	None	None	None	None	(Signal Ocean, southportmaritime.com)

5 rows × 57 columns