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: oceanbolt.sdk.client.APIClient)[source]

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

distance()[source]

Calculates the shortest distance between a list of locations.

duration()[source]

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

shortest_route()[source]

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

get_raw()[source]

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

#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"}
    ]
)

Arguments

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

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

Sequence[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

Response

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

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

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

individual_legs

Array of the individual legs that compose the voyage

Type

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