Package Documentation

Distances API Package.

Classes:

Name	Description
DistancesAPI	Represents Signal's Distances API.
VesselClass	A group of vessels of similar characteristics.
VesselClassFilter	A filter used to find specific vessel classes.
Port	A maritime facility where vessels can dock.
PortFilter	A filter used to find specific ports.
LoadingCondition	The states of a vessel carrying cargo.
RouteResponse	A route between two points
AlternativePath	An alternative path for the route
PointsOnRoute	A point and extra properties needed for a route
Point	A point in latitude and longitude.

AlternativePath

Bases: SignalBaseModel

An alternative path for the route.

Attributes:

Name	Type	Description
calculated_route	Optional[Tuple[Point, ...]]	List of coordinates between start and end point.
distance	Optional[Decimal]	The distance between the two points.
routing_points_on_route	Optional[Tuple[PointsOnRoute, ...]]
piracy_distance	Optional[Decimal]	The distance between the two points when piracy is considered.
seca_distance	Optional[Decimal]	The distance between the two points when SECA is considered.

Source code in signal_ocean/distances/models.py

class AlternativePath(SignalBaseModel):
    """An alternative path for the route.

    Attributes:
        calculated_route: List of coordinates between start and end point.
        distance: The distance between the two points.
        routing_points_on_route:
        piracy_distance: The distance between the two points when piracy
            is considered.
        seca_distance: The distance between the two points when SECA is
            considered.
    """

    calculated_route: Optional[Tuple[Point, ...]] = None
    distance: Optional[Decimal] = None
    routing_points_on_route: Optional[Tuple[PointsOnRoute, ...]] = None
    piracy_distance: Optional[Decimal] = None
    seca_distance: Optional[Decimal] = None

DistancesAPI

Represents Signal's Distances API.

Source code in signal_ocean/distances/distances_api.py

