Distance Calculator

Introduction to the Distance Calculator

The DistanceCalculator service provides an easy way for users to calculate distances and shortest route between ports and vessels.

More examples can be found in the following juypyter notebook: Calculating Distances

DistanceCalculator Client

class oceanbolt.sdk.distance.DistanceCalculator(client: APIClient)

DistanceCalculator provides an interface to calculate shortest route between ports/vessels

distance()

Calculates the shortest distance between a list of locations.

duration()

Calculates expected duration for a voyage between a list of locations, given a speed provided by the user.

shortest_route()

Calculates the shortest route between a list of locations, and returns the route as a pandas dataframe of lat/lons.

get_raw()

Provides access to the raw response from the API, which includes breakdown by individual legs, in case of a waypoint route calculation.

batch_distance()

Batch calculates the shortest distance between a list of locations.

batch_duration()

Batch calculates expected duration for a voyage between a list of locations, given a speed provided by the user.

batch_shortest_route()

Batch calculates the shortest route between a list of locations, and returns the route as pandas dataframes of lat/lons.

batch_get_raw()

Provides access to the raw response from the API, which includes breakdown by individual legs, in case of a waypoint route calculation.

Calculating the shortest distance

Example

from oceanbolt.sdk.client import APIClient
from oceanbolt.sdk.distance import DistanceCalculator
from oceanbolt.sdk.data.entities import Search
base_client = APIClient("<TOKEN>")

#Distance between ports
distance = DistanceCalculator(base_client).distance(
    locations=[
        {"unlocode": "USHOU"},
        {"unlocode": "HKHKG"},
    ]
)

#Distance between a vessel's current location and a port
distance = DistanceCalculator(base_client).distance(
    locations=[
        {"imo": 9586801},
        {"unlocode": "HKHKG"},
    ]
)

#Distance calculation with a waypoint
distance = DistanceCalculator(APIClient()).distance(
    locations=[
        {"unlocode":"AUPHE"},
        {"unlocode":"HKHKG"},
        {"unlocode":"USHOU"}
    ]
)

#Distance between a raw coordinates
distance = DistanceCalculator(base_client).distance(
    locations=[
        {"point": {"lon":-75.522015,"lat":10.298378}},
        {"point": {"lon":-95.127000,"lat":29.727500}},
    ]
)

Arguments

class oceanbolt.com.distancecalculator_v3.types.DistanceRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Request object for CalculateDistance method

locations

List of locations to calculate the shortest route between. If more than 2 locations are specified, then routing will be calculated through all locations, using intermediary locations as waypoints. The routing order of the locations will be based on the order of the locations in the request body.

Type:

MutableSequence[oceanbolt.com.distancecalculator_v3.types.Location]

speed

An optional speed parameter. If this is supplied, then the API will return an estimate of the total duration of the voyage, based on the supplied speed. Speed parameter should be supplied in knots.

Type:

float

transform

Specifies a transformation to be applied to the returned shortest path. Allowed values are [great_circle].

Type:

str

longitude_adjustment

Specifies whether the resulting points/lines crossing the antimeridian should be adjusted to form a continuous line for plotting. Allowed values are [antimeridian,none]. Default value is ‘antimeridian.

Type:

str

block_suez

Flag indicating whether to block navigation through the Suez Canal

Type:

bool

block_panama

Flag indicating whether to Block navigation through the Panama Canal

Type:

bool

Response

class oceanbolt.com.distancecalculator_v3.types.DistanceResponse(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Response object for CalculateDistance method

total_distance

Total distance of the entire voyage in nautical miles.

Type:

float

total_duration_hours

Total expected duration of the entire voyage, given a certain speed supplied by the user.

Type:

float

total_shortest_path

The calculated shortest path between the start/end point of the entire voyage.

Type:

MutableSequence[oceanbolt.com.distancecalculator_v3.types.Point]

individual_legs

Array of the individual legs that compose the voyage

Type:

MutableSequence[oceanbolt.com.distancecalculator_v3.types.Leg]

status

Status

Type:

oceanbolt.com.distancecalculator_v3.types.DistanceResponse.DistanceAlgorithmStatus

class DistanceAlgorithmStatus(value)

Values:

ALGORITHM_ERROR (0):

No description available.

PLANAR (1):

No description available.

SPHERICAL (2):

No description available.

Batch Calculations

The distance calculator also supports batch calculations. The primary usage differences from non-batch calculations are in the client’s method name, prefixed with “batch_”, and in the request object, where each request to be calculated is an element of a requests array.

Batch methods include:

• batch_distance()

• batch_duration()

• batch_shortest_route()

• batch_get_raw()

Example

from oceanbolt.sdk.client import APIClient
from oceanbolt.sdk.distance import DistanceCalculator
from oceanbolt.sdk.data.entities import Search
base_client = APIClient("<TOKEN>")

distances = DistanceCalculator(base_client).batch_distance(
    requests=[
        {
            "locations": [
                {"unlocode": "AUPHE"},
                {"unlocode": "HKHKG"},
                {"unlocode": "USHOU"}
            ]
        },
        {
            "locations": [
                {"point": {"lon":-75.522015,"lat":10.298378}},
                {"point": {"lon":-95.127000,"lat":29.727500}}
            ]
        }
    ]
)