ExpectedArrivals

Description

The ExpectedArrivals method returns AIS data, with optional Voyage and Master datasets, for all vessels expected at a port within a given period. A vessel is included when the port is entered as destination in its AIS transponder.

Dataset	Content	Credits
AIS	Coordinates, course, speed, heading, current draught, destination, ETA and static vessel data	5
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/expectedarrivals?userkey=YOUR_API_KEY&param=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`
`limit`	no	integer	-	Maximum number of returned records
`interval`	yes*	integer	-	Time interval (minutes) in the future to check for expected arrivals
`fromdate`	yes*	datetime	-	Start of the period, UTC (YYYY-MM-DD HH:MM:SS)
`todate`	yes*	datetime	-	End of the period, UTC (YYYY-MM-DD HH:MM:SS)
`locode`	yes	text	-	UN/LOCODE of the port
`aistype`	no	list of integers	-	List of vessel types, see AIS Ship Types (e.g. `70,80`)

(*) The request must specify a time span with either interval or fromdate and todate.

Code examples

curl "https://api.vesselfinder.com/expectedarrivals?userkey=YOUR_API_KEY&interval=1440&locode=BGVAR"

import requests

resp = requests.get(
    "https://api.vesselfinder.com/expectedarrivals",
    params={"userkey": "YOUR_API_KEY", "interval": "1440", "locode": "BGVAR"},
    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',
    'interval' => '1440',
    'locode'   => 'BGVAR',
]);
$data = json_decode(file_get_contents("https://api.vesselfinder.com/expectedarrivals?$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 expectedarrivals.mjs)
const params = new URLSearchParams({ userkey: 'YOUR_API_KEY', interval: '1440', locode: 'BGVAR' });
const resp = await fetch(`https://api.vesselfinder.com/expectedarrivals?${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"}, "interval": {"1440"}, "locode": {"BGVAR"}}
	resp, err := http.Get("https://api.vesselfinder.com/expectedarrivals?" + 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

Vessels expected in the next 24 hours

GET https://api.vesselfinder.com/expectedarrivals?userkey=YOUR_API_KEY&interval=1440&locode=BGVAR

[
    {
        "AIS": {
            "MMSI": 636092343,
            "TIMESTAMP": "2017-08-16 13:02:17 UTC",
            "LATITUDE": 40.79601,
            "LONGITUDE": 28.89114,
            "COURSE": 138.5,
            "SPEED": 0.4,
            "HEADING": 135,
            "NAVSTAT": 1,
            "IMO": 9407469,
            "NAME": "ANNA-MARIA",
            "CALLSIGN": "D5AS7",
            "TYPE": 70,
            "A": 162,
            "B": 28,
            "C": 21,
            "D": 11,
            "DRAUGHT": 6.5,
            "DESTINATION": "VARNA",
            "LOCODE": "BGVAR",
            "ETA_AIS": "08-16 14:00",
            "ETA": "2017-08-16 14:00:00",
            "SRC": "TER",
            "ZONE": "Black Sea",
            "ECA": false
        }
    },
    {
        "AIS": {
            "MMSI": 271001057,
            "TIMESTAMP": "2017-08-16 13:06:41 UTC",
            "LATITUDE": 43.0857,
            "LONGITUDE": 27.95016,
            "COURSE": 160.0,
            "SPEED": 0.5,
            "HEADING": 73,
            "NAVSTAT": 1,
            "IMO": 9126742,
            "NAME": "ROZA A",
            "CALLSIGN": "TCRB7",
            "TYPE": 71,
            "A": 138,
            "B": 30,
            "C": 10,
            "D": 10,
            "DRAUGHT": 7.5,
            "DESTINATION": "BGVAR",
            "LOCODE": "BGVAR",
            "ETA_AIS": "08-16 15:00",
            "ETA": "2017-08-16 15:00:00",
            "SRC": "TER",
            "ZONE": "Black Sea",
            "ECA": false
        }
    }
]

<VESSELS>
  <VESSEL>
    <AIS MMSI="636092343" TIMESTAMP="2017-08-16 13:02:17 UTC" LATITUDE="40.79601" LONGITUDE="28.89114" COURSE="138.5" SPEED="0.4" HEADING="135" NAVSTAT="1" IMO="9407469" NAME="ANNA-MARIA" CALLSIGN="D5AS7" TYPE="70" A="162" B="28" C="21" D="11" DRAUGHT="6.5" DESTINATION="VARNA" LOCODE="BGVAR" ETA_AIS="08-16 14:00" ETA="2017-08-16 14:00:00" SRC="TER" ZONE="Black Sea" ECA="false"/>
  </VESSEL>
  <VESSEL>
    <AIS MMSI="271001057" TIMESTAMP="2017-08-16 13:06:41 UTC" LATITUDE="43.0857" LONGITUDE="27.95016" COURSE="160.0" SPEED="0.5" HEADING="73" NAVSTAT="1" IMO="9126742" NAME="ROZA A" CALLSIGN="TCRB7" TYPE="71" A="138" B="30" C="10" D="10" DRAUGHT="7.5" DESTINATION="BGVAR" LOCODE="BGVAR" ETA_AIS="08-16 15:00" ETA="2017-08-16 15:00:00" SRC="TER" ZONE="Black Sea" ECA="false"/>
  </VESSEL>
</VESSELS>

With Voyage and Master datasets

GET https://api.vesselfinder.com/expectedarrivals?userkey=YOUR_API_KEY&extradata=voyage,master&interval=1440&locode=BGVAR

[
    {
        "AIS": {
            "MMSI": 636092343,
            "TIMESTAMP": "2017-08-16 13:09:20 UTC",
            "LATITUDE": 40.79497,
            "LONGITUDE": 28.89261,
            "COURSE": 152.0,
            "SPEED": 0.9,
            "HEADING": 162,
            "NAVSTAT": 1,
            "IMO": 9407469,
            "NAME": "ANNA-MARIA",
            "CALLSIGN": "D5AS7",
            "TYPE": 70,
            "A": 162,
            "B": 28,
            "C": 21,
            "D": 11,
            "DRAUGHT": 6.5,
            "DESTINATION": "VARNA",
            "LOCODE": "BGVAR",
            "ETA_AIS": "08-16 14:00",
            "ETA": "2017-08-16 14:00:00",
            "SRC": "TER",
            "ZONE": "Black Sea",
            "ECA": false
        },
        "MASTERDATA": {
            "IMO": 9407469,
            "NAME": "ANNA-MARIA",
            "FLAG": "LR",
            "TYPE": "Bulk Carrier",
            "BUILT": 2007,
            "BUILDER": "KAWASAKI",
            "OWNER": "ANNA-MARIA SCHIFFAHRTS",
            "MANAGER": "BLUMENTHAL JMK GMBH & CO KG",
            "CLASS": "NIPPON KAIJI KYOKAI",
            "LENGTH": 189.9,
            "BEAM": 32.3,
            "MAXDRAUGHT": 13.0,
            "GT": 30811,
            "NT": 18205,
            "DWT": 55473,
            "TEU": 0,
            "CRUDE": 0,
            "GAS": 0
        },
        "VOYAGE": {
            "LOCODE": "BR002",
            "DEPARTURE": "2017-06-10 15:20:10 UTC",
            "LASTPORT": "Santos Anchorage",
            "LASTCOUNTRY": "Brazil"
        }
    },
    {
        "AIS": {
            "MMSI": 271001057,
            "TIMESTAMP": "2017-08-16 13:09:40 UTC",
            "LATITUDE": 43.08535,
            "LONGITUDE": 27.95031,
            "COURSE": 166.0,
            "SPEED": 0.2,
            "HEADING": 54,
            "NAVSTAT": 1,
            "IMO": 9126742,
            "NAME": "ROZA A",
            "CALLSIGN": "TCRB7",
            "TYPE": 71,
            "A": 138,
            "B": 30,
            "C": 10,
            "D": 10,
            "DRAUGHT": 7.5,
            "DESTINATION": "BGVAR",
            "LOCODE": "BGVAR",
            "ETA_AIS": "08-16 15:00",
            "ETA": "2017-08-16 15:00:00",
            "SRC": "TER",
            "ZONE": "Black Sea",
            "ECA": false
        },
        "MASTERDATA": {
            "IMO": 9126742,
            "NAME": "ROZA A",
            "FLAG": "TR",
            "TYPE": "Container Ship",
            "BUILT": 1997,
            "BUILDER": "CHINA SB CORP",
            "OWNER": "LIMAR LIMAN",
            "MANAGER": "ARKAS DENIZCILIK VE NAKLIYAT",
            "CLASS": "AMERICAN BUREAU OF SHIPPING",
            "LENGTH": 168.8,
            "BEAM": 27.3,
            "MAXDRAUGHT": 13.5,
            "GT": 15120,
            "NT": 6764,
            "DWT": 19325,
            "TEU": 1439,
            "CRUDE": 0,
            "GAS": 0
        },
        "VOYAGE": {
            "LOCODE": "TRAMB",
            "DEPARTURE": "2017-08-15 12:05:56 UTC",
            "LASTPORT": "Ambarli",
            "LASTCOUNTRY": "Turkey"
        }
    }
]

<VESSELS>
  <VESSEL>
    <AIS MMSI="636092343" TIMESTAMP="2017-08-16 13:09:20 UTC" LATITUDE="40.79497" LONGITUDE="28.89261" COURSE="152.0" SPEED="0.9" HEADING="162" NAVSTAT="1" IMO="9407469" NAME="ANNA-MARIA" CALLSIGN="D5AS7" TYPE="70" A="162" B="28" C="21" D="11" DRAUGHT="6.5" DESTINATION="VARNA" LOCODE="BGVAR" ETA_AIS="08-16 14:00" ETA="2017-08-16 14:00:00" SRC="TER" ZONE="Black Sea" ECA="false"/>
    <MASTERDATA IMO="9407469" NAME="ANNA-MARIA" FLAG="LR" TYPE="Bulk Carrier" BUILT="2007" BUILDER="KAWASAKI" OWNER="ANNA-MARIA SCHIFFAHRTS" MANAGER="BLUMENTHAL JMK GMBH &amp; CO KG" CLASS="NIPPON KAIJI KYOKAI" LENGTH="189.9" BEAM="32.3" MAXDRAUGHT="13.0" GT="30811" NT="18205" DWT="55473" TEU="0" CRUDE="0" GAS="0"/>
    <VOYAGE LOCODE="BR002" DEPARTURE="2017-06-10 15:20:10 UTC" LASTPORT="Santos Anchorage" LASTCOUNTRY="Brazil"/>
  </VESSEL>
  <VESSEL>
    <AIS MMSI="271001057" TIMESTAMP="2017-08-16 13:09:40 UTC" LATITUDE="43.08535" LONGITUDE="27.95031" COURSE="166.0" SPEED="0.2" HEADING="54" NAVSTAT="1" IMO="9126742" NAME="ROZA A" CALLSIGN="TCRB7" TYPE="71" A="138" B="30" C="10" D="10" DRAUGHT="7.5" DESTINATION="BGVAR" LOCODE="BGVAR" ETA_AIS="08-16 15:00" ETA="2017-08-16 15:00:00" SRC="TER" ZONE="Black Sea" ECA="false"/>
    <MASTERDATA IMO="9126742" NAME="ROZA A" FLAG="TR" TYPE="Container Ship" BUILT="1997" BUILDER="CHINA SB CORP" OWNER="LIMAR LIMAN" MANAGER="ARKAS DENIZCILIK VE NAKLIYAT" CLASS="AMERICAN BUREAU OF SHIPPING" LENGTH="168.8" BEAM="27.3" MAXDRAUGHT="13.5" GT="15120" NT="6764" DWT="19325" TEU="1439" CRUDE="0" GAS="0"/>
    <VOYAGE LOCODE="TRAMB" DEPARTURE="2017-08-15 12:05:56 UTC" LASTPORT="Ambarli" LASTCOUNTRY="Turkey"/>
  </VESSEL>
</VESSELS>