class DistancesAPI:
    """Represents Signal's Distances API."""

    def __init__(self, connection: Optional[Connection] = None):
        """Initializes DistancesAPI.

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

    def get_vessel_classes(
        self, class_filter: Optional[VesselClassFilter] = None
    ) -> Tuple[VesselClass, ...]:
        """Retrieves available vessel classes.

        Args:
            class_filter: A filter used to find specific vessel classes. If not
                specified, returns all available vessel classes.

        Returns:
            A tuple of available vessel classes that match the filter.
        """
        response = self.__connection._make_get_request(
            "/distances-api/api/v1/VesselClasses"
        )
        response.raise_for_status()

        classes = (VesselClass(**c) for c in response.json())
        class_filter = class_filter or VesselClassFilter()

        return tuple(class_filter._apply(classes))

    def get_ports(
        self, port_filter: Optional[PortFilter] = None
    ) -> Tuple[Port, ...]:
        """Retrieves available ports.

        Args:
            port_filter: A filter used to find specific ports. If not
                specified, returns all available ports.

        Returns:
            A tuple of available ports that match the filter.
        """
        response = self.__connection._make_get_request(
            "/distances-api/api/v1/ports"
        )
        response.raise_for_status()

        ports = (Port(**p) for p in response.json())
        port_filter = port_filter or PortFilter()

        return tuple(port_filter._apply(ports))

    def get_point_to_point_distance(
        self,
        vessel_class: VesselClass,
        loading_condition_id: int,
        start_point: Point,
        end_point: Point,
    ) -> Optional[Decimal]:
        """Retrieves the distance from one point to another.

        Args:
            vessel_class: Vessel class for which the distance will be
                calculated.
            loading_condition_id: Loading condition of the vessels
                for which the distance will be calculated.
                Options available: Laden and Ballast.
            start_point: The starting point latitude and longitude.
            end_point: The ending point latitude and longitude.

        Returns:
            A Decimal representing the distance in NM between two points.
        """
        response = self.__connection._make_get_request(
            "/distances-api/api/v1/Distance/PointToPoint",
            {
                "vesselclass": vessel_class.id,
                "loadingcondition": loading_condition_id,
                "latitudefrom": str(start_point.lat),
                "latitudeto": str(end_point.lat),
                "longitudefrom": str(start_point.lon),
                "longitudeto": str(end_point.lon),
            },
        )

        response.raise_for_status()

        return as_decimal(response.json())

    def get_point_to_port_distance(
        self,
        vessel_class: VesselClass,
        loading_condition_id: int,
        point: Point,
        port: Port,
    ) -> Optional[Decimal]:
        """Retrieves the distance from one point to another.

        Args:
            vessel_class: Vessel class for which the distance will be
                calculated.
            loading_condition_id: Loading condition of the vessels
                for which the distance will be calculated.
                Options available: Laden and Ballast.
            point: The starting point latitude and longitude.
            port: The target port.

        Returns:
            A Decimal representing the distance in NM between a point
                and a port.
        """
        response = self.__connection._make_get_request(
            "/distances-api/api/v1/Distance/PointToPort",
            {
                "vesselclass": vessel_class.id,
                "loadingcondition": loading_condition_id,
                "latitude": str(point.lat),
                "longitude": str(point.lon),
                "portid": port.id,
            },
        )

        response.raise_for_status()

        return as_decimal(response.json())

    def get_port_to_port_distance(
        self,
        vessel_class: VesselClass,
        loading_condition_id: int,
        port_from: Port,
        port_to: Port,
    ) -> Optional[Decimal]:
        """Retrieves the distance from one point to another.

        Args:
            vessel_class: Vessel class for which the distance will be
                calculated.
            loading_condition_id: Loading condition of the vessels
                for which the distance will be calculated.
                Options available: Laden and Ballast.
            port_from: The starting port for the distance
                route calculation.
            port_to: The ending port for the distance
                route calculation.

        Returns:
            A Decimal representing the distance in NM between two ports.
        """
        response = self.__connection._make_get_request(
            "/distances-api/api/v1/Distance/PortToPort",
            {
                "vesselclass": vessel_class.id,
                "loadingcondition": loading_condition_id,
                "portIdFrom": port_from.id,
                "portIdTo": port_to.id,
            },
        )

        response.raise_for_status()

        return as_decimal(response.json())

    def get_point_to_point_route(
        self,
        vessel_class: VesselClass,
        loading_condition_id: int,
        start_point: Point,
        end_point: Point,
    ) -> RouteResponse:
        """Retrieves the route from one point to another.

        Args:
            vessel_class: Vessel class for which the distance will be
                calculated.
            loading_condition_id: Loading condition of the vessels
                for which the distance will be calculated.
                Options available: Laden and Ballast.
            start_point: The starting point latitude and longitude.
            end_point: The ending point latitude and longitude.

        Returns:
            A Route between two points with distance in NM.
        """
        response = self.__connection._make_get_request(
            "/distances-api/api/v1/Distance/PointToPoint/Route",
            {
                "vesselclass": vessel_class.id,
                "loadingcondition": loading_condition_id,
                "latitudefrom": str(start_point.lat),
                "latitudeto": str(end_point.lat),
                "longitudefrom": str(start_point.lon),
                "longitudeto": str(end_point.lon),
            },
        )

        response.raise_for_status()

        return _distances_json.parse_route_response(response.json())

    def get_point_to_port_route(
        self,
        vessel_class: VesselClass,
        loading_condition_id: int,
        point: Point,
        port: Port,
    ) -> RouteResponse:
        """Retrieves the route from one point to another.

        Args:
            vessel_class: Vessel class for which the distance will be
                calculated.
            loading_condition_id: Loading condition of the vessels
                for which the distance will be calculated.
                Options available: Laden and Ballast.
            point: The starting point latitude and longitude.
            port: The ending port for the distance
                route calculation.

        Returns:
            A Route between a point and a port with distance in NM.
        """
        response = self.__connection._make_get_request(
            "/distances-api/api/v1/Distance/PointToPort/Route",
            {
                "vesselclass": vessel_class.id,
                "loadingcondition": loading_condition_id,
                "latitude": str(point.lat),
                "longitude": str(point.lon),
                "portid": port.id,
            },
        )

        response.raise_for_status()

        return _distances_json.parse_route_response(response.json())

    def get_port_to_port_route(
        self,
        vessel_class: VesselClass,
        loading_condition_id: int,
        port_from: Port,
        port_to: Port,
    ) -> RouteResponse:
        """Retrieves the route from one point to another.

        Args:
            vessel_class: Vessel class for which the distance will be
                calculated.
            loading_condition_id: Loading condition of the vessels
                for which the distance will be calculated.
                Options available: Laden and Ballast.
            port_from: The starting port for the distance
                route calculation.
            port_to: The ending port for the distance
                route calculation.

        Returns:
            A Route between two ports with distance in NM.
        """
        response = self.__connection._make_get_request(
            "/distances-api/api/v1/Distance/PortToPort/Route",
            {
                "vesselclass": vessel_class.id,
                "loadingcondition": loading_condition_id,
                "portIdFrom": port_from.id,
                "portIdTo": port_to.id,
            },
        )

        response.raise_for_status()

        return _distances_json.parse_route_response(response.json())

    def get_generic_point_to_point_route(
        self,
        start_point: Point,
        end_point: Point,
        route_restrictions: Optional[RouteRestrictions] = None,
        delays_valid_at: Optional[date] = None,
        get_alternatives: Optional[bool] = None,
    ) -> RouteResponse:
        """Retrieves a generic route between two points.

        The method takes into consideration the provided restrictions and can
        also return alternative routes.

        Args:
            start_point: The starting point latitude and longitude.
            end_point: The ending point latitude and longitude.
            route_restrictions: Restrictions to obey while calculating the
                route.
            delays_valid_at: Date at which the route delays are valid.
            get_alternatives: Whether or not to include alternative routes.

        Returns:
            A Route between two points with distance in NM.
        """
        route_restrictions = route_restrictions or RouteRestrictions()
        response = self.__connection._make_get_request(
            "/distances-api/api/v1/Distance/Generic",
            {
                "StartPointLatitude": str(start_point.lat),
                "StartPointLongitude": str(start_point.lon),
                "EndPointLatitude": str(end_point.lat),
                "EndPointLongitude": str(end_point.lon),
                "DelaysValidAt": format_iso_date(delays_valid_at)
                if delays_valid_at
                else None,
                "GetAlternatives": get_alternatives,
                **route_restrictions._to_query_string(),
            },
        )

        response.raise_for_status()
        return _distances_json.parse_route_response(response.json())

__init__(connection=None)

Initializes DistancesAPI.

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/distances/distances_api.py

def __init__(self, connection: Optional[Connection] = None):
    """Initializes DistancesAPI.

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

