# 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]