You need to track a heavy lift vessel (HLV) end-to-end: find it quickly, see live AIS positions, verify route and ETA to a project site, keep a multi-ship dashboard synchronized, and export voyage and emissions metrics for stakeholders. By the end of this guide, you’ll wire up a working integration that searches for a heavy lift vessel, streams its live track with optional history and route, aggregates voyage analytics, and scales to a small HLV fleet — all via a single REST API key and base URL.
Why this approach works for heavy lift vessels
Heavy lift shipments are high-stakes, schedule-constrained, and often berth- or tide-dependent. The difference between a crane mobilization going smoothly and a multi-day delay is timely, precise AIS and port context. With vessels-api.com, you get:
- 18 REST endpoints covering vessel search, live tracking with up to 168 hours of history, fleet operations, port intelligence, and IMO CII emissions scoring.
- One API key, one base URL: no OAuth dance, no per-endpoint auth variants.
- Consistent JSON envelope on every response: {status, success, message, data} — easy to log and parse.
- Near real-time AIS coverage suitable for live dashboards and ETA workflows.
- A 7-day free trial on all plans and a path from indie project to enterprise workflow without code changes.
We’ll focus on five endpoints that matter most to heavy lift teams:
- /vessels/search — locate the right ship (name/IMO/MMSI) with filters.
- /vessels/track — live position, history, active route, predicted ETA, and weather.
- /vessels/analytics — voyage stats for planning and post-op reporting.
- /vessels/fleet — batch positions and routes for multi-ship views.
- /vessels/green — IMO CII emissions insights for ESG and compliance.
Full API reference is in the Documentation, and you can test endpoints interactively via the MCP.
Authentication, base URL, and response envelope
All endpoints share a single base URL and header-based API key:
- Base URL: https://vessels-api.com/api/V1
- Auth header: X-API-Key: YOUR_API_KEY
Every response follows the same envelope: {status, success, message, data}. That means your error handling and logging can be unified across vessel, fleet, and port operations.
Step 1 — Find your heavy lift vessel
Use fuzzy name search or precise identifiers to resolve a vessel quickly. For heavy lift vessels, it’s common to key off IMO in contracts and MMSI in live operations. Use optional filters like ship_type, flag, and build year to narrow down a large result set.
Search by name or code
curl -H "X-API-Key: YOUR_API_KEY" "https://vessels-api.com/api/V1/vessels/track?mmsi=258785000&hours=48"Parameters you’ll actually use in HLV workflows:
- query: vessel name fragment, IMO, or MMSI.
- ship_type: target heavy-lift classes if you maintain a catalog.
- year_built_from/year_built_to: filter for gear capability proxies (newer heavy lifters often have higher SWL cranes).
- per_page: paginate up to 100 per page if searching broadly.
Key fields in each result include imo, mmsi, name, vessel_type, flag, deadweight_tonnage, length_m, width_m — sufficient to confirm you’re tracking the correct HLV for a cargo move or loadout site survey.
Step 2 — Live track the vessel and read its route
The tracking endpoint returns current position, optional history up to 168 hours, and the active voyage route including departure and destination ports, ETA, and average speed. For heavy lift, this is your single source of truth for project cargo ETAs, tug coordination windows, and berth readiness.
Official cURL (48‑hour window)
Official JSON response
{
"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:20+00:00",
"age_minutes": 5153720,
"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
}
}Fields to wire into your heavy lift dashboard:
- current_position.latitude/longitude, speed_knots, course_degrees: render on the map and compute CPA to pilot boarding or tow rendezvous points.
- current_position.timestamp_utc: timestamps are UTC ISO-8601; use this to compute data freshness and update frequency.
- route.departure_port, route.destination_port, route.avg_speed_knots: sanity-check the active voyage; substitute predicted_eta if available.
- last_port_visits: confirm project cargo legs and time in port for post-op reporting.
Tip: request include_route=true and include_predicted_eta=true when you need more detail. You can also extend hours up to 168 for a one-week breadcrumb trail for audits or incident reviews.
Python example: poll and extract key fields
import requests
from datetime import datetime, timezone
API_KEY = "YOUR_API_KEY"
BASE = "https://vessels-api.com/api/V1"
def track_heavy_lift(mmsi="258785000", hours=48):
url = f"{BASE}/vessels/track"
params = {"mmsi": mmsi, "hours": hours}
headers = {"X-API-Key": API_KEY}
r = requests.get(url, headers=headers, params=params, timeout=20)
r.raise_for_status()
payload = r.json()
if not payload.get("success"):
raise RuntimeError(payload.get("message", "API error"))
data = payload["data"]
vessel = data["vessel"]
pos = data["current_position"]
route = data.get("route") or {}
# Normalize outputs
out = {
"imo": vessel.get("imo"),
"mmsi": vessel.get("mmsi"),
"lat": pos.get("latitude"),
"lon": pos.get("longitude"),
"speed_knots": pos.get("speed_knots"),
"course": pos.get("course_degrees"),
"nav_status": pos.get("navigational_status"),
"fix_time_utc": pos.get("timestamp_utc"),
"route_from": route.get("departure_port"),
"route_to": route.get("destination_port"),
"avg_speed_knots": route.get("avg_speed_knots"),
"predicted_eta": data.get("predicted_eta"),
}
return out
if __name__ == "__main__":
info = track_heavy_lift()
print("HLV:", info["imo"], info["mmsi"])
print("Pos:", info["lat"], info["lon"], "@", info["fix_time_utc"])
print("SOG:", info["speed_knots"], "kn COG:", info["course"])
print("Route:", info["route_from"], "→", info["route_to"], "ETA:", info["predicted_eta"] or "n/a")Step 3 — Add voyage analytics for planning and post-op
For heavy lift programs, you’ll want consolidated voyage metrics to estimate crane standby, barge availability, and port call durations. The analytics endpoint aggregates distance, speeds, and port call counts over a given period.
Per-vessel analytics over a rolling window
Key outputs under data.statistics you will use in planning sheets:
- total_distance_nm: helps verify bunker and tow planning assumptions.
- avg_speed_knots, max_speed_knots: calibrate ETA buffers for project cargo safety margins.
- port_calls_count, total_time_in_port_hours: benchmark loading/offloading cycles.
- ports_visited: map recent operating areas for project risk reviews.
Switch type to port or fleet if you need port-centric or fleet-level rollups without stitching datasets yourself.
Step 4 — Track multiple heavy lift vessels in one request
Project cargo timelines often depend on two or more HLVs, plus tugs or barges staged across regions. Use the fleet endpoint to request positions and routes in batch for a clean, low-latency dashboard update.
POST a batch: positions and routes
Design notes for robust fleet views:
- Include IMO or MMSI per record. If both are available, pass both for cross-checking.
- Set include_positions and include_routes to true to avoid multiple round-trips.
- Persist a “stale after” threshold (e.g., 10–30 minutes) using each vessel’s latest timestamp_utc; flag overdue positions in your UI.
Step 5 — Add ESG and compliance context
Many HLV charters now include emissions reporting. You can compute an IMO CII rating over windows from 24 hours to one year using the green endpoint — useful for charter party reporting and internal ESG dashboards.
Get CII scoring over 30 days
The response includes:
- distance_nm and estimated_emissions (co2_tons, co2_per_nm) for the window.
- cii.score and cii.rating (A best → E worst) based on IMO MEPC.339(76).
- year and regulation_reference for audit trails.
Combine this with analytics to contextualize emissions per voyage leg or port call.
Optional — Port-side context for schedule realism
Heavy-lift windows are tight. To anticipate clash risks and tug/crane standby, add port intelligence where your HLV is headed:
- /ports: list and pick the target port by ID and coordinates to render on your map.
- /ports/data: get live vessel counts to understand current traffic pressure.
- /port/expected-arrivals: see who else is inbound with ETA and origin — useful for berth competition estimation.
Expected arrivals example
Use the expected_arrivals array to spot overlapping large tonnage calling the same port window as your HLV, then adjust tow plans or pilot times accordingly.
Implementation tips that save you hours
- Units: distances are nautical miles (nm), speeds are knots. Coordinates are decimal degrees; bearings are degrees (true).
- Timestamps: all timestamps are UTC ISO-8601. Store and compare as UTC to avoid time zone drift in Gantt charts.
- History windows: /vessels/track supports hours up to 168. For always-on dashboards, poll at your UI frequency and store the latest breadcrumb rather than replaying 7 days each time.
- Pagination: search supports page and per_page (max 100). Always capture pagination.total and last_page for user-facing search flows.
- Response envelope: standardize on checking success first; log message on non-200 states. Use status codes: 400/422 for bad params, 401 for missing/invalid key, 404 when a vessel or port isn’t found, 429 when you’ve hit rate limits, 500 for server errors.
- Resilience: for fleet polling, favor POST /vessels/fleet over n single calls. Back off on 429 with exponential retry and preserve last good positions to keep the map stable.
- Data freshness: consult current_position.timestamp_utc and any age_minutes fields to annotate stale AIS fixes in the UI.
End-to-end example workflow for a project cargo move
- Search and resolve the heavy lift vessel using /vessels/search with a name or IMO from your charter party.
- Start a polling loop on /vessels/track with hours=48 to maintain a rolling window, and render the HLV on your map with current SOG/COG.
- Query /vessels/analytics with type=vessel and period=7d to calibrate ETA buffers and crane standby windows based on real average speeds and port time behavior.
- If you are coordinating multiple HLVs and assist tugs, batch them in /vessels/fleet with include_positions and include_routes to update a single dashboard tick.
- Use /vessels/green over 30d or 1y windows to export CII summaries into your ESG reporting package.
Frequently asked questions
How often should I poll /vessels/track for an HLV?
Base it on your UI and stakeholder needs. Many dashboards poll every 1–5 minutes and annotate the last fix timestamp_utc. For lower-bandwidth contexts, poll every 10–15 minutes and rely on route.avg_speed_knots and predicted_eta to smooth gaps.
Do I need separate auth flows per endpoint?
No. All endpoints share a single base URL and the same X-API-Key header. There are no per-endpoint auth differences.
What’s the quickest way to stand up a multi-ship map?
Use POST /vessels/fleet with include_positions=true and include_routes=true. This reduces round-trips and simplifies update logic for 5–50 tracked assets.
How do I interpret CII ratings for a single HLV voyage?
Request /vessels/green for a window that matches your reporting period (e.g., 30d). Use cii.rating (A–E) with estimated_emissions.co2_tons and distance_nm to contextualize intensity. If you need per-leg granularity, align with analytics statistics and last_port_visits from the tracking endpoint.
Can I filter search results to just heavy lift types?
Yes. Use /vessels/search with ship_type when you maintain a list of heavy lift categories or filter by capacity proxies (e.g., deadweight_tonnage ranges and year built) using min_dwt/max_dwt and year_built_from/year_built_to.
Next step
Bring your heavy lift dashboard online in minutes. Start with the tracking example above, then add analytics and fleet batching as you scale. When you’re ready, sign up and explore endpoints interactively: