Skip to content

Market Rates

Market Rates API Package.

Classes:

Name Description
MarketRatesAPI

Represents Signal's Market Rates API.
MarketRate

The market rate of a certain route or vessel class.
Route

A route with available market rate.
VesselClass

A vessel class.
CargoId

The cargo ID, Dirty (0), Clean(1) or IMO (2).

CargoId

Bases: Enum

An enumeration of all possible cargo ids.

Source code in signal_ocean/market_rates/enums.py 
 6
 7
 8
 9
10
11
@unique
class CargoId(Enum):
    """An enumeration of all possible cargo ids."""
    DIRTY = 0
    CLEAN = 1
    IMO = 2

MarketRate dataclass

The market rate of a certain route or vessel class.

Attributes:

Name Type Description
route_id str

ID of the route.
rate_date datetime

Date of the rate.
rate_value float

Value of the rate.
unit str

Unit of the rate.
vessel_class_id int

ID of the vessel class.
deprecated_to Optional[str]

Route ID if route is deprecated.
Source code in signal_ocean/market_rates/models.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
@dataclass(frozen=True)
class MarketRate:
    """The market rate of a certain route or vessel class.

    Attributes:
        route_id: ID of the route.
        rate_date: Date of the rate.
        rate_value: Value of the rate.
        unit: Unit of the rate.
        vessel_class_id: ID of the vessel class.
        deprecated_to: Route ID if route is deprecated.
    """

    route_id: str
    rate_date: datetime
    rate_value: float
    unit: str
    vessel_class_id: int
    deprecated_to: Optional[str] = None

MarketRatesAPI

Represents Signal's Market Rates API.

Source code in signal_ocean/market_rates/market_rates_api.py 
 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
class MarketRatesAPI:
    """Represents Signal's Market Rates API."""

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

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

    def get_market_rates(
        self, start_date: date, route_id: Optional[str] = None,
            vessel_class_id: Optional[int] = None,
            end_date: Optional[date] = None,
            cargo_id: Optional[CargoId] = None
    ) -> Tuple[MarketRate, ...]:
        """Provides market rates for given day/period and route/vessel class.

        Args:
            start_date: Start date of market rates. If end date is not
            specified, it returns market rate for the given day only.
            route_id: Route ID.
            vessel_class_id: Vessel class ID.
            end_date: Combined with start_date will produce result market rates
            for all consecutive days from start to end date.
            cargo_id: Dirty (0), Clean(1) or IMO (2).

        Returns:
            The market rates or None if there are no market rates matching the
            given criteria.
        """
        query_dict = {
            "start_date": start_date.isoformat(),
            "requested-by": "SignalSDK"
        }

        if route_id is not None:
            query_dict["route_id"] = '{}'.format(route_id)
        if vessel_class_id is not None:
            query_dict["vessel_class_id"] = '{}'.format(vessel_class_id)
        if end_date is not None:
            query_dict["end_date"] = end_date.isoformat()
        if cargo_id is not None:
            query_dict["cargo_id"] = cargo_id.value

        query_string: QueryString = query_dict
        response = self.__connection._make_get_request(
            "market-rates/api/v2/market_rates", query_string
        )
        response.raise_for_status()
        response_json = response.json()
        return_object = parse_market_rates(response_json)

        return return_object

    def get_routes(
        self, vessel_class_id: Optional[int] = None
    ) -> Tuple[Route, ...]:
        """Fetches all routes or the ones matching the vessel class ID.

        Args:
            vessel_class_id: Vessel class ID.

        Returns:
            The result routes.
        """
        if vessel_class_id is not None:
            uri = f"market-rates/api/v2/routes/{vessel_class_id}"
        else:
            uri = "market-rates/api/v2/routes"

        response = self.__connection._make_get_request(uri)
        response.raise_for_status()
        response_json = response.json()
        return_object = parse_routes(response_json)

        return return_object

    @staticmethod
    def get_vessel_classes() -> Tuple[VesselClass, ...]:
        """Retrieves all available vessel classes.

        Returns:
            A tuple of all available vessel classes.
        """
        vessel_types = tuple(VesselClass(
            cast(int, vessel_class["id"]),
            cast(int, vessel_class["vessel_type_id"]),
            cast(int, vessel_class["from_size"]),
            cast(int, vessel_class["to_size"]),
            cast(str, vessel_class["name"]),
            cast(str, vessel_class["vessel_type"]),
            cast(str, vessel_class["defining_size"]),
            cast(str, vessel_class["size"]))
                             for vessel_class in VESSEL_CLASSES)
        return vessel_types

__init__(connection=None)

Initializes the Market Rates 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/market_rates/market_rates_api.py 
17
18
19
20
21
22
23
24
def __init__(self, connection: Optional[Connection] = None):
    """Initializes the Market Rates API.

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

get_market_rates(start_date, route_id=None, vessel_class_id=None, end_date=None, cargo_id=None)

Provides market rates for given day/period and route/vessel class.

Parameters:

Name Type Description Default
start_date date

Start date of market rates. If end date is not

 required
route_id Optional[str]

Route ID.

 None
vessel_class_id Optional[int]

Vessel class ID.

 None
end_date Optional[date]

Combined with start_date will produce result market rates

 None
cargo_id Optional[CargoId]

Dirty (0), Clean(1) or IMO (2).

 None

Returns:

Type Description
MarketRate

The market rates or None if there are no market rates matching the
...

given criteria.
Source code in signal_ocean/market_rates/market_rates_api.py 
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
def get_market_rates(
    self, start_date: date, route_id: Optional[str] = None,
        vessel_class_id: Optional[int] = None,
        end_date: Optional[date] = None,
        cargo_id: Optional[CargoId] = None
) -> Tuple[MarketRate, ...]:
    """Provides market rates for given day/period and route/vessel class.

    Args:
        start_date: Start date of market rates. If end date is not
        specified, it returns market rate for the given day only.
        route_id: Route ID.
        vessel_class_id: Vessel class ID.
        end_date: Combined with start_date will produce result market rates
        for all consecutive days from start to end date.
        cargo_id: Dirty (0), Clean(1) or IMO (2).

    Returns:
        The market rates or None if there are no market rates matching the
        given criteria.
    """
    query_dict = {
        "start_date": start_date.isoformat(),
        "requested-by": "SignalSDK"
    }

    if route_id is not None:
        query_dict["route_id"] = '{}'.format(route_id)
    if vessel_class_id is not None:
        query_dict["vessel_class_id"] = '{}'.format(vessel_class_id)
    if end_date is not None:
        query_dict["end_date"] = end_date.isoformat()
    if cargo_id is not None:
        query_dict["cargo_id"] = cargo_id.value

    query_string: QueryString = query_dict
    response = self.__connection._make_get_request(
        "market-rates/api/v2/market_rates", query_string
    )
    response.raise_for_status()
    response_json = response.json()
    return_object = parse_market_rates(response_json)

    return return_object

get_routes(vessel_class_id=None)

Fetches all routes or the ones matching the vessel class ID.

Parameters:

Name Type Description Default
vessel_class_id Optional[int]

Vessel class ID.

 None

Returns:

Type Description
Tuple[Route, ...]

The result routes.
Source code in signal_ocean/market_rates/market_rates_api.py 
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
def get_routes(
    self, vessel_class_id: Optional[int] = None
) -> Tuple[Route, ...]:
    """Fetches all routes or the ones matching the vessel class ID.

    Args:
        vessel_class_id: Vessel class ID.

    Returns:
        The result routes.
    """
    if vessel_class_id is not None:
        uri = f"market-rates/api/v2/routes/{vessel_class_id}"
    else:
        uri = "market-rates/api/v2/routes"

    response = self.__connection._make_get_request(uri)
    response.raise_for_status()
    response_json = response.json()
    return_object = parse_routes(response_json)

    return return_object

get_vessel_classes() staticmethod

Retrieves all available vessel classes.

Returns:

Type Description
Tuple[VesselClass, ...]

A tuple of all available vessel classes.
Source code in signal_ocean/market_rates/market_rates_api.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
@staticmethod
def get_vessel_classes() -> Tuple[VesselClass, ...]:
    """Retrieves all available vessel classes.

    Returns:
        A tuple of all available vessel classes.
    """
    vessel_types = tuple(VesselClass(
        cast(int, vessel_class["id"]),
        cast(int, vessel_class["vessel_type_id"]),
        cast(int, vessel_class["from_size"]),
        cast(int, vessel_class["to_size"]),
        cast(str, vessel_class["name"]),
        cast(str, vessel_class["vessel_type"]),
        cast(str, vessel_class["defining_size"]),
        cast(str, vessel_class["size"]))
                         for vessel_class in VESSEL_CLASSES)
    return vessel_types

Route dataclass

A route with available market rate.

Attributes:

Name Type Description
id str

ID of the route.
description str

Description of the route.
unit str

Unit in which rate is provided.
vessel_class_id int

ID of the vessel class.
cargo_id int

Cargo ID.
load_port_id int

Load port ID.
discharge_port_id int

Discharge port ID.
load_area_id int

Load area ID.
discharge_area_id int

Discharge area ID.
load_port_2_id Optional[int]

Second load port ID.
discharge_port_2_id Optional[int]

Second discharge port ID.
load_area_2_id Optional[int]

Second load area ID.
discharge_area_2_id Optional[int]

Second discharge area ID.
deprecated_to Optional[str]

Route ID if route is deprecated.
deprecated_since Optional[datetime]

Deprecation effective date.
Source code in signal_ocean/market_rates/models.py 
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
@dataclass(frozen=True)
class Route:
    """A route with available market rate.

    Attributes:
        id: ID of the route.
        description: Description of the route.
        unit: Unit in which rate is provided.
        vessel_class_id: ID of the vessel class.
        cargo_id: Cargo ID.
        load_port_id: Load port ID.
        discharge_port_id: Discharge port ID.
        load_area_id: Load area ID.
        discharge_area_id: Discharge area ID.
        load_port_2_id: Second load port ID.
        discharge_port_2_id: Second discharge port ID.
        load_area_2_id: Second load area ID.
        discharge_area_2_id: Second discharge area ID.
        deprecated_to: Route ID if route is deprecated.
        deprecated_since: Deprecation effective date.
    """

    id: str
    description: str
    unit: str
    vessel_class_id: int
    cargo_id: int
    load_port_id: int
    discharge_port_id: int
    load_area_id: int
    discharge_area_id: int
    load_port_2_id: Optional[int] = None
    discharge_port_2_id: Optional[int] = None
    load_area_2_id: Optional[int] = None
    discharge_area_2_id: Optional[int] = None
    deprecated_to: Optional[str] = None
    deprecated_since: Optional[datetime] = None

VesselClass dataclass

A vessel class.

Attributes:

Name Type Description
id int

The vessel class id, e.g. 60 -> VLGC, 61 -> Midsize/LGC etc.
vessel_type_id int

The vessel type id, e.g. 6
from_size int

Minimum size
to_size int

Maximum size
name str

The vessel class name
vessel_type str

The vessel type name, e.g. LPG
defining_size str

Size type, e.g. CubicSize
size str

The vessel size, e.g. cbm
Source code in signal_ocean/market_rates/models.py 
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
@dataclass(frozen=True)
class VesselClass:
    """A vessel class.

    Attributes:
        id: The vessel class id, e.g. 60 -> VLGC, 61 -> Midsize/LGC etc.
        vessel_type_id: The vessel type id, e.g. 6
        from_size: Minimum size
        to_size: Maximum size
        name: The vessel class name
        vessel_type: The vessel type name, e.g. LPG
        defining_size: Size type, e.g. CubicSize
        size: The vessel size, e.g. cbm
    """

    id: int
    vessel_type_id: int
    from_size: int
    to_size: int
    name: str
    vessel_type: str
    defining_size: str
    size: str