PortCalls

Description

The PortCalls method returns arrival and departure events for a port, a vessel or a fleet of vessels. The AIS dataset is available for all events and the Voyage dataset only for arrivals at a selected port.

Dataset	Content	Credits
PortCall	Port, country, date/time and type of the event (arrival/departure)	2
AIS	Coordinates, course, speed, heading, current draught, destination, ETA and static vessel data	1
Voyage	Last port/country and time of departure	1

URL format

https://api.vesselfinder.com/portcalls?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: `ais`, `voyage` or both: `ais,voyage`
`limit`	no	integer	-	Maximum number of returned records
`interval`	yes***	integer	-	The maximum age of the returned events (in minutes)
`event`	no	text	-	Filter data by event type. Possible values are `arrival` or `departure`
`fromdate`	no	datetime	-	Start of the period, UTC (YYYY-MM-DD HH:MM:SS)
`todate`	no	datetime	-	End of the period, UTC (YYYY-MM-DD HH:MM:SS)
`imo`	yes*	list of integers	-	List of IMO numbers (comma separated)
`mmsi`	yes*	list of integers	-	List of MMSI numbers (comma separated)
`locode`	yes*	text	-	UN/LOCODE of the port
`anchorage`	no	integer	1	`0` = exclude anchorages; `1` = include anchorages; `2` = anchorages only
`imo_only`	no	integer	0	Specifies whether to include port call events only for vessels that have an IMO number: `0` = all vessels; `1` = only vessels with an IMO number
`last_id`	no**	integer	-	Returns only port call events with an ID greater than the specified value

(*) You must provide at least one IMO number, MMSI number, or port UN/LOCODE. You may use multiple IMO and MMSI numbers together. If locode is given, imo and mmsi are ignored and all events at the port are returned (and charged).
(**) When used, this parameter overrides the fromdate and todate filters.
(***) Not required when fromdate / todate or last_id is used.

Code examples

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

import requests

resp = requests.get(
    "https://api.vesselfinder.com/portcalls",
    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:
    pc = vessel["PORTCALL"]
    print(pc["EVENT"], pc["PORT"], pc["TIMESTAMP"], pc["MMSI"])

<?php
$query = http_build_query([
    'userkey'  => 'YOUR_API_KEY',
    'interval' => '1440',
    'locode'   => 'BGVAR',
]);
$data = json_decode(file_get_contents("https://api.vesselfinder.com/portcalls?$query"), true);
if (isset($data['error'])) {
    throw new Exception($data['error']);
}

foreach ($data as $vessel) {
    $pc = $vessel['PORTCALL'];
    echo "{$pc['EVENT']} {$pc['PORT']} {$pc['TIMESTAMP']} {$pc['MMSI']}\n";
}

// Node.js 18+ (save as portcalls.mjs)
const params = new URLSearchParams({ userkey: 'YOUR_API_KEY', interval: '1440', locode: 'BGVAR' });
const resp = await fetch(`https://api.vesselfinder.com/portcalls?${params}`);
const data = await resp.json();
if (data.error) throw new Error(data.error);

for (const { PORTCALL: pc } of data) {
  console.log(pc.EVENT, pc.PORT, pc.TIMESTAMP, pc.MMSI);
}

package main

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

type vessel struct {
	PORTCALL struct {
		EVENT     string
		PORT      string
		TIMESTAMP string
		MMSI      int
	}
}

func main() {
	q := url.Values{"userkey": {"YOUR_API_KEY"}, "interval": {"1440"}, "locode": {"BGVAR"}}
	resp, err := http.Get("https://api.vesselfinder.com/portcalls?" + 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.PORTCALL.EVENT, v.PORTCALL.PORT, v.PORTCALL.TIMESTAMP, v.PORTCALL.MMSI)
	}
}

Examples

Port calls for a vessel

GET https://api.vesselfinder.com/portcalls?userkey=YOUR_API_KEY&interval=14400&imo=9175717