get_generic_point_to_point_route(start_point, end_point, route_restrictions=None, delays_valid_at=None, get_alternatives=None)

Retrieves a generic route between two points.

The method takes into consideration the provided restrictions and can also return alternative routes.

Parameters:

Name	Type	Description	Default
start_point	Point	The starting point latitude and longitude.	required
end_point	Point	The ending point latitude and longitude.	required
route_restrictions	Optional[RouteRestrictions]	Restrictions to obey while calculating the route.	None
delays_valid_at	Optional[date]	Date at which the route delays are valid.	None
get_alternatives	Optional[bool]	Whether or not to include alternative routes.	None

Returns:

Type	Description
RouteResponse	A Route between two points with distance in NM.

Source code in signal_ocean/distances/distances_api.py

def get_generic_point_to_point_route(
    self,
    start_point: Point,
    end_point: Point,
    route_restrictions: Optional[RouteRestrictions] = None,
    delays_valid_at: Optional[date] = None,
    get_alternatives: Optional[bool] = None,
) -> RouteResponse:
    """Retrieves a generic route between two points.

    The method takes into consideration the provided restrictions and can
    also return alternative routes.

    Args:
        start_point: The starting point latitude and longitude.
        end_point: The ending point latitude and longitude.
        route_restrictions: Restrictions to obey while calculating the
            route.
        delays_valid_at: Date at which the route delays are valid.
        get_alternatives: Whether or not to include alternative routes.

    Returns:
        A Route between two points with distance in NM.
    """
    route_restrictions = route_restrictions or RouteRestrictions()
    response = self.__connection._make_get_request(
        "/distances-api/api/v1/Distance/Generic",
        {
            "StartPointLatitude": str(start_point.lat),
            "StartPointLongitude": str(start_point.lon),
            "EndPointLatitude": str(end_point.lat),
            "EndPointLongitude": str(end_point.lon),
            "DelaysValidAt": format_iso_date(delays_valid_at)
            if delays_valid_at
            else None,
            "GetAlternatives": get_alternatives,
            **route_restrictions._to_query_string(),
        },
    )

    response.raise_for_status()
    return _distances_json.parse_route_response(response.json())

get_point_to_point_distance(vessel_class, loading_condition_id, start_point, end_point)

Retrieves the distance from one point to another.

