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 dataclass

An alternative path for the route.

Attributes:

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

Source code in signal_ocean/distances/models.py

@dataclass(frozen=True)
class AlternativePath:
    """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: Tuple[Point, ...]
    distance: Decimal
    routing_points_on_route: Tuple[PointsOnRoute, ...]
    piracy_distance: Decimal
    seca_distance: Decimal

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 dataclass

A point on the surface of Earth.

Attributes:

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

Source code in signal_ocean/distances/models.py

@dataclass(frozen=True)
class Point:
    """A point on the surface of Earth.

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

    lat: Decimal
    lon: Decimal

PointsOnRoute dataclass

A point and extra properties needed for a route.

Attributes:

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

Source code in signal_ocean/distances/models.py

@dataclass(frozen=True)
class PointsOnRoute:
    """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: bool
    is_seca: bool
    distance: Decimal
    distance_to_enter: Decimal
    heading: int
    editable: bool
    name: str
    is_shown: bool
    delay_mins: int
    center_point: Point

Port dataclass

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

@dataclass(frozen=True, eq=False)
class Port:
    """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 dataclass

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

@dataclass(eq=False)
class PortFilter:
    """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.
    """

    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 dataclass

A route between two points.

Attributes:

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

Source code in signal_ocean/distances/models.py

@dataclass(frozen=True)
class RouteResponse:
    """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: int
    start_point: Point
    end_point: Point
    calculated_route: Tuple[Point, ...]
    routing_points_on_route: Tuple[PointsOnRoute, ...]
    distance: Decimal
    piracy_distance: Decimal
    seca_distance: Decimal
    alternative_paths: Tuple[AlternativePath, ...]
    is_empty: bool
    bbox: Optional[Tuple[Decimal, ...]]

RouteRestrictions dataclass

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

@dataclass(frozen=True)
class RouteRestrictions:
    """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 dataclass

A group of vessels of similar characteristics, i.e. 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

@dataclass(frozen=True, eq=False)
class VesselClass:
    """A group of vessels of similar characteristics, i.e. Aframax, Panamax, etc.

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

VesselClassFilter dataclass

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

@dataclass(eq=False)
class VesselClassFilter:
    """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.
    """

    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
        )