[
    {
        "PORTCALL": {
            "MMSI": 304491000,
            "IMO": 9175717,
            "LOCODE": "TRYPO",
            "EVENT": "DEPARTURE",
            "TIMESTAMP": "2017-08-06 15:37:22 UTC",
            "PORT": "Yilport",
            "COUNTRY": "Turkey"
        }
    },
    {
        "PORTCALL": {
            "MMSI": 304491000,
            "IMO": 9175717,
            "LOCODE": "TRAMB",
            "EVENT": "ARRIVAL",
            "TIMESTAMP": "2017-08-06 20:57:34 UTC",
            "PORT": "Ambarli",
            "COUNTRY": "Turkey"
        }
    },
    {
        "PORTCALL": {
            "MMSI": 304491000,
            "IMO": 9175717,
            "LOCODE": "TRAMB",
            "EVENT": "DEPARTURE",
            "TIMESTAMP": "2017-08-07 00:05:59 UTC",
            "PORT": "Ambarli",
            "COUNTRY": "Turkey"
        }
    },
    {
        "PORTCALL": {
            "MMSI": 304491000,
            "IMO": 9175717,
            "LOCODE": "ITGIT",
            "EVENT": "ARRIVAL",
            "TIMESTAMP": "2017-08-12 02:57:05 UTC",
            "PORT": "Gioia Tauro",
            "COUNTRY": "Italy"
        }
    },
    {
        "PORTCALL": {
            "MMSI": 304491000,
            "IMO": 9175717,
            "LOCODE": "ITGIT",
            "EVENT": "DEPARTURE",
            "TIMESTAMP": "2017-08-12 14:06:31 UTC",
            "PORT": "Gioia Tauro",
            "COUNTRY": "Italy"
        }
    }
]

<VESSELS>
  <VESSEL>
    <PORTCALL MMSI="304491000" IMO="9175717" LOCODE="TRYPO" EVENT="DEPARTURE" TIMESTAMP="2017-08-06 15:37:22 UTC" PORT="Yilport" COUNTRY="Turkey"/>
  </VESSEL>
  <VESSEL>
    <PORTCALL MMSI="304491000" IMO="9175717" LOCODE="TRAMB" EVENT="ARRIVAL" TIMESTAMP="2017-08-06 20:57:34 UTC" PORT="Ambarli" COUNTRY="Turkey"/>
  </VESSEL>
  <VESSEL>
    <PORTCALL MMSI="304491000" IMO="9175717" LOCODE="TRAMB" EVENT="DEPARTURE" TIMESTAMP="2017-08-07 00:05:59 UTC" PORT="Ambarli" COUNTRY="Turkey"/>
  </VESSEL>
  <VESSEL>
    <PORTCALL MMSI="304491000" IMO="9175717" LOCODE="ITGIT" EVENT="ARRIVAL" TIMESTAMP="2017-08-12 02:57:05 UTC" PORT="Gioia Tauro" COUNTRY="Italy"/>
  </VESSEL>
  <VESSEL>
    <PORTCALL MMSI="304491000" IMO="9175717" LOCODE="ITGIT" EVENT="DEPARTURE" TIMESTAMP="2017-08-12 14:06:31 UTC" PORT="Gioia Tauro" COUNTRY="Italy"/>
  </VESSEL>
</VESSELS>

Port calls for a vessel with AIS dataset

GET https://api.vesselfinder.com/portcalls?userkey=YOUR_API_KEY&interval=7200&extradata=ais&imo=9175717