Parameters:

Name	Type	Description	Default
vessel_class	VesselClass	Vessel class for which the distance will be calculated.	required
loading_condition_id	int	Loading condition of the vessels for which the distance will be calculated. Options available: Laden and Ballast.	required
start_point	Point	The starting point latitude and longitude.	required
end_point	Point	The ending point latitude and longitude.	required

Returns:

Type	Description
Optional[Decimal]	A Decimal representing the distance in NM between two points.

Source code in signal_ocean/distances/distances_api.py

def get_point_to_point_distance(
    self,
    vessel_class: VesselClass,
    loading_condition_id: int,
    start_point: Point,
    end_point: Point,
) -> Optional[Decimal]:
    """Retrieves the distance from one point to another.

    Args:
        vessel_class: Vessel class for which the distance will be
            calculated.
        loading_condition_id: Loading condition of the vessels
            for which the distance will be calculated.
            Options available: Laden and Ballast.
        start_point: The starting point latitude and longitude.
        end_point: The ending point latitude and longitude.

    Returns:
        A Decimal representing the distance in NM between two points.
    """
    response = self.__connection._make_get_request(
        "/distances-api/api/v1/Distance/PointToPoint",
        {
            "vesselclass": vessel_class.id,
            "loadingcondition": loading_condition_id,
            "latitudefrom": str(start_point.lat),
            "latitudeto": str(end_point.lat),
            "longitudefrom": str(start_point.lon),
            "longitudeto": str(end_point.lon),
        },
    )

    response.raise_for_status()

    return as_decimal(response.json())

get_point_to_point_route(vessel_class, loading_condition_id, start_point, end_point)

Retrieves the route from one point to another.

Parameters:

Name	Type	Description	Default
vessel_class	VesselClass	Vessel class for which the distance will be calculated.	required
loading_condition_id	int	Loading condition of the vessels for which the distance will be calculated. Options available: Laden and Ballast.	required
start_point	Point	The starting point latitude and longitude.	required
end_point	Point	The ending point latitude and longitude.	required

Returns:

Type	Description
RouteResponse	A Route between two points with distance in NM.

Source code in signal_ocean/distances/distances_api.py

def get_point_to_point_route(
    self,
    vessel_class: VesselClass,
    loading_condition_id: int,
    start_point: Point,
    end_point: Point,
) -> RouteResponse:
    """Retrieves the route from one point to another.

    Args:
        vessel_class: Vessel class for which the distance will be
            calculated.
        loading_condition_id: Loading condition of the vessels
            for which the distance will be calculated.
            Options available: Laden and Ballast.
        start_point: The starting point latitude and longitude.
        end_point: The ending point latitude and longitude.

    Returns:
        A Route between two points with distance in NM.
    """
    response = self.__connection._make_get_request(
        "/distances-api/api/v1/Distance/PointToPoint/Route",
        {
            "vesselclass": vessel_class.id,
            "loadingcondition": loading_condition_id,
            "latitudefrom": str(start_point.lat),
            "latitudeto": str(end_point.lat),
            "longitudefrom": str(start_point.lon),
            "longitudeto": str(end_point.lon),
        },
    )

    response.raise_for_status()

    return _distances_json.parse_route_response(response.json())

get_point_to_port_distance(vessel_class, loading_condition_id, point, port)

Retrieves the distance from one point to another.

Parameters:

Name	Type	Description	Default
vessel_class	VesselClass	Vessel class for which the distance will be calculated.	required
loading_condition_id	int	Loading condition of the vessels for which the distance will be calculated. Options available: Laden and Ballast.	required
point	Point	The starting point latitude and longitude.	required
port	Port	The target port.	required

Returns:

Type	Description
Optional[Decimal]	A Decimal representing the distance in NM between a point and a port.

Source code in signal_ocean/distances/distances_api.py

def get_point_to_port_distance(
    self,
    vessel_class: VesselClass,
    loading_condition_id: int,
    point: Point,
    port: Port,
) -> Optional[Decimal]:
    """Retrieves the distance from one point to another.

    Args:
        vessel_class: Vessel class for which the distance will be
            calculated.
        loading_condition_id: Loading condition of the vessels
            for which the distance will be calculated.
            Options available: Laden and Ballast.
        point: The starting point latitude and longitude.
        port: The target port.

    Returns:
        A Decimal representing the distance in NM between a point
            and a port.
    """
    response = self.__connection._make_get_request(
        "/distances-api/api/v1/Distance/PointToPort",
        {
            "vesselclass": vessel_class.id,
            "loadingcondition": loading_condition_id,
            "latitude": str(point.lat),
            "longitude": str(point.lon),
            "portid": port.id,
        },
    )

    response.raise_for_status()

    return as_decimal(response.json())

