API to Track a Heavy Lift Vessel

API to Track a Heavy Lift Vessel

You need a reliable way to track a heavy lift vessel carrying project cargo so you can predict ETAs, prepare cranes and berth windows, and keep stakeholders aligned. By the end of this guide, you’ll be able to integrate vessels-api.com to search for a heavy lift vessel, stream its live AIS track and recent route, batch-monitor multiple ships in a fleet, analyze voyage performance, and factor in port congestion signals—all with consistent JSON and one API key.

What makes heavy lift tracking different—and how the API helps

Heavy lift vessels operate on tight windows: crane bookings, weather windows, and convoy permissions. Slippage is costly. You need accurate positions, recent route context, predicted ETAs, and port-side signals. Vessels API provides:

Illustration: API to Track a Heavy Lift Vessel
  • 18 REST endpoints covering vessel search, live tracking, fleet operations, port intelligence, ESG/IMO CII, and a premium real-time AIS feed.
  • One X-API-Key for all endpoints; same base URL: https://vessels-api.com/api/V1
  • Consistent JSON envelope on every response: {status, success, message, data}
  • Global AIS coverage with near real-time refresh rates
  • 7-day free trial on all plans and scalability from indie to enterprise (details in docs)

Target users include developers, logistics startups, fleet managers, port operators, and ESG/compliance teams. This article focuses on endpoints and patterns that ship your heavy lift use case quickly.

Base URL, authentication, and response envelope

All endpoints live under https://vessels-api.com/api/V1. Send your API key in the X-API-Key header. All responses include the same envelope: {status, success, message, data}, and timestamps are UTC (ISO 8601). Units to note:

  • Speed: knots
  • Distance: nautical miles (nm)
  • Radius: nautical miles (nearby endpoint)
  • CII emissions: tons CO2 and CO2 per nm

Endpoints you’ll actually use for heavy lift

In practice, you’ll rely on these 3–5 endpoints to build a reliable transportation stack for heavy lift operations:

  • GET /vessels/search — Discover or validate a heavy lift vessel by name, IMO, or MMSI with filters.
  • GET /vessels/track — Live position, up to 168h history, current route, predicted ETA, and last port calls.
  • POST /vessels/fleet — Batch positions and routes for multiple vessels in a single call.
  • GET /vessels/analytics — Voyage statistics over rolling windows; useful for schedule performance views.
  • GET /ports/congestion — Real-time congestion and wait-time statistics to de-risk port calls.

Quickstart: Track a known heavy lift vessel by MMSI

When you know the MMSI, the live track endpoint is the shortest path to value. The API returns the current position, recent route context, and last port visits—all with one call. Below is the official sample you can copy and run.

cURL (official sample)

curl -H "X-API-Key: YOUR_API_KEY" "https://vessels-api.com/api/V1/vessels/track?mmsi=258785000&hours=48"

JSON (official sample)