[
    {
        "AIS": {
            "MMSI": 304491000,
            "TIMESTAMP": "2017-08-12 02:57:05 UTC",
            "LATITUDE": 38.44518,
            "LONGITUDE": 15.88136,
            "COURSE": 96.7,
            "SPEED": 7.4,
            "HEADING": 91,
            "NAVSTAT": 0,
            "IMO": 9175717,
            "NAME": "MARENO",
            "CALLSIGN": "V2BC5",
            "TYPE": 70,
            "A": 133,
            "B": 20,
            "C": 14,
            "D": 11,
            "DRAUGHT": 8.8,
            "DESTINATION": "GIOIA TAURO",
            "LOCODE": "ITGIT",
            "ETA_AIS": "08-12 03:00",
            "ETA": "2017-08-12 03:00:00",
            "SRC": "TER",
            "ZONE": "Adriatic Sea",
            "ECA": false
        },
        "PORTCALL": {
            "MMSI": 304491000,
            "IMO": 9175717,
            "LOCODE": "ITGIT",
            "EVENT": "ARRIVAL",
            "TIMESTAMP": "2017-08-12 02:57:05 UTC",
            "PORT": "Gioia Tauro",
            "COUNTRY": "Italy"
        }
    },
    {
        "AIS": {
            "MMSI": 304491000,
            "TIMESTAMP": "2017-08-12 14:06:31 UTC",
            "LATITUDE": 38.44421,
            "LONGITUDE": 15.88018,
            "COURSE": 239.6,
            "SPEED": 6.7,
            "HEADING": 240,
            "NAVSTAT": 0,
            "IMO": 9175717,
            "NAME": "MARENO",
            "CALLSIGN": "V2BC5",
            "TYPE": 70,
            "A": 133,
            "B": 20,
            "C": 14,
            "D": 11,
            "DRAUGHT": 9.9,
            "DESTINATION": "TRIESTE",
            "LOCODE": "ITGIT",
            "ETA_AIS": "08-14 15:00",
            "ETA": "2017-08-14 15:00:00",
            "SRC": "TER",
            "ZONE": "Mediterranean Sea",
            "ECA": false
        },
        "PORTCALL": {
            "MMSI": 304491000,
            "IMO": 9175717,
            "LOCODE": "ITGIT",
            "EVENT": "DEPARTURE",
            "TIMESTAMP": "2017-08-12 14:06:31 UTC",
            "PORT": "Gioia Tauro",
            "COUNTRY": "Italy"
        }
    }
]

<VESSELS>
  <VESSEL>
    <AIS MMSI="304491000" TIMESTAMP="2017-08-12 02:57:05 UTC" LATITUDE="38.44518" LONGITUDE="15.88136" COURSE="96.7" SPEED="7.4" HEADING="91" NAVSTAT="0" IMO="9175717" NAME="MARENO" CALLSIGN="V2BC5" TYPE="70" A="133" B="20" C="14" D="11" DRAUGHT="8.8" DESTINATION="GIOIA TAURO" LOCODE="ITGIT" ETA_AIS="08-12 03:00" ETA="2017-08-12 03:00:00" SRC="TER" ZONE="Adriatic Sea" ECA="false"/>
    <PORTCALL MMSI="304491000" IMO="9175717" LOCODE="ITGIT" EVENT="ARRIVAL" TIMESTAMP="2017-08-12 02:57:05 UTC" PORT="Gioia Tauro" COUNTRY="Italy"/>
  </VESSEL>
  <VESSEL>
    <AIS MMSI="304491000" TIMESTAMP="2017-08-12 14:06:31 UTC" LATITUDE="38.44421" LONGITUDE="15.88018" COURSE="239.6" SPEED="6.7" HEADING="240" NAVSTAT="0" IMO="9175717" NAME="MARENO" CALLSIGN="V2BC5" TYPE="70" A="133" B="20" C="14" D="11" DRAUGHT="9.9" DESTINATION="TRIESTE" LOCODE="ITGIT" ETA_AIS="08-14 15:00" ETA="2017-08-14 15:00:00" SRC="TER" ZONE="Mediterranean Sea" ECA="false"/>
    <PORTCALL MMSI="304491000" IMO="9175717" LOCODE="ITGIT" EVENT="DEPARTURE" TIMESTAMP="2017-08-12 14:06:31 UTC" PORT="Gioia Tauro" COUNTRY="Italy"/>
  </VESSEL>
</VESSELS>

Port calls for a vessel in a date range

GET https://api.vesselfinder.com/portcalls?userkey=YOUR_API_KEY&fromdate=2017-08-06%2000:00:00&todate=2017-08-07%2023:59:59&limit=2&imo=9175717

[
    {
        "PORTCALL": {
            "MMSI": 304491000,
            "IMO": 9175717,
            "LOCODE": "TRAMB",
            "EVENT": "DEPARTURE",
            "TIMESTAMP": "2017-08-07 00:05:59 UTC",
            "PORT": "Ambarli",
            "COUNTRY": "Turkey"
        }
    },
    {
        "PORTCALL": {
            "MMSI": 304491000,
            "IMO": 9175717,
            "LOCODE": "TRAMB",
            "EVENT": "ARRIVAL",
            "TIMESTAMP": "2017-08-06 20:57:34 UTC",
            "PORT": "Ambarli",
            "COUNTRY": "Turkey"
        }
    }
]