get_point_to_port_route(vessel_class, loading_condition_id, point, port)

Retrieves the route from one point to another.

Parameters:

Name	Type	Description	Default
vessel_class	VesselClass	Vessel class for which the distance will be calculated.	required
loading_condition_id	int	Loading condition of the vessels for which the distance will be calculated. Options available: Laden and Ballast.	required
point	Point	The starting point latitude and longitude.	required
port	Port	The ending port for the distance route calculation.	required

Returns:

Type	Description
RouteResponse	A Route between a point and a port with distance in NM.

Source code in signal_ocean/distances/distances_api.py

def get_point_to_port_route(
    self,
    vessel_class: VesselClass,
    loading_condition_id: int,
    point: Point,
    port: Port,
) -> RouteResponse:
    """Retrieves the route from one point to another.

    Args:
        vessel_class: Vessel class for which the distance will be
            calculated.
        loading_condition_id: Loading condition of the vessels
            for which the distance will be calculated.
            Options available: Laden and Ballast.
        point: The starting point latitude and longitude.
        port: The ending port for the distance
            route calculation.

    Returns:
        A Route between a point and a port with distance in NM.
    """
    response = self.__connection._make_get_request(
        "/distances-api/api/v1/Distance/PointToPort/Route",
        {
            "vesselclass": vessel_class.id,
            "loadingcondition": loading_condition_id,
            "latitude": str(point.lat),
            "longitude": str(point.lon),
            "portid": port.id,
        },
    )

    response.raise_for_status()

    return _distances_json.parse_route_response(response.json())

get_port_to_port_distance(vessel_class, loading_condition_id, port_from, port_to)

Retrieves the distance from one point to another.

Parameters:

Name	Type	Description	Default
vessel_class	VesselClass	Vessel class for which the distance will be calculated.	required
loading_condition_id	int	Loading condition of the vessels for which the distance will be calculated. Options available: Laden and Ballast.	required
port_from	Port	The starting port for the distance route calculation.	required
port_to	Port	The ending port for the distance route calculation.	required

Returns:

Type	Description
Optional[Decimal]	A Decimal representing the distance in NM between two ports.

Source code in signal_ocean/distances/distances_api.py

def get_port_to_port_distance(
    self,
    vessel_class: VesselClass,
    loading_condition_id: int,
    port_from: Port,
    port_to: Port,
) -> Optional[Decimal]:
    """Retrieves the distance from one point to another.

    Args:
        vessel_class: Vessel class for which the distance will be
            calculated.
        loading_condition_id: Loading condition of the vessels
            for which the distance will be calculated.
            Options available: Laden and Ballast.
        port_from: The starting port for the distance
            route calculation.
        port_to: The ending port for the distance
            route calculation.

    Returns:
        A Decimal representing the distance in NM between two ports.
    """
    response = self.__connection._make_get_request(
        "/distances-api/api/v1/Distance/PortToPort",
        {
            "vesselclass": vessel_class.id,
            "loadingcondition": loading_condition_id,
            "portIdFrom": port_from.id,
            "portIdTo": port_to.id,
        },
    )

    response.raise_for_status()

    return as_decimal(response.json())

get_port_to_port_route(vessel_class, loading_condition_id, port_from, port_to)

Retrieves the route from one point to another.

Parameters:

Name	Type	Description	Default
vessel_class	VesselClass	Vessel class for which the distance will be calculated.	required
loading_condition_id	int	Loading condition of the vessels for which the distance will be calculated. Options available: Laden and Ballast.	required
port_from	Port	The starting port for the distance route calculation.	required
port_to	Port	The ending port for the distance route calculation.	required

Returns:

Type	Description
RouteResponse	A Route between two ports with distance in NM.

Source code in signal_ocean/distances/distances_api.py

