LiveData
Description
The LiveData method returns AIS, Voyage and Master data for all vessels in a predefined geographic area. The area, datasets and filters (type, size etc.) are set by your subscription.
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/livedata?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/livedata?userkey=YOUR_API_KEY"
import requests
resp = requests.get(
"https://api.vesselfinder.com/livedata",
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/livedata?$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 livedata.mjs)
const params = new URLSearchParams({ userkey: 'YOUR_API_KEY' });
const resp = await fetch(`https://api.vesselfinder.com/livedata?${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/livedata?" + 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
Area with AIS dataset
GET https://api.vesselfinder.com/livedata?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>
Area with AIS, Voyage and Master datasets
GET https://api.vesselfinder.com/livedata?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>