<VESSELS>
  <VESSEL>
    <PORTCALL MMSI="304491000" IMO="9175717" LOCODE="TRAMB" EVENT="DEPARTURE" TIMESTAMP="2017-08-07 00:05:59 UTC" PORT="Ambarli" COUNTRY="Turkey"/>
  </VESSEL>
  <VESSEL>
    <PORTCALL MMSI="304491000" IMO="9175717" LOCODE="TRAMB" EVENT="ARRIVAL" TIMESTAMP="2017-08-06 20:57:34 UTC" PORT="Ambarli" COUNTRY="Turkey"/>
  </VESSEL>
</VESSELS>

Port calls for a port

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

[
    {
        "PORTCALL": {
            "MMSI": 636013076,
            "IMO": 9419084,
            "LOCODE": "BGVAR",
            "EVENT": "DEPARTURE",
            "TIMESTAMP": "2017-08-17 12:09:44 UTC",
            "PORT": "Varna",
            "COUNTRY": "Bulgaria"
        }
    },
    {
        "PORTCALL": {
            "MMSI": 271000086,
            "IMO": 7726213,
            "LOCODE": "BGVAR",
            "EVENT": "DEPARTURE",
            "TIMESTAMP": "2017-08-17 12:41:52 UTC",
            "PORT": "Varna",
            "COUNTRY": "Bulgaria"
        }
    },
    {
        "PORTCALL": {
            "MMSI": 457303000,
            "IMO": 8107000,
            "LOCODE": "BGVAR",
            "EVENT": "ARRIVAL",
            "TIMESTAMP": "2017-08-17 12:51:16 UTC",
            "PORT": "Varna",
            "COUNTRY": "Bulgaria"
        }
    }
]

<VESSELS>
  <VESSEL>
    <PORTCALL MMSI="636013076" IMO="9419084" LOCODE="BGVAR" EVENT="DEPARTURE" TIMESTAMP="2017-08-17 12:09:44 UTC" PORT="Varna" COUNTRY="Bulgaria"/>
  </VESSEL>
  <VESSEL>
    <PORTCALL MMSI="271000086" IMO="7726213" LOCODE="BGVAR" EVENT="DEPARTURE" TIMESTAMP="2017-08-17 12:41:52 UTC" PORT="Varna" COUNTRY="Bulgaria"/>
  </VESSEL>
  <VESSEL>
    <PORTCALL MMSI="457303000" IMO="8107000" LOCODE="BGVAR" EVENT="ARRIVAL" TIMESTAMP="2017-08-17 12:51:16 UTC" PORT="Varna" COUNTRY="Bulgaria"/>
  </VESSEL>
</VESSELS>

Arrivals at a port with Voyage dataset

GET https://api.vesselfinder.com/portcalls?userkey=YOUR_API_KEY&interval=720&extradata=voyage&locode=BGVAR

[
    {
        "PORTCALL": {
            "MMSI": 207401000,
            "IMO": 0,
            "LOCODE": "BGVAR",
            "EVENT": "ARRIVAL",
            "TIMESTAMP": "2017-08-18 02:40:32 UTC",
            "PORT": "Varna",
            "COUNTRY": "Bulgaria"
        },
        "VOYAGE": {
            "LOCODE": "BGBAL",
            "DEPARTURE": "2017-08-18 00:24:40 UTC",
            "LASTPORT": "Balchik",
            "LASTCOUNTRY": "Bulgaria"
        }
    }
]

<VESSELS>
  <VESSEL>
    <PORTCALL MMSI="207401000" IMO="0" LOCODE="BGVAR" EVENT="ARRIVAL" TIMESTAMP="2017-08-18 02:40:32 UTC" PORT="Varna" COUNTRY="Bulgaria"/>
    <VOYAGE LOCODE="BGBAL" DEPARTURE="2017-08-18 00:24:40 UTC" LASTPORT="Balchik" LASTCOUNTRY="Bulgaria"/>
  </VESSEL>
</VESSELS>