Distance

Description

The Distance method returns the shortest sea route between two points and its length. The response is in GeoJSON format. XML is not supported.

Each successful response costs 1 credit.

URL format

https://api.vesselfinder.com/distance?userkey=YOUR_API_KEY&from=lon1,lat1&to=lon2,lat2&param=value&…

Parameters

Parameter	Required	Type	Default	Description
`userkey`	yes	text	-	Your personal API key
`from`	yes	text	-	Comma separated longitude, latitude of the first point
`to`	yes	text	-	Comma separated longitude, latitude of the second point
`gateways`	no	text	-	Comma separated list of straits, canals and passages to open for crossing. All are closed by default
`ECA`	no	text	allow	ECA zone crossing preferences (`allow`, `deny`, `minimize`)
`EPSG3857`	no	integer	0	If set to `1` returns coordinates in EPSG:3857 (Web Mercator)

With ECA=deny, if no route avoids the ECA zones, the API returns the error path not found.

Available gateways

Gateway	Description
`suez`	Suez Canal
`panama`	Panama Canal
`kiel`	Kiel Canal
`oresund`	Oresund Strait
`messina`	Messina Strait
`corinth`	Corinth Canal
`malacca`	Malacca Strait
`drake`	Drake Passage
`magellan`	Magellan Strait
`northeast`	Northeast Passage
`northwest`	Northwest Passage

Code examples

curl "https://api.vesselfinder.com/distance?userkey=YOUR_API_KEY&from=27.3711,43.256&to=128.345,-34.223&gateways=panama,suez"

import requests

resp = requests.get(
    "https://api.vesselfinder.com/distance",
    params={
        "userkey": "YOUR_API_KEY",
        "from": "27.3711,43.256",
        "to": "128.345,-34.223",
        "gateways": "panama,suez",
    },
    timeout=30,
)
route = resp.json()
if "error" in route:
    raise RuntimeError(route["error"])

props = route["properties"]
print(round(props["Distance"] / 1852, 1), "nautical miles")
print("via", ", ".join(props["Crossing"]))

<?php
$query = http_build_query([
    'userkey'  => 'YOUR_API_KEY',
    'from'     => '27.3711,43.256',
    'to'       => '128.345,-34.223',
    'gateways' => 'panama,suez',
]);
$route = json_decode(file_get_contents("https://api.vesselfinder.com/distance?$query"), true);
if (isset($route['error'])) {
    throw new Exception($route['error']);
}

$props = $route['properties'];
echo round($props['Distance'] / 1852, 1), " nautical miles\n";
echo 'via ', implode(', ', $props['Crossing']), "\n";

// Node.js 18+ (save as distance.mjs)
const params = new URLSearchParams({
  userkey: 'YOUR_API_KEY',
  from: '27.3711,43.256',
  to: '128.345,-34.223',
  gateways: 'panama,suez',
});
const resp = await fetch(`https://api.vesselfinder.com/distance?${params}`);
const route = await resp.json();
if (route.error) throw new Error(route.error);

const { Distance, Crossing } = route.properties;
console.log((Distance / 1852).toFixed(1), 'nautical miles');
console.log('via', Crossing.join(', '));

package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"net/url"
	"strings"
)

func main() {
	q := url.Values{
		"userkey":  {"YOUR_API_KEY"},
		"from":     {"27.3711,43.256"},
		"to":       {"128.345,-34.223"},
		"gateways": {"panama,suez"},
	}
	resp, err := http.Get("https://api.vesselfinder.com/distance?" + q.Encode())
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	var route struct {
		Error      string `json:"error"`
		Properties struct {
			Crossing []string
			Distance float64
		} `json:"properties"`
	}
	if err := json.NewDecoder(resp.Body).Decode(&route); err != nil {
		log.Fatal(err)
	}
	if route.Error != "" {
		log.Fatal(route.Error)
	}
	fmt.Printf("%.1f nautical miles\n", route.Properties.Distance/1852)
	fmt.Println("via", strings.Join(route.Properties.Crossing, ", "))
}

Example

GET https://api.vesselfinder.com/distance?userkey=YOUR_API_KEY&from=27.3711,43.256&to=128.345,-34.223&gateways=panama,suez

GeoJSON

{
  "geometry": {
    "coordinates": [
      [
        27.3711,
        43.256
      ],
      [
        27.939036,
        43.190176
      ],
      [
        28.018078,
        43.182272
      ],
      [...]
    ],
    "type": "LineString"
  },
  "properties": {
    "Crossing": [
      "Bosporus strait",
      "Dardanelles strait",
      "Suez canal",
      "Bab-el-Mandab strait",
      "SW Australia"
    ],
    "Distance": 15414989,
    "DistanceECA": 0
  },
  "type": "Feature"
}

Crossing property contains a list of all straits, canals and passages along the calculated route.
Distance property is the length (in meters) of the calculated route.
DistanceECA property is the length (in meters) of the calculated route in ECA zones.