{
"status": 200,
"success": true,
"message": "OK",
"data": {
"vessel": {
"imo": "9122556",
"mmsi": "258785000",
"name": null
},
"current_position": {
"latitude": 53.33708,
"longitude": 7.17993,
"speed_knots": 0,
"course_degrees": 212,
"heading_degrees": null,
"navigational_status": 5,
"timestamp_utc": "2017-01-24T04:07:04+00:00",
"age_minutes": 5113281,
"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": "2026-04-30T09:00:00+00:00",
"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
}
}

What to use immediately:

  • data.vessel: Validate you’re tracking the right ship by MMSI/IMO.
  • data.current_position: Use latitude/longitude for plotting; use speed_knots and course_degrees for operational state; timestamp_utc is the AIS time in UTC.
  • data.route: departure_port, destination_port, and eta are your logistics heartbeat; avg_speed_knots is helpful for ETA sanity checks.
  • data.last_port_visits: Build a recent-call context for gate, crane, and pilotage planning.

Tips:

  • hours supports up to 168 (7 days). Omit to default to 24 hours of history.
  • Use include_route, include_predicted_eta, include_weather flags when you need extra context and want to control payload size.

Find a heavy lift vessel by name, IMO, MMSI, and filters

When you don’t have identifiers on hand, search with fuzzy name matching and filters to scope to heavy lift vessels. Common filters include ship_type, flag, deadweight, TEU, and year built windows. Pagination is supported with page and per_page (max 100).

Python example: search for a heavy lift vessel

import os
import requests

BASE_URL = "https://vessels-api.com/api/V1"
API_KEY = os.getenv("VESSELS_API_KEY", "YOUR_API_KEY")

def search_heavy_lift(query, flag=None, min_dwt=None, max_dwt=None, page=1, per_page=50):
params = {
"query": query,
"ship_type": "Heavy Lift",
"page": page,
"per_page": per_page
}
if flag:
params["flag"] = flag
if min_dwt:
params["min_dwt"] = min_dwt
if max_dwt:
params["max_dwt"] = max_dwt

r = requests.get(f"{BASE_URL}/vessels/search", headers={"X-API-Key": API_KEY}, params=params, timeout=20)
r.raise_for_status()
payload = r.json()
if not payload.get("success"):
raise RuntimeError(payload.get("message"))
vessels = payload["data"]["vessels"]
# Pick the top match and return key identifiers for subsequent tracking
if vessels:
top = vessels[0]
return {"imo": top.get("imo"), "mmsi": top.get("mmsi"), "name": top.get("name"), "flag": top.get("flag")}
return None

candidate = search_heavy_lift("Jumbo", flag="Netherlands")
print(candidate)

This code filters by ship_type=Heavy Lift and optionally by flag and DWT. Use the returned IMO/MMSI to call /vessels/track next.

Batch-monitor multiple heavy lift vessels (fleet view)

For project cargo, you often track a convoy: the heavy lift ship, a tug, and possibly an escort. The fleet endpoint lets you fetch positions and route snapshots for several vessels in one POST call, reducing request overhead and simplifying state management.

JavaScript example: fleet snapshot for dashboards

const fetch = require("node-fetch");

const BASE_URL = "https://vessels-api.com/api/V1";
const API_KEY = process.env.VESSELS_API_KEY || "YOUR_API_KEY";

async function getFleetSnapshot(vessels) {
const body = {
vessels, // e.g., [{ imo: "9122556" }, { mmsi: "258785000" }]
include_positions: true,
include_routes: true
};

const res = await fetch(`${BASE_URL}/vessels/fleet`, {
method: "POST",
headers: {
"X-API-Key": API_KEY,
"Content-Type": "application/json"
},
body: JSON.stringify(body),
});

if (!res.ok) {
const text = await res.text();
throw new Error(`Fleet request failed: ${res.status} ${text}`);
}

const payload = await res.json();
if (!payload.success) {
throw new Error(payload.message);
}

const fleetStats = payload.data.fleet; // { total_vessels, vessels_at_sea, vessels_in_port }
const items = payload.data.vessels.map(v => ({
name: v.name,
imo: v.imo,
mmsi: v.mmsi,
lat: v.position?.latitude,
lon: v.position?.longitude,
speed: v.position?.speed_knots,
dest: v.route?.destination_port,
eta: v.route?.eta
}));

return { fleetStats, items };
}

getFleetSnapshot([{ imo: "9122556" }, { mmsi: "258785000" }])
.then(console.log)
.catch(console.error);

Use the returned fleet summary to power a header widget, while the per-vessel objects feed a map and an ETA table. Because you can include routes, your dashboard can show planned destinations and ETAs without extra calls.

Voyage analytics for schedule adherence and port-call planning

Heavy lift voyages often use dynamic schedules. The analytics endpoint aggregates distance sailed, average and maximum speeds, and port-call counts over configurable periods. This enables:

  • Schedule adherence: compare avg_speed_knots to planned convoy speed.
  • Cycle times: monitor total_time_in_port_hours to spot delays in crane ops.
  • Performance baselines: over 7d/30d/90d windows to inform operational planning.

Python example: pull 7-day vessel analytics

import os
import requests

BASE_URL = "https://vessels-api.com/api/V1"
API_KEY = os.getenv("VESSELS_API_KEY", "YOUR_API_KEY")

def vessel_last_7d(mmsi):
params = {"type": "vessel", "mmsi": mmsi, "period": "7d"}
r = requests.get(f"{BASE_URL}/vessels/analytics", headers={"X-API-Key": API_KEY}, params=params, timeout=20)
r.raise_for_status()
data = r.json()["data"]
stats = data["statistics"]
return {
"mmsi": data.get("mmsi"),
"period": data.get("period"),
"distance_nm": stats.get("total_distance_nm"),
"avg_speed_knots": stats.get("avg_speed_knots"),
"max_speed_knots": stats.get("max_speed_knots"),
"port_calls": stats.get("port_calls_count"),
"time_in_port_hours": stats.get("total_time_in_port_hours")
}

print(vessel_last_7d("258785000"))

Combine this with /vessels/track to show “live now” context next to historical performance trends (e.g., sparkline of avg_speed_knots week over week).

Bring port-side reality into the plan: congestion signals

For heavy lift cargoes that require precise crane slots and pilotage, a few hours of port congestion can ripple through a multi-week schedule. Use /ports/congestion to understand anchorage vs. berth counts and wait-time statistics for a specified period.

Key details:

  • Required parameter: port_id (a UNLOCODE from the title parentheses in the endpoint docs, e.g., ARBUE for Buenos Aires).
  • Optional parameter: period=24h|3d|7d depending on how you summarize wait times for planners.
  • Response includes snapshot and statistics sections suitable for dashboard widgets.

Pair congestion insights with the vessel’s route. If route.eta is tight and the destination port shows elevated avg_wait_time_hours_last_7d, alert operations to move the crane slot or adjust tide windows.

Build an end-to-end heavy lift workflow

Putting it together for a transportation stack that serves planners, port ops, and customers:

  1. Discovery: Use GET /vessels/search with ship_type=Heavy Lift to identify the right vessel and capture IMO/MMSI.
  2. Live tracking: Use GET /vessels/track with hours=48–168 to render a map, show current_position and route. Plot last_port_visits as context.
  3. Fleet view: Use POST /vessels/fleet for convoy or multi-vessel dashboards with positions and ETAs in one call.
  4. Performance: Use GET /vessels/analytics to display total_distance_nm, avg_speed_knots, port_calls_count, and total_time_in_port_hours.
  5. Port ops: Use GET /ports/congestion for the target port to estimate likelihood of delay vs. planned crane window.

Operational tips that save time

  • Polling cadence: For near real-time maps, 30–120 second polling is typical. Back off when current_position.age_minutes is high to avoid hammering when data is stale.
  • Cache by vessel: Cache /vessels/track responses per MMSI/IMO keyed by hours + include flags. Invalidate on position timestamp changes.
  • Pagination: /vessels/search supports page and per_page (max 100). Persist pagination state in your UI to avoid inconsistent result sets on refresh.
  • Error handling: Check the envelope fields. status 401 indicates a missing or invalid X-API-Key; 404 means vessel/port not found; 422 indicates an out-of-range parameter (e.g., radius too large); 429 signals rate limiting.
  • Units and coordinate sanity: All lat/lon are WGS84 decimal degrees; speed in knots; distances in nm; timestamps are ISO 8601 in UTC. Normalize to your UI’s timezone on render, never in storage.

ESG and compliance for heavy lift portfolios

If you manage a portfolio of heavy lift tonnage, the GET /vessels/green endpoint exposes IMO CII scoring per vessel over configurable windows (24h, 7d, 30d, 1y). Use it to:

  • Report current CII banding (A to E) for compliance stakeholders.
  • Alert when a vessel trends toward D/E ratings during a campaign.
  • Track estimated_emissions.co2_tons and co2_per_nm to benchmark routes.

You can periodically fetch /vessels/green alongside your fleet call and store the score and rating with a timestamp for ESG dashboards.

Security, simplicity, and integration ergonomics

All endpoints share a single auth mechanism via X-API-Key. There is no per-endpoint auth difference or OAuth dance. This keeps server-side integrations simple and secure—inject the key via secret management and pass-through from your backend only (avoid exposing the key to browsers or mobile apps directly).

Because every endpoint returns the same envelope, your client code can centralize validation and error parsing:

  • Check HTTP status; parse JSON; assert success == true.
  • If success is false, surface message to logs and your notification bus.
  • Always read data.* only after verifying success.

End-to-end sample: from search to live map and ETA

Below is a compact Python flow you can adapt to your API server to power a project-cargo map view for a single heavy lift vessel:

import os
import requests

BASE_URL = "https://vessels-api.com/api/V1"
API_KEY = os.getenv("VESSELS_API_KEY", "YOUR_API_KEY")

def api_get(path, params=None):
r = requests.get(f"{BASE_URL}{path}", headers={"X-API-Key": API_KEY}, params=params, timeout=20)
r.raise_for_status()
payload = r.json()
if not payload.get("success"):
raise RuntimeError(payload.get("message"))
return payload["data"]

def find_candidate(name_query):
# Constrain to heavy lift to avoid false positives
data = api_get("/vessels/search", {
"query": name_query,
"ship_type": "Heavy Lift",
"per_page": 10
})
vessels = data.get("vessels", [])
return vessels[0] if vessels else None

def live_track(mmsi):
data = api_get("/vessels/track", {
"mmsi": mmsi,
"hours": 48,
"include_route": "true",
"include_predicted_eta": "true"
})
return {
"now": data["current_position"],
"route": data.get("route"),
"predicted_eta": data.get("predicted_eta"),
"last_ports": data.get("last_port_visits", [])
}

candidate = find_candidate("Jumbo")
if candidate:
track = live_track(candidate["mmsi"])
print({
"lat": track["now"]["latitude"],
"lon": track["now"]["longitude"],
"speed_knots": track["now"]["speed_knots"],
"destination": track["now"]["destination"] or (track["route"]["destination_port"] if track["route"] else None),
"eta": track["now"]["eta"] or track.get("predicted_eta")
})

Use this pattern to build an HTTP endpoint from your server that your frontend map can call on a 60–90 second cadence.

Common pitfalls and how to avoid them

  • Mixing identifiers: Don’t send both IMO and MMSI in the same query unless the endpoint allows it. Choose one and be consistent.
  • Assuming destination is always set: destination in current_position can be null. Fall back to route.destination_port if present.
  • Over-polling for stale positions: If age_minutes is large, reduce polling or switch to a lower frequency to save bandwidth.
  • Ignoring port-side signals: For tight crane bookings, monitor /ports/congestion alongside the vessel ETA for the final leg.

Where to go next

  • Register to get your API key and start a 7‑day trial.
  • Read the Documentation for every endpoint, parameter, and error code.
  • Explore the MCP for real-time maritime control plane integrations.

FAQ

Which identifier should I use for tracking—IMO or MMSI?
Use whichever you have available. MMSI is typically best for AIS position lookups; IMO is stable across MMSI changes. The /vessels/search endpoint returns both, so you can normalize.

How often does AIS data refresh?
The API provides global AIS coverage with near real-time refresh rates. Poll smartly (e.g., every 60–120 seconds) and consider backing off when age_minutes is high.

Can I track multiple heavy lift vessels in one request?
Yes. Use POST /vessels/fleet with a list of IMO/MMSI objects and set include_positions/include_routes as needed.

How do I estimate ETA reliability?
Combine current_position.speed_knots with route.avg_speed_knots. If available, use predicted_eta and compare to destination port congestion stats to flag risks.

How do I report emissions or CII for heavy lift vessels?
Use GET /vessels/green to pull distance_nm, estimated_emissions, and the CII score and rating over a chosen period.

If you’re building transportation tooling for heavy lift cargoes—dashboards, ETA pipelines, or port-side planning—wire up the endpoints above and ship value quickly. Get started now with your API key: Register, explore the Documentation, and integrate with the MCP when you’re ready for production workflows.

Keywords
API development heavy lift vessel tracking project cargo management live AIS tracking vessel integration API

Ready to get started?

Get your API key and start tracking vessels in minutes.

Get API Key

Related posts