If your job is to answer “Is there a cruise ship near this port right now, and when will it berth?” you need live AIS positions, short-range proximity search, and reliable port intelligence you can wire into your dashboard. By the end of this post, you’ll be able to programmatically detect cruise ships in the vicinity of a port, pull their live track and ETA, and surface expected arrivals using vessels-api.com — all with one API key and consistent JSON responses.
What you can build: cruise-ops proximity and ETA in one API
vessels-api.com provides 18 REST endpoints covering vessel search, live AIS tracking, fleet operations, port intelligence, IMO CII emissions scoring, and a premium real-time AIS feed. Integration is straightforward:
- Base URL: https://vessels-api.com/api/V1
- Authentication: X-API-Key header on every request
- Consistent response envelope: {status, success, message, data}
- Global AIS coverage with near real-time refresh rates
- 7-day free trial on all plans and scalable for indie devs to enterprise fleets
In this guide we’ll focus on endpoints that matter for cruise ships near ports:
- /vessels/nearby — find vessels within a radius of a port coordinate, filtered to passenger/cruise types
- /vessels/track — get a ship’s current position, recent history, route, and last port visits
- /ports/data — fetch authoritative port coordinates and live counts for vessels in port
- /port/expected-arrivals — list inbound vessels with ETA and origin
- /vessels/analytics — optional stats for time-in-port and port calls over a period
Core workflow: detect “cruise ship near a port”
The fastest pattern is a two-step flow:
- Resolve port coordinates from /ports or /ports/data
- Call /vessels/nearby with those coordinates and ship_type=Passenger
You can then enrich any nearby candidate with /vessels/track for route and ETA, or supplement with /port/expected-arrivals to line up planned calls with live positions.
Step 1: get a port’s coordinates and live counts
Use /ports to browse the catalog of 248 ports, or /ports/data to pull a specific port with live counts and coordinates. The latter is useful when you already know the identifier:
curl -H "X-API-Key: YOUR_API_KEY" "https://vessels-api.com/api/V1/vessels/track?mmsi=258785000&hours=48"
Key fields you’ll use:
- data.latitude, data.longitude — decimal degrees for your proximity query
- data.vessels_in_port, data.vessels_expected — quick sanity checks for your UI
Notes:
- Timestamps across the API are ISO 8601 in UTC (e.g., 2026-04-27T21:35:36+00:00)
- All response bodies adhere to the same envelope: {status, success, message, data}
Step 2: check nearby vessels (filter to cruise/passenger)
With coordinates in hand, query /vessels/nearby. Distances are in nautical miles (NM). Use ship_type to filter to passenger vessels, which includes cruise ships.
Important parameters:
- latitude, longitude — center point for the radius search
- radius — NM; default 50, max 200
- ship_type — filter; for cruise use Passenger
- limit — cap the number of returned vessels (default 50)
Returned vessel objects include MMSI/IMO identifiers, ship_type, a position block with timestamp_utc, distance_nm from the center, and basic motion data (speed_knots, course_degrees). This is sufficient to build a “cruise ships within 20 NM of the port” widget.
Enrich a candidate: live track, route, and last port calls
Once you’ve selected a nearby passenger vessel, gather more context via /vessels/track. This endpoint returns the current position, up to 168 hours of position history, the active route with ETA, and the last port visits.
Official live track sample (MMSI 258785000)
The following cURL and JSON are an official sample and can be used to wire your parsing logic:
{
"status": 200,
"success": true,
"message": "OK",
"data": {
"vessel": {
"imo": "9122556",
"mmsi": "258785000",
"name": null
},
"current_position": {
"latitude": 53.33708,
"longitude": 7.17993,
"position_precision": "precise",
"position_accuracy_nm": null,
"speed_knots": 0,
"course_degrees": 212,
"heading_degrees": null,
"navigational_status": 5,
"timestamp_utc": "2017-01-24T04:07:38+00:00",
"age_minutes": 5159480,
"destination": null,
"eta": null
},
"predicted_eta": null,
"position_history": [],
"route": {
"departure_port": "HERACLIO",
"departure_time": "2026-04-27T21:35:36+00:00",
"destination_port": "HERACLIO",
"eta": null,
"distance_nm": null,
"avg_speed_knots": 17.1
},
"last_port_visits": [
{
"port_id": "156",
"port_name": "EMDEN",
"arrival_time": "2026-07-30T13:00:10+00:00",
"departure_time": null,
"duration_hours": null
},
{
"port_id": "10",
"port_name": "HERACLIO",
"arrival_time": "2026-04-20T12:00:00+00:00",
"departure_time": "2026-04-23T08:00:00+00:00",
"duration_hours": 68
}
],
"weather": null
}
}
How to use these fields:
- data.current_position.latitude/longitude — chart the latest AIS fix
- data.current_position.speed_knots/course_degrees — live motion
- data.current_position.timestamp_utc — always UTC
- data.route.destination_port and data.route.eta — show voyage intent and ETA when available
- data.last_port_visits — context for shore teams and excursion planning
Tip: include hours=48 (default 24, max 168) to control the returned position_history. When building maps, consider caching responses for a short TTL and keying by MMSI plus your chosen hours window.
Expected cruise arrivals: complement AIS with declared ETAs
Live proximity is powerful, but terminals also need declared ETAs for resource planning. Use /port/expected-arrivals to list inbound vessels for a port alongside their origin and ETA.
Returned rows contain mmsi, imo, name, vessel_type, eta, and departure_port. Cross-match by MMSI with your nearby results to reconcile planned calls with live AIS positions and improve your ETA confidence.
Port congestion snapshot: anchorage vs. berth pressure
When a cruise ship nears a port, berthing availability dictates whether it proceeds directly or waits at anchorage. Query /ports/congestion for a real-time snapshot and recent wait-time stats.
Key fields:
- data.snapshot.vessels_in_anchorage and data.snapshot.vessels_at_berth — current load
- data.statistics.* — recent averages and maxima to calibrate buffers around ETA
Use this to condition your “arrival readiness” widgets: if anchorage is crowded and average waits are increasing, surface a warning even when a cruise ship is within a few NM.
Analytics for cruise reporting: time in port and ports visited
To summarize recent cruise activity, /vessels/analytics (type=vessel or port) provides aggregated voyage stats for operational and reporting needs.
Relevant fields include total_time_in_port_hours, port_calls_count, and ports_visited, which help planners and ESG/compliance teams quantify recent calls without stitching raw tracks.
JavaScript example: find cruise ships near a port and enrich with track
The following script resolves a port, queries nearby passenger vessels, and then calls /vessels/track for the first result. Replace YOUR_API_KEY and the port code as needed.
async function fetchJson(url) {
const res = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } });
if (!res.ok) throw new Error(`HTTP ${res.status}`);
return res.json();
}
async function cruiseShipsNearPort(portId) {
// 1) Get port coordinates
const portUrl = `https://vessels-api.com/api/V1/ports/data?port=${encodeURIComponent(portId)}`;
const portResp = await fetchJson(portUrl);
const { latitude, longitude, name } = portResp.data;
// 2) Query nearby passenger vessels within 20 NM
const nearbyUrl = `https://vessels-api.com/api/V1/vessels/nearby?latitude=${latitude}&longitude=${longitude}&radius=20&ship_type=Passenger&limit=20`;
const nearbyResp = await fetchJson(nearbyUrl);
const vessels = nearbyResp.data.vessels;
// 3) Enrich the first vessel with live track and route details
if (vessels.length === 0) {
return { port: name, nearbyCruiseShips: [], enriched: null };
}
const first = vessels[0];
const trackUrl = `https://vessels-api.com/api/V1/vessels/track?mmsi=${encodeURIComponent(first.mmsi)}&hours=48`;
const trackResp = await fetchJson(trackUrl);
return {
port: name,
nearbyCruiseShips: vessels.map(v => ({
mmsi: v.mmsi,
name: v.name,
distance_nm: v.distance_nm,
speed_knots: v.speed_knots,
timestamp_utc: v.position.timestamp_utc
})),
enriched: {
mmsi: trackResp.data.vessel.mmsi,
current_position: trackResp.data.current_position,
route: trackResp.data.route,
last_port_visits: trackResp.data.last_port_visits
}
};
}
// Example usage:
cruiseShipsNearPort("ARBUE")
.then(result => console.log(JSON.stringify(result, null, 2)))
.catch(err => console.error(err));
Notes:
- All endpoints are GET except /vessels/fleet (POST). Here we use only GET endpoints.
- Consider adding a small cache (e.g., 30–60 seconds) around /vessels/nearby for dashboards to reduce flicker and API calls.
Python example: reconcile expected arrivals with nearby cruise ships
This snippet fetches expected arrivals for a port and cross-references them with nearby passenger vessels within 25 NM to surface “on-approach” calls.
import requests
BASE = "https://vessels-api.com/api/V1"
HEADERS = {"X-API-Key": "YOUR_API_KEY"}
def get_port_coords(port_id):
r = requests.get(f"{BASE}/ports/data", params={"port": port_id}, headers=HEADERS, timeout=15)
r.raise_for_status()
d = r.json()["data"]
return d["latitude"], d["longitude"]
def get_nearby_passengers(lat, lon, radius_nm=25):
r = requests.get(f"{BASE}/vessels/nearby", params={
"latitude": lat,
"longitude": lon,
"radius": radius_nm,
"ship_type": "Passenger",
"limit": 100
}, headers=HEADERS, timeout=20)
r.raise_for_status()
return r.json()["data"]["vessels"]
def get_expected_arrivals(port_id):
r = requests.get(f"{BASE}/port/expected-arrivals", params={"port": port_id}, headers=HEADERS, timeout=15)
r.raise_for_status()
return r.json()["data"]["expected_arrivals"]
def join_expected_with_nearby(port_id):
lat, lon = get_port_coords(port_id)
nearby = get_nearby_passengers(lat, lon, 25)
expected = get_expected_arrivals(port_id)
by_mmsi = {v.get("mmsi"): v for v in nearby if v.get("mmsi")}
reconciled = []
for row in expected:
mmsi = row.get("mmsi")
near = by_mmsi.get(mmsi)
reconciled.append({
"mmsi": mmsi,
"imo": row.get("imo"),
"name": row.get("name"),
"eta": row.get("eta"),
"departure_port": row.get("departure_port"),
"nearby_distance_nm": near.get("distance_nm") if near else None,
"nearby_speed_knots": near.get("speed_knots") if near else None
})
return reconciled
if __name__ == "__main__":
result = join_expected_with_nearby("ARBUE")
for r in result:
print(r)
This is a pragmatic way to flag which expected cruise calls are already within approach distance, and how fast they’re moving. For UI, display ETA from expected-arrivals, and use distance_nm/speed_knots from nearby to hint if the ETA is plausible or likely to shift.
Batching cruise fleets (optional)
If you manage a cruise line or a multi-ship terminal, one request to /vessels/fleet returns positions and routes for multiple vessels. Use IMO or MMSI per vessel and opt-in to include positions and/or routes.
The response contains a fleet summary (vessels_at_sea, vessels_in_port) and a list of vessel objects with position and route when requested. This is ideal for control-room displays where you want one paint every polling cycle.
Implementation details that save time
- Authentication: always send X-API-Key: YOUR_API_KEY. There is no OAuth and no per-endpoint auth variance.
- Units: distances in nautical miles (NM), speeds in knots, coordinates in decimal degrees.
- Timestamps: ISO 8601 with UTC offset, e.g., 2026-04-27T21:35:36+00:00.
- Pagination: when browsing large search results via /vessels/search use page and per_page (max 100).
- Errors: 400 invalid parameter, 401 missing/invalid API key, 404 not found, 422 parameter out of range, 429 rate limit exceeded, 500 server error. Always check status/success in the envelope before reading data.
- Data envelope: every response follows {status, success, message, data}, which simplifies client libraries and telemetry logging.
- Caching: for wallboards, a short TTL (e.g., 30–60 seconds for nearby/track) balances freshness and API utilization.
Why this stack works for “cruise ship near a port”
Combining /ports/data for authoritative coordinates, /vessels/nearby with ship_type filtering, and /vessels/track for route context gives you a complete loop: Where is it now, how far is it from the port, what is its likely plan, and when did it last call other ports? Augment with /port/expected-arrivals and, when relevant, /ports/congestion to capture the operational picture that influences berthing and shore-side logistics.
Quick links
FAQ
How do I restrict results to cruise ships only?
Use ship_type=Passenger on /vessels/nearby or /vessels/search. This covers cruise vessels as a subset of passenger types.
What timezone are the timestamps in?
All timestamps are ISO 8601 in UTC (e.g., 2026-04-27T21:35:36+00:00). Normalize your UI accordingly.
Can I get both live AIS context and planned ETAs?
Yes. Use /vessels/track for current_position and route (with ETA when available), and /port/expected-arrivals for declared ETAs. Cross-reference by MMSI or IMO.
What’s the maximum history I can request from /vessels/track?
Use hours up to a maximum of 168 hours (7 days). The default is 24 hours.
How do I handle errors consistently?
Every response includes {status, success, message}. Check success before consuming data. Common codes: 400 for invalid parameters, 401 for missing/invalid API key, 404 when a vessel or port isn’t found, 422 when a parameter is out of range, 429 for rate limits, and 500 for server errors.
Get started
Wire up the two-step proximity flow in your app today: resolve a port, call nearby with ship_type=Passenger, and enrich with track and expected-arrivals. The API surface is small, the envelope is consistent, and the endpoints are designed for production dashboards. Grab your key and ship your “cruise ship near a port” feature: Register, explore the Documentation, and check out the MCP for ecosystem tools.