def get_port_to_port_route(
    self,
    vessel_class: VesselClass,
    loading_condition_id: int,
    port_from: Port,
    port_to: Port,
) -> RouteResponse:
    """Retrieves the route from one point to another.

    Args:
        vessel_class: Vessel class for which the distance will be
            calculated.
        loading_condition_id: Loading condition of the vessels
            for which the distance will be calculated.
            Options available: Laden and Ballast.
        port_from: The starting port for the distance
            route calculation.
        port_to: The ending port for the distance
            route calculation.

    Returns:
        A Route between two ports with distance in NM.
    """
    response = self.__connection._make_get_request(
        "/distances-api/api/v1/Distance/PortToPort/Route",
        {
            "vesselclass": vessel_class.id,
            "loadingcondition": loading_condition_id,
            "portIdFrom": port_from.id,
            "portIdTo": port_to.id,
        },
    )

    response.raise_for_status()

    return _distances_json.parse_route_response(response.json())

get_ports(port_filter=None)

Retrieves available ports.

Parameters:

Name	Type	Description	Default
port_filter	Optional[PortFilter]	A filter used to find specific ports. If not specified, returns all available ports.	None

Returns:

Type	Description
Tuple[Port, ...]	A tuple of available ports that match the filter.

Source code in signal_ocean/distances/distances_api.py

def get_ports(
    self, port_filter: Optional[PortFilter] = None
) -> Tuple[Port, ...]:
    """Retrieves available ports.

    Args:
        port_filter: A filter used to find specific ports. If not
            specified, returns all available ports.

    Returns:
        A tuple of available ports that match the filter.
    """
    response = self.__connection._make_get_request(
        "/distances-api/api/v1/ports"
    )
    response.raise_for_status()

    ports = (Port(**p) for p in response.json())
    port_filter = port_filter or PortFilter()

    return tuple(port_filter._apply(ports))

get_vessel_classes(class_filter=None)

Retrieves available vessel classes.

Parameters:

Name	Type	Description	Default
class_filter	Optional[VesselClassFilter]	A filter used to find specific vessel classes. If not specified, returns all available vessel classes.	None

Returns:

Type	Description
Tuple[VesselClass, ...]	A tuple of available vessel classes that match the filter.

Source code in signal_ocean/distances/distances_api.py

def get_vessel_classes(
    self, class_filter: Optional[VesselClassFilter] = None
) -> Tuple[VesselClass, ...]:
    """Retrieves available vessel classes.

    Args:
        class_filter: A filter used to find specific vessel classes. If not
            specified, returns all available vessel classes.

    Returns:
        A tuple of available vessel classes that match the filter.
    """
    response = self.__connection._make_get_request(
        "/distances-api/api/v1/VesselClasses"
    )
    response.raise_for_status()

    classes = (VesselClass(**c) for c in response.json())
    class_filter = class_filter or VesselClassFilter()

    return tuple(class_filter._apply(classes))

LoadingCondition

Contains constants for available loading conditions.

Source code in signal_ocean/distances/loading_condition.py

class LoadingCondition(metaclass=IterableConstants):
    """Contains constants for available loading conditions."""
    LADEN = 1
    '''
    Vessel is loaded.
    '''
    BALLAST = 2
    '''
    Vessel is free of cargo
    '''

BALLAST = 2 class-attribute instance-attribute

Vessel is free of cargo

LADEN = 1 class-attribute instance-attribute

Vessel is loaded.

Point

Bases: SignalBaseModel

A point on the surface of Earth.

Attributes:

Name	Type	Description
lat	Optional[Decimal]	The latitude of the point.
lon	Optional[Decimal]	The longitude of the point.

Source code in signal_ocean/distances/models.py

class Point(SignalBaseModel):
    """A point on the surface of Earth.

    Attributes:
        lat: The latitude of the point.
        lon: The longitude of the point.
    """

    lat: Optional[Decimal] = None
    lon: Optional[Decimal] = None

PointsOnRoute

Bases: SignalBaseModel

A point and extra properties needed for a route.

Attributes:

Name	Type	Description
is_hra	Optional[bool]	Is the point in a high-risk area.
is_seca	Optional[bool]	Is the point in a Sulfur Emission Control Area.
distance	Optional[Decimal]	The distance between the two points.
distance_to_enter	Optional[Decimal]
heading	Optional[int]	The point on route heading.
editable	Optional[bool]	If the point on route is editable.
name	Optional[str]	The point on route name.
is_shown	Optional[bool]	If the point on route is shown.
delay_mins	Optional[int]	The delay in minutes.
center_point	Optional[Point]	The center point of route.

