Port Events API

Track vessel arrivals and departures at ports worldwide. The port events API provides near-real-time data on ship movements, with events collected every 1 minute. Short-term historical data is also available.

What are Port Events?

Port events represent the movement of vessels into and out of ports. Every time a ship arrives at or departs from a port, the system automatically detects and records the event based on AIS position data and port boundaries. This produces a log of port call events useful for logistics tracking, traffic analysis, and operational planning.

The port event detection system monitors vessel positions against defined port areas, automatically generating arrival events when vessels enter port waters and departure events when they leave. Events include timestamps, vessel information, and port details, providing structured data on port-level shipping activity.

Subscription Note: Port Events endpoints are available on all plans. View pricing for details.

Use Cases

Supply Chain Visibility

Know when your cargo arrives at destination ports. Poll for arrival events to trigger downstream logistics processes.

Port Performance Analytics

Analyze port traffic patterns, dwell times, and throughput. Compare port efficiency and identify congestion trends.

Trade Flow Analysis

Track commodity movements between ports. Understand trade routes and identify new market opportunities.

Vessel Monitoring

Build complete port call histories for vessels. Monitor fleet utilization and voyage patterns over time.

Event Types

ARRIVAL

Port Arrival

Detect when vessels arrive at a port, with events recorded at 1-minute intervals. Includes the timestamp of entry, vessel details, and the port identifier.

DEPARTURE

Port Departure

Generated when a vessel exits the port area. Marks the end of a port call. The time between arrival and departure gives you the total time in port.

Understanding UN/LOCODE

Ports are identified using the UN/LOCODE (United Nations Code for Trade and Transport Locations) system. This is a standardized five-character code that uniquely identifies ports and other transport locations worldwide.

UN/LOCODE Format

The code consists of two parts: a 2-letter country code (ISO 3166-1) followed by a 3-character location code.

NLRTM

Rotterdam, Netherlands

SGSIN

Singapore

CNSHA

Shanghai, China

USNYC

New York, USA

Tip: Use the Ports API to search for UN/LOCODE values by port name or location.

Available Endpoints

GET /portevents

Get All Port Events

Retrieve port events within a specified time range. Returns both arrivals and departures across all ports.

Parameters:

  • time.from - Start of time range in RFC3339 format (optional, defaults to 24 hours ago)
  • time.to - End of time range in RFC3339 format (optional, defaults to current time)
  • filter.country - Filter by port country (case-insensitive)
  • filter.unlocode - Filter by port UN/LOCODE
  • filter.eventType - Filter by event type: arrival, departure, or all
  • filter.vesselName - Filter by vessel name (full-text search)
  • filter.portName - Filter by port name (full-text search)
  • pagination.limit - Results per page (max 50, default 20)
  • pagination.nextToken - Cursor for next page of results

At least one filter or time parameter is required.

GET /portevents/port/{unlocode}

Get Events by Port

Retrieve all port events for a specific port using its UN/LOCODE. Ideal for monitoring traffic at a particular port of interest.

Parameters:

  • unlocode - Port UN/LOCODE (e.g., NLRTM) (required)
  • pagination.limit - Results per page (max 50, default 20)
  • pagination.nextToken - Cursor for next page of results
GET /portevents/ports

Search Events by Port Name

Search for port events by port name when you don't know the UN/LOCODE. Supports partial name matching.

Parameters:

  • filter.portName - Port name to search (required)
  • pagination.limit - Results per page (max 50, default 20)
  • pagination.nextToken - Cursor for next page of results
GET /portevents/vessel/{id}

Get Vessel Port History

Retrieve available port call history for a specific vessel within the data retention window. Build voyage itineraries and analyze vessel trading patterns.

Parameters:

  • id - Vessel MMSI or IMO number (required)
  • filter.idType - Identifier type: mmsi or imo (required)
  • filter.eventType - Filter by arrival, departure, or all (default: all)
  • filter.sortOrder - Sort by time: asc or desc (default: desc)
  • time.from / time.to - Time range filter in RFC3339 format (optional)
  • pagination.limit - Results per page (max 50, default 20)
  • pagination.nextToken - Cursor for next page of results
GET /portevents/vessel/{id}/last

Get Last Port Event

Quickly retrieve the most recent port event for a vessel. Useful for determining a vessel's current status - whether it's in port or at sea.

Parameters:

  • id - Vessel MMSI or IMO number (required)
  • filter.idType - Identifier type: mmsi or imo (required)
GET /portevents/vessels

Search Events by Vessel Name

Search for port events by vessel name. Useful when you know the ship's name but not its MMSI or IMO number.

Parameters:

  • filter.vesselName - Vessel name to search (required)
  • pagination.limit - Results per page (max 50, default 20)
  • pagination.nextToken - Cursor for next page of results

Code Examples

Get Port Events at Rotterdam (cURL)

curl -X GET "https://api.vesselapi.com/v1/portevents/port/NLRTM" \
     -H "Authorization: Bearer YOUR_API_KEY"

Get Vessel Port History (Python)

import requests
from datetime import datetime, timedelta

mmsi = "253041000"
now = datetime.utcnow()
one_month_ago = now - timedelta(days=30)

response = requests.get(
    f"https://api.vesselapi.com/v1/portevents/vessel/{mmsi}",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={
        "filter.idType": "mmsi",
        "filter.eventType": "all",
        "time.from": one_month_ago.strftime("%Y-%m-%dT%H:%M:%SZ"),
        "time.to": now.strftime("%Y-%m-%dT%H:%M:%SZ")
    }
)

events = response.json()
for event in events["portEvents"]:
    print(f"{event['event']}: {event['port']['name']} at {event['timestamp']}")

Check If Vessel Is In Port (JavaScript)

async function isVesselInPort(vesselId) {
  const response = await fetch(
    `https://api.vesselapi.com/v1/portevents/vessel/${vesselId}/last?` +
    new URLSearchParams({ "filter.idType": "mmsi" }),
    { headers: { "Authorization": "Bearer YOUR_API_KEY" } }
  );

  const data = await response.json();
  const lastEvent = data.portEvent;

  if (lastEvent.event === "Arrival") {
    console.log(`Vessel is in port: ${lastEvent.port.name}`);
    return true;
  } else {
    console.log(`Vessel departed from: ${lastEvent.port.name}`);
    return false;
  }
}

Response Fields

Field Description
event "Arrival" or "Departure"
timestamp UTC timestamp of the event
port.unlo_code UN/LOCODE of the port
port.name Port name
port.country Country of the port
vessel.mmsi Vessel's MMSI number
vessel.name Vessel name
vessel.imo Vessel's IMO number (if available)

Ready to Track Port Activity?

Try these endpoints interactively in the API Explorer, or sign up for a plan to access port events data.

Open API Explorer View Pricing

Related Documentation

Vessel Tracking

Get real-time vessel positions and details.

Ports

Search ports and find UN/LOCODE values.