Towage teams need reliable, minute-to-minute visibility of their tugs to coordinate berths, escorts, and barge moves. By the end of this article, you’ll be able to query, track, and operationalize tugboat data using vessels-api.com — from finding your tug by name or MMSI, to monitoring a live track with historical positions, to building a dispatch dashboard that watches multiple tugs at once.
Why a purpose-built API for tugboat operations
Towage is hyper-local and time-critical. Dispatchers, pilots, and port ops teams need consistent data they can wire directly into their workflows. Vessels API provides:
- 18 REST endpoints spanning vessel search, live tracking, fleet operations, port intelligence, CII emissions, and a premium real-time AIS feed.
- One API key, one base URL. All endpoints return a consistent JSON envelope: {status, success, message, data}.
- Near real-time AIS coverage that works the same whether you’re tracking a single tug or your entire harbor fleet.
All requests use the X-API-Key header against https://vessels-api.com/api/V1. Most endpoints are GET; batch fleet operations use POST.
Find your tug fast with /vessels/search
Before you can track or dispatch a tug, you need to resolve it by name, IMO, or MMSI. Use the search endpoint to identify the record and apply filters helpful for tug operations.
Example: Search by fuzzy name plus type filter
curl -H "X-API-Key: YOUR_API_KEY" "https://vessels-api.com/api/V1/vessels/track?mmsi=258785000&hours=48"Response structure (abbreviated):
{
"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:43+00:00",
"age_minutes": 5140700,
"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
}
}What matters for tug workflows: MMSI/IMO for downstream calls, vessel_type to confirm it’s a tug, and dimensions (length_m/width_m) for berth fit checks. Pagination fields help you iterate through results; set per_page up to 100.
Track a tug in real time with /vessels/track
Once you have MMSI or IMO, pull live positions, recent history, active route, and predicted ETA in one request. For a tug dispatch panel, you can poll this endpoint on a cadence appropriate to your UI (for example, every 30–60 seconds, subject to your app’s caching policy).
Official live example
This is the official sample for MMSI 258785000. Copy/paste exactly to validate your integration and confirm payload shape.
How to use it:
- current_position.timestamp_utc is ISO-8601 UTC; use age_minutes to highlight stale AIS updates.
- speed_knots and course_degrees drive your map overlay and “underway vs. idle” logic.
- route and last_port_visits help ops see context around the current job cycle.
- Increase history with hours= up to 168 (7 days) to replay movements for incident reviews.
Python example: Map-ready data from /vessels/track
import requests
API_KEY = "YOUR_API_KEY"
MMSI = "258785000"
url = "https://vessels-api.com/api/V1/vessels/track"
params = {"mmsi": MMSI, "hours": 48, "include_route": "true", "include_predicted_eta": "true"}
resp = requests.get(url, headers={"X-API-Key": API_KEY}, params=params, timeout=20)
resp.raise_for_status()
payload = resp.json()
if not payload.get("success"):
raise RuntimeError(f"API error: {payload.get('message')}")
data = payload["data"]
pos = data["current_position"]
lat, lon = pos["latitude"], pos["longitude"]
speed = pos["speed_knots"]
status = pos["navigational_status"]
ts = pos["timestamp_utc"]
route = data.get("route") or {}
last_visits = data.get("last_port_visits") or []
print(f"Lat/Lon: {lat}, {lon} | Speed: {speed} kn | Nav status: {status} | Time: {ts}")
if route:
print(f"Voyage: {route.get('departure_port')} → {route.get('destination_port')} ETA {route.get('eta')}")
print(f"Last port calls: {[v['port_name'] for v in last_visits]}")See which tugs are nearby with /vessels/nearby
Harbor dispatchers often need to find the closest available tug(s) to an inbound tanker or to a barge requiring assist. Use the nearby endpoint with latitude/longitude of the job and a radius in nautical miles.
Key fields to wire into a “closest tug” widget:
- vessels[].position.latitude/longitude for plotting.
- distance_nm to sort by proximity.
- speed_knots and navigational_status to filter vessels actually underway or available.
Tip: Pair this with /vessels/track by requesting detailed telemetry only after the user clicks a tug in the nearby list, reducing bandwidth and UI noise.
Batch your harbor fleet with /vessels/fleet
For a control room view, pull multiple tugs’ positions and routes in one round trip. This cuts client/server chatter and keeps your map synchronized.
What to expect back:
- data.fleet.vessels_at_sea and vessels_in_port for a quick health snapshot.
- data.vessels[] with position and route inline per tug.
For map updates, store the last timestamp_utc for each MMSI and only redraw markers that changed since the last poll.
Port activity feeds for tug scheduling
Tug availability depends on berth turnover and expected arrivals. Port-level event feeds let you anticipate work and pre-position assets.
Expected arrivals
Abbreviated response shape:
Use eta to schedule assist windows and generate job tickets. If you maintain a tug “duty roster,” you can match predicted workloads to available crews.
Recent arrivals and departures
Wire arrivals[] and departures[] into your operations timeline to see which berths will free up and where to dispatch the next tug job.
After-action KPIs with /vessels/analytics
Measure utilization, port calls, and speed profiles for your tugboats to improve planning and maintenance. Switch the analytics type based on the insight you need.
- type=vessel with a tug MMSI for a single-asset review (voyage distance, average/max speed, port calls).
- type=fleet with mmsi_list to roll up movement stats across your tugs.
Look at data.statistics.total_distance_nm for tow mileage, avg_speed_knots for engine-hour estimation, and port_calls_count for workload trends.
ESG and compliance: tugs and CII context
Some operators need to report emissions across mixed fleets. While CII primarily targets cargo ships, you can still use /vessels/green to provide estimated CO2 context in consolidated ESG dashboards that include tugs.
Read data.estimated_emissions.co2_tons and data.cii.rating. Present this alongside utilization to interpret emissions per nautical mile (co2_per_nm) for your operations reviews.
Implementation notes that save time
- Authentication: Include X-API-Key: YOUR_API_KEY on every request. No OAuth flows or per-endpoint auth differences.
- Units and timestamps: Distances in nautical miles (nm), speeds in knots, timestamps are UTC ISO-8601.
- Polling cadence: For a live tugboard, 30–60s polling is generally sufficient. Respect client-side caching to minimize redraws.
- Pagination: /vessels/search supports page and per_page (max 100). Use pagination.total and last_page to drive UI pagination.
- Error handling: Check the top-level {status, success, message}. Common errors include 400 (missing params), 401 (invalid key), 404 (not found), 422 (out of range), 429 (rate limited), 500 (server error). Implement backoff on 429/500.
- Envelope consistency: Every response contains the same envelope, so you can centralize parsing and logging across services.
JavaScript example: Closest-available tug selector
This snippet finds nearby tugs to a job coordinate, then enriches the top result with /vessels/track.
async function fetchJSON(url, params) {
const q = new URLSearchParams(params);
const res = await fetch(`${url}?${q.toString()}`, {
headers: { "X-API-Key": "YOUR_API_KEY" }
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const json = await res.json();
if (!json.success) throw new Error(json.message);
return json.data;
}
(async () => {
const center = { latitude: 29.736, longitude: -95.262 };
const nearby = await fetchJSON(
"https://vessels-api.com/api/V1/vessels/nearby",
{ ...center, radius: 10, ship_type: "tug", limit: 20 }
);
const tugs = (nearby.vessels || []).sort((a, b) => a.distance_nm - b.distance_nm);
if (tugs.length === 0) {
console.log("No tugs within 10nm");
return;
}
const closest = tugs[0];
const track = await fetchJSON(
"https://vessels-api.com/api/V1/vessels/track",
{ mmsi: closest.mmsi, hours: 24, include_route: "true" }
);
const cur = track.current_position;
console.log(`Closest tug MMSI ${closest.mmsi} at ${closest.distance_nm}nm`);
console.log(`Position ${cur.latitude},${cur.longitude} | ${cur.speed_knots} kn | status ${cur.navigational_status}`);
})();Putting it together: a practical tugboard architecture
- Discovery: Use /vessels/search to seed your fleet list and store MMSIs/IMOs for your tugs.
- Live map: Use /vessels/fleet to load all active tugs on initial page load. Poll every 30–60s.
- Detail panel: On click, query /vessels/track with hours=48 for recent movements and route context.
- Jobs view: Poll /vessels/nearby around terminals or pilot boarding areas to suggest candidates for new assists.
- Planning: Ingest /port/expected-arrivals and /port/activity to forecast workload and berth turnover.
- Reporting: Run /vessels/analytics weekly for utilization KPIs and optionally /vessels/green for emissions context.
Explore the full parameter set and all endpoints in the Documentation. If you prefer building with tools that support model-context protocols for rapid prototyping, check out the MCP.
FAQ
What’s the minimum data I need to track a tug?
Pass either imo or mmsi to /vessels/track. If you don’t know them, resolve via /vessels/search with a fuzzy name query and optional ship_type filter.
How far back can I request position history?
Use hours on /vessels/track up to 168 (7 days). If you omit it, the default is 24 hours.
How do I filter to only tugs when listing nearby vessels?
Add ship_type=tug to /vessels/nearby. Combine with radius (NM) and limit to tailor your search window.
How can I reduce API calls for a fleet map?
Use /vessels/fleet with include_positions true to fetch multiple tugs in one request. Then retrieve /vessels/track only for vessels that the user opens.
What’s the format of response data?
Every endpoint returns {status, success, message, data}. Timestamps are ISO-8601 in UTC, speeds are in knots, and distances are in nautical miles.
Ready to spin up a tugboard or enhance your towage ops with live AIS? Start integrating in minutes: Register.