Source code in signal_ocean/distances/models.py

class PointsOnRoute(SignalBaseModel):
    """A point and extra properties needed for a route.

    Attributes:
        is_hra: Is the point in a high-risk area.
        is_seca: Is the point in a Sulfur Emission Control Area.
        distance: The distance between the two points.
        distance_to_enter:
        heading: The point on route heading.
        editable: If the point on route is editable.
        name: The point on route name.
        is_shown: If the point on route is shown.
        delay_mins: The delay in minutes.
        center_point: The center point of route.
    """

    is_hra: Optional[bool] = None
    is_seca: Optional[bool] = None
    distance: Optional[Decimal] = None
    distance_to_enter: Optional[Decimal] = None
    heading: Optional[int] = None
    editable: Optional[bool] = None
    name: Optional[str] = None
    is_shown: Optional[bool] = None
    delay_mins: Optional[int] = None
    center_point: Optional[Point] = None

Port

Bases: IdentityEqModel

A maritime facility where vessels can dock.

Attributes:

Name	Type	Description
id	int	The ID of the port.
name	str	The name of the port.

Source code in signal_ocean/distances/port.py

class Port(IdentityEqModel):
    """A maritime facility where vessels can dock.

    Attributes:
        id: The ID of the port.
        name: The name of the port.
    """
    id: int
    name: str

PortFilter

Bases: IdentityEqModel

A filter used to find specific ports.

Attributes:

Name	Type	Description
name_like	Optional[str]	Used to find ports by name. When specified, ports whose names partially match (contain) the attribute's value will be returned. Matching is case-insensitive.

Source code in signal_ocean/distances/port_filter.py

class PortFilter(IdentityEqModel):
    """A filter used to find specific ports.

    Attributes:
        name_like: Used to find ports by name. When specified, ports whose
            names partially match (contain) the attribute's value will be
            returned. Matching is case-insensitive.
    """

    model_config = ConfigDict(
        frozen=False,
        populate_by_name=True,
        extra='ignore',
        alias_generator=_to_pascal_case,
    )
    __eq__ = object.__eq__
    __hash__ = object.__hash__

    name_like: Optional[str] = None

    def _apply(self, ports: Iterable[Port]) -> Iterable[Port]:
        return filter(self.__does_port_match, ports)

    def __does_port_match(self, port: Port) -> bool:
        return not self.name_like or contains_caseless(
            self.name_like, port.name
        )

RouteResponse

Bases: SignalBaseModel

A route between two points.

Attributes:

Name	Type	Description
id	Optional[int]	The id of the route response.
start_point	Optional[Point]	Start point coordinates.
end_point	Optional[Point]	End point coordinates.
calculated_route	Optional[Tuple[Point, ...]]	List of coordinates between start and end point.
routing_points_on_route	Optional[Tuple[PointsOnRoute, ...]]	List of points on a route.
distance	Optional[Decimal]	The distance between the two points.
piracy_distance	Optional[Decimal]	The distance between the two points when piracy is considered.
seca_distance	Optional[Decimal]	The distance between the two points when seca is considered.
alternative_paths	Optional[Tuple[AlternativePath, ...]]	List of alternative paths between the two points.
is_empty	Optional[bool]	If the response is empty.
bbox	Optional[Tuple[Decimal, ...]]	The bounding box of the route.

Source code in signal_ocean/distances/models.py

class RouteResponse(SignalBaseModel):
    """A route between two points.

    Attributes:
        id: The id of the route response.
        start_point: Start point coordinates.
        end_point: End point coordinates.
        calculated_route: List of coordinates between start and end point.
        routing_points_on_route: List of points on a route.
        distance: The distance between the two points.
        piracy_distance: The distance between the two points when piracy is
            considered.
        seca_distance: The distance between the two points when seca is
            considered.
        alternative_paths: List of alternative paths between the two points.
        is_empty: If the response is empty.
        bbox: The bounding box of the route.
    """

    id: Optional[int] = None
    start_point: Optional[Point] = None
    end_point: Optional[Point] = None
    calculated_route: Optional[Tuple[Point, ...]] = None
    routing_points_on_route: Optional[Tuple[PointsOnRoute, ...]] = None
    distance: Optional[Decimal] = None
    piracy_distance: Optional[Decimal] = None
    seca_distance: Optional[Decimal] = None
    alternative_paths: Optional[Tuple[AlternativePath, ...]] = None
    is_empty: Optional[bool] = None
    bbox: Optional[Tuple[Decimal, ...]] = None

RouteRestrictions

Bases: SignalBaseModel

Restrictions that can be placed upon a route.

Attributes:

Name	Type	Description
is_suez_open	Optional[bool]	Determines whether or not to route through the Suez Canal.
is_panama_open	Optional[bool]	Determines whether or not to route through the Panama Canal.
is_messina_open	Optional[bool]	Determines whether or not to route through the Strait of Messina.
is_oresund_open	Optional[bool]	Determines whether or not to route through the Øresund Strait.
is_suez_open_only_northbound	Optional[bool]	Determines whether or not to route through the Suez Canal only when northbound.
is_piracy_considered	Optional[bool]	Determines whether or not to route through areas where a piracy threat exists.
minimize_seca	Optional[bool]	Determines whether or not to minimize distance travelled through SECA areas.

Source code in signal_ocean/distances/models.py

class RouteRestrictions(SignalBaseModel):
    """Restrictions that can be placed upon a route.

    Attributes:
        is_suez_open: Determines whether or not to route through the Suez
            Canal.
        is_panama_open: Determines whether or not to route through the Panama
            Canal.
        is_messina_open: Determines whether or not to route through the Strait
            of Messina.
        is_oresund_open: Determines whether or not to route through the Øresund
            Strait.
        is_suez_open_only_northbound: Determines whether or not to route
            through the Suez Canal only when northbound.
        is_piracy_considered: Determines whether or not to route through areas
            where a piracy threat exists.
        minimize_seca: Determines whether or not to minimize distance travelled
            through SECA areas.
    """

    is_suez_open: Optional[bool] = None
    is_panama_open: Optional[bool] = None
    is_messina_open: Optional[bool] = None
    is_oresund_open: Optional[bool] = None
    is_suez_open_only_northbound: Optional[bool] = None
    is_piracy_considered: Optional[bool] = None
    minimize_seca: Optional[bool] = None

    def _to_query_string(self) -> Dict[str, Optional[bool]]:
        return {
            "IsSuezOpen": self.is_suez_open,
            "IsPanamaOpen": self.is_panama_open,
            "IsPiracyConsidered": self.is_piracy_considered,
            "IsMessinaOpen": self.is_messina_open,
            "IsOresundOpen": self.is_oresund_open,
            "IsSuezOpenOnlyNorthbound": self.is_suez_open_only_northbound,
            "MinimizeSeca": self.minimize_seca,
        }

VesselClass

Bases: IdentityEqModel

A group of vessels of similar characteristics.

For example Aframax, Panamax, etc.

Attributes:

Name	Type	Description
id	int	The vessel class ID.
name	str	The vessel class name.

Source code in signal_ocean/distances/vessel_class.py

class VesselClass(IdentityEqModel):
    """A group of vessels of similar characteristics.

    For example Aframax, Panamax, etc.

    Attributes:
        id: The vessel class ID.
        name: The vessel class name.
    """
    id: int
    name: str

VesselClassFilter

Bases: IdentityEqModel

A filter used to find specific vessel classes.

Attributes:

Name	Type	Description
name_like	Optional[str]	Used to find vessel classes by name. When specified, vessel classes whose names partially match (contain) the attribute's value will be returned. Matching is case-insensitive.

Source code in signal_ocean/distances/vessel_class_filter.py

class VesselClassFilter(IdentityEqModel):
    """A filter used to find specific vessel classes.

    Attributes:
        name_like: Used to find vessel classes by name. When specified, vessel
            classes whose names partially match (contain) the attribute's value
            will be returned. Matching is case-insensitive.
    """

    model_config = ConfigDict(
        frozen=False,
        populate_by_name=True,
        extra='ignore',
        alias_generator=_to_pascal_case,
    )
    __eq__ = object.__eq__
    __hash__ = object.__hash__

    name_like: Optional[str] = None

    def _apply(
        self, vessel_classes: Iterable[VesselClass]
    ) -> Iterable[VesselClass]:
        return filter(self.__does_class_match, vessel_classes)

    def __does_class_match(self, vessel_class: VesselClass) -> bool:
        return not self.name_like or contains_caseless(
            self.name_like, vessel_class.name
        )