Vessels
Description
The Vessels method returns AIS data, with optional Voyage and Master datasets, for one or more vessels.
| Dataset | Content | Credits |
|---|---|---|
| AIS | Coordinates, course, speed, heading, current draught, destination, ETA and static vessel data | 1 |
| Voyage | Last port/country and time of departure | 1 |
| Master | IMO, name, flag, type, year of build, builder, owner / manager, classification society, dimensions, maximum draught, gross tonnage, net tonnage, deadweight, TEU, crude and gas capacity | 2 |
URL format
https://api.vesselfinder.com/vessels?userkey=YOUR_API_KEY¶m=value&…
Parameters
| Parameter | Required | Type | Default | Description |
|---|---|---|---|---|
userkey | yes | text | - | Your personal API key |
format | no | text | json | Response format json or xml |
extradata | no | text | - | Additional datasets: voyage, master or both: voyage,master |
interval | no | integer | - | The maximum age of the returned positions (in minutes) |
imo | yes* | list of integers | - | List of IMO numbers (comma separated) |
mmsi | yes* | list of integers | - | List of MMSI numbers (comma separated) |
(*) Vessels can be specified using a list of IMO numbers, MMSI numbers, or a combination of both.
Code examples
curl "https://api.vesselfinder.com/vessels?userkey=YOUR_API_KEY&imo=9175717"
import requests
resp = requests.get(
"https://api.vesselfinder.com/vessels",
params={"userkey": "YOUR_API_KEY", "imo": "9175717"},
timeout=30,
)
data = resp.json()
if isinstance(data, dict) and "error" in data:
raise RuntimeError(data["error"])
for vessel in data:
ais = vessel["AIS"]
print(ais["NAME"], ais["LATITUDE"], ais["LONGITUDE"])
<?php
$query = http_build_query([
'userkey' => 'YOUR_API_KEY',
'imo' => '9175717',
]);
$data = json_decode(file_get_contents("https://api.vesselfinder.com/vessels?$query"), true);
if (isset($data['error'])) {
throw new Exception($data['error']);
}
foreach ($data as $vessel) {
$ais = $vessel['AIS'];
echo "{$ais['NAME']} {$ais['LATITUDE']} {$ais['LONGITUDE']}\n";
}
// Node.js 18+ (save as vessels.mjs)
const params = new URLSearchParams({ userkey: 'YOUR_API_KEY', imo: '9175717' });
const resp = await fetch(`https://api.vesselfinder.com/vessels?${params}`);
const data = await resp.json();
if (data.error) throw new Error(data.error);
for (const { AIS: ais } of data) {
console.log(ais.NAME, ais.LATITUDE, ais.LONGITUDE);
}
package main
import (
"encoding/json"
"fmt"
"log"
"net/http"
"net/url"
)
type vessel struct {
AIS struct {
NAME string
LATITUDE float64
LONGITUDE float64
}
}
func main() {
q := url.Values{"userkey": {"YOUR_API_KEY"}, "imo": {"9175717"}}
resp, err := http.Get("https://api.vesselfinder.com/vessels?" + q.Encode())
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
var raw json.RawMessage
if err := json.NewDecoder(resp.Body).Decode(&raw); err != nil {
log.Fatal(err)
}
var apiErr struct{ Error string }
if json.Unmarshal(raw, &apiErr) == nil && apiErr.Error != "" {
log.Fatal(apiErr.Error)
}
var vessels []vessel
if err := json.Unmarshal(raw, &vessels); err != nil {
log.Fatal(err)
}
for _, v := range vessels {
fmt.Println(v.AIS.NAME, v.AIS.LATITUDE, v.AIS.LONGITUDE)
}
}
Examples
One vessel by IMO
GET https://api.vesselfinder.com/vessels?userkey=YOUR_API_KEY&imo=9175717
[
{
"AIS": {
"MMSI": 304491000,
"TIMESTAMP": "2017-08-11 11:15:15 UTC",
"LATITUDE": 40.07288,
"LONGITUDE": 154.48535,
"COURSE": 285.6,
"SPEED": 14.0,
"HEADING": 286,
"NAVSTAT": 0,
"IMO": 9175717,
"NAME": "MARENO",
"CALLSIGN": "V2BC5",
"TYPE": 70,
"A": 133,
"B": 20,
"C": 14,
"D": 11,
"DRAUGHT": 8.7,
"DESTINATION": "GIOIA TAURO",
"LOCODE": "ITGIT",
"ETA_AIS": "08-12 03:00",
"ETA": "2017-08-12 03:00:00",
"SRC": "TER",
"ZONE": "North Pacific Ocean",
"ECA": false
}
}
]
<VESSELS>
<VESSEL>
<AIS MMSI="304491000" TIMESTAMP="2017-08-11 11:15:15 UTC" LATITUDE="40.07288" LONGITUDE="154.48535" COURSE="285.6" SPEED="14.0" HEADING="286" NAVSTAT="0" IMO="9175717" NAME="MARENO" CALLSIGN="V2BC5" TYPE="70" A="133" B="20" C="14" D="11" DRAUGHT="8.7" DESTINATION="GIOIA TAURO" LOCODE="ITGIT" ETA_AIS="08-12 03:00" ETA="2017-08-12 03:00:00" SRC="TER" ZONE="North Pacific Ocean" ECA="false"/>
</VESSEL>
</VESSELS>
Several vessels by IMO and MMSI
GET https://api.vesselfinder.com/vessels?userkey=YOUR_API_KEY&imo=9228801,9441271&mmsi=227441980
[
{
"AIS": {
"MMSI": 215096000,
"TIMESTAMP": "2017-08-11 11:14:03 UTC",
"LATITUDE": 42.82085,
"LONGITUDE": 9.98676,
"COURSE": 357.0,
"SPEED": 11.2,
"HEADING": 8,
"NAVSTAT": 0,
"IMO": 9228801,
"NAME": "BALTIC SKY I",
"CALLSIGN": "9HCD7",
"TYPE": 89,
"A": 152,
"B": 30,
"C": 7,
"D": 20,
"DRAUGHT": 10.7,
"DESTINATION": "GENOA",
"LOCODE": "ITGOA",
"ETA_AIS": "08-12 08:00",
"ETA": "2017-08-12 08:00:00",
"SRC": "TER",
"ZONE": "North Pacific Ocean",
"ECA": false
}
},
{
"AIS": {
"MMSI": 227441980,
"TIMESTAMP": "2017-08-11 11:17:37 UTC",
"LATITUDE": 46.1459,
"LONGITUDE": -1.16631,
"COURSE": 360.0,
"SPEED": 0.0,
"HEADING": 511,
"NAVSTAT": 1,
"IMO": 0,
"NAME": "CLEMENTINE",
"CALLSIGN": "FJVK",
"TYPE": 60,
"A": 0,
"B": 0,
"C": 0,
"D": 0,
"DRAUGHT": 0.0,
"DESTINATION": "",
"LOCODE": "",
"ETA_AIS": "00-00 00:00",
"ETA": "",
"SRC": "TER",
"ZONE": "North Pacific Ocean",
"ECA": false
}
},
{
"AIS": {
"MMSI": 538003777,
"TIMESTAMP": "2017-08-11 11:18:05 UTC",
"LATITUDE": 36.28361,
"LONGITUDE": -3.5416,
"COURSE": 260.0,
"SPEED": 11.2,
"HEADING": 260,
"NAVSTAT": 0,
"IMO": 9441271,
"NAME": "M/V CANARY",
"CALLSIGN": "V7TC3",
"TYPE": 70,
"A": 160,
"B": 30,
"C": 10,
"D": 22,
"DRAUGHT": 12.3,
"DESTINATION": "GIBRALTAR",
"LOCODE": "GIGIB",
"ETA_AIS": "08-11 04:00",
"ETA": "2017-08-11 04:00:00",
"SRC": "TER",
"ZONE": "Black Sea",
"ECA": false
}
}
]
<VESSELS>
<VESSEL>
<AIS MMSI="215096000" TIMESTAMP="2017-08-11 11:14:03 UTC" LATITUDE="42.82085" LONGITUDE="9.98676" COURSE="357.0" SPEED="11.2" HEADING="8" NAVSTAT="0" IMO="9228801" NAME="BALTIC SKY I" CALLSIGN="9HCD7" TYPE="89" A="152" B="30" C="7" D="20" DRAUGHT="10.7" DESTINATION="GENOA" LOCODE="ITGOA" ETA_AIS="08-12 08:00" ETA="2017-08-12 08:00:00" SRC="TER" ZONE="North Pacific Ocean" ECA="false"/>
</VESSEL>
<VESSEL>
<AIS MMSI="227441980" TIMESTAMP="2017-08-11 11:17:37 UTC" LATITUDE="46.1459" LONGITUDE="-1.16631" COURSE="360.0" SPEED="0.0" HEADING="511" NAVSTAT="1" IMO="0" NAME="CLEMENTINE" CALLSIGN="FJVK" TYPE="60" A="0" B="0" C="0" D="0" DRAUGHT="0.0" DESTINATION="" LOCODE="" ETA_AIS="00-00 00:00" ETA="" SRC="TER" ZONE="North Pacific Ocean" ECA="false"/>
</VESSEL>
<VESSEL>
<AIS MMSI="538003777" TIMESTAMP="2017-08-11 11:18:05 UTC" LATITUDE="36.28361" LONGITUDE="-3.5416" COURSE="260.0" SPEED="11.2" HEADING="260" NAVSTAT="0" IMO="9441271" NAME="M/V CANARY" CALLSIGN="V7TC3" TYPE="70" A="160" B="30" C="10" D="22" DRAUGHT="12.3" DESTINATION="GIBRALTAR" LOCODE="GIGIB" ETA_AIS="08-11 04:00" ETA="2017-08-11 04:00:00" SRC="TER" ZONE="Black Sea" ECA="false"/>
</VESSEL>
</VESSELS>
With Voyage and Master datasets
GET https://api.vesselfinder.com/vessels?userkey=YOUR_API_KEY&extradata=voyage,master&imo=9607198
[
{
"AIS": {
"MMSI": 566554000,
"TIMESTAMP": "2017-08-11 11:43:42 UTC",
"LATITUDE": 54.29732,
"LONGITUDE": 4.75682,
"COURSE": 7.8,
"SPEED": 11.5,
"HEADING": 5,
"IMO": 9607198,
"NAVSTAT": 0,
"NAME": "BW HAWK",
"CALLSIGN": "9V2920",
"TYPE": 80,
"A": 150,
"B": 33,
"C": 9,
"D": 23,
"DRAUGHT": 9.2,
"DESTINATION": "FRURO>NOMLK",
"LOCODE": "NOMLK",
"ETA_AIS": "08-17 00:01",
"ETA": "2017-08-17 00:01:00",
"SRC": "TER",
"ZONE": "Black Sea",
"ECA": false
},
"MASTERDATA": {
"IMO": 9607198,
"NAME": "BW HAWK",
"FLAG": "SG",
"TYPE": "Chemical/Oil Products Tanker",
"BUILT": 2015,
"BUILDER": "SPP SB CO",
"OWNER": "BW CLEARWATER PTE LTD",
"MANAGER": "BW MARITIME PTE LTD",
"CLASS": "AMERICAN BUREAU OF SHIPPING",
"LENGTH": 183.0,
"BEAM": 32.2,
"MAXDRAUGHT": 10.5,
"GT": 29768,
"NT": 0,
"DWT": 49999,
"CRUDE": 82500,
"GAS": 0
},
"VOYAGE": {
"LOCODE": "FRPET",
"DEPARTURE": "2017-08-09 17:26:38 UTC",
"LASTPORT": "Petit-Couronne",
"LASTCOUNTRY": "France"
}
}
]
<VESSELS>
<VESSEL>
<AIS MMSI="566554000" TIMESTAMP="2017-08-11 11:43:42 UTC" LATITUDE="54.29732" LONGITUDE="4.75682" COURSE="7.8" SPEED="11.5" HEADING="5" IMO="9607198" NAVSTAT="0" NAME="BW HAWK" CALLSIGN="9V2920" TYPE="80" A="150" B="33" C="9" D="23" DRAUGHT="9.2" DESTINATION="FRURO>NOMLK" LOCODE="NOMLK" ETA_AIS="08-17 00:01" ETA="2017-08-17 00:01:00" SRC="TER" ZONE="Black Sea" ECA="false"/>
<MASTERDATA IMO="9607198" NAME="BW HAWK" FLAG="SG" TYPE="Chemical/Oil Products Tanker" BUILT="2015" BUILDER="SPP SB CO" OWNER="BW CLEARWATER PTE LTD" MANAGER="BW MARITIME PTE LTD" CLASS="AMERICAN BUREAU OF SHIPPING" LENGTH="183.0" BEAM="32.2" MAXDRAUGHT="10.5" GT="29768" NT="0" DWT="49999" CRUDE="82500" GAS="0"/>
<VOYAGE LOCODE="FRPET" DEPARTURE="2017-08-09 17:26:38 UTC" LASTPORT="Petit-Couronne" LASTCOUNTRY="France"/>
</VESSEL>
</VESSELS>