VesselsList
Description
The VesselsList method returns AIS, Voyage and Master data for a predefined fleet of vessels, identified by IMO or MMSI. The datasets are set by your subscription.
Your vessel list is managed with the ListManager method,
which lets you view, add, replace, or remove vessels. If the list is empty, the method returns
the error [IMO|MMSI] parameter is required.
The minimum time between requests is set by your subscription. Faster requests return the
error Too frequent requests!
| Dataset | Content |
|---|---|
| AIS | Coordinates, course, speed, heading, current draught, destination, ETA and static vessel data |
| Voyage | Last port/country and time of departure |
| 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 |
URL format
https://api.vesselfinder.com/vesselslist?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 |
interval | no | integer | - | The maximum age of the returned positions (in minutes) |
Code examples
curl "https://api.vesselfinder.com/vesselslist?userkey=YOUR_API_KEY"import requests
resp = requests.get(
"https://api.vesselfinder.com/vesselslist",
params={"userkey": "YOUR_API_KEY"},
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',
]);
$data = json_decode(file_get_contents("https://api.vesselfinder.com/vesselslist?$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 vesselslist.mjs)
const params = new URLSearchParams({ userkey: 'YOUR_API_KEY' });
const resp = await fetch(`https://api.vesselfinder.com/vesselslist?${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"}}
resp, err := http.Get("https://api.vesselfinder.com/vesselslist?" + 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
Fleet with AIS dataset
GET https://api.vesselfinder.com/vesselslist?userkey=YOUR_API_KEY
[
{
"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 Sea",
"ECA": true
}
},
{
"AIS": {
"MMSI": 247142520,
"TIMESTAMP": "2017-08-11 11:09:43 UTC",
"LATITUDE": 37.93858,
"LONGITUDE": 20.33623,
"COURSE": 327.3,
"SPEED": 9.0,
"HEADING": 511,
"NAVSTAT": 0,
"IMO": 0,
"NAME": "MARIELLA II",
"CALLSIGN": "IZTN",
"TYPE": 30,
"A": 6,
"B": 12,
"C": 1,
"D": 4,
"DRAUGHT": 2.0,
"DESTINATION": "PESCA",
"LOCODE": "",
"ETA_AIS": "00-00 24:60",
"ETA": "",
"SRC": "TER",
"ZONE": "Black Sea",
"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 UTC",
"SRC": "TER",
"ZONE": "North Sea",
"ECA": true
}
}
]<VESSELS>
<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 Sea" ECA="true"/>
</VESSEL>
<VESSEL>
<AIS MMSI="247142520" TIMESTAMP="2017-08-11 11:09:43 UTC" LATITUDE="37.93858" LONGITUDE="20.33623" COURSE="327.3" SPEED="9.0" HEADING="511" NAVSTAT="0" IMO="0" NAME="MARIELLA II" CALLSIGN="IZTN" TYPE="30" A="6" B="12" C="1" D="4" DRAUGHT="2.0" DESTINATION="PESCA" LOCODE="" ETA_AIS="00-00 24:60" ETA="" SRC="TER" ZONE="Black Sea" 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 UTC" SRC="TER" ZONE="North Sea" ECA="true"/>
</VESSEL>
</VESSELS>Fleet with AIS, Voyage and Master datasets
GET https://api.vesselfinder.com/vesselslist?userkey=YOUR_API_KEY
[
{
"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>