You need to track a dredger in near real-time, see its recent track and active route, and surface reliable ETAs and port interactions in your dashboard. By the end of this guide, you’ll query a dredger’s live AIS position and history, locate nearby traffic around your dredging site, roll up multiple dredgers into a fleet snapshot, and wire this data into a dredging operations UI using vessels-api.com.
What makes this API fit for dredger tracking
Dredging projects demand precise timing: hopper cycles, disposal transits, tug rendezvous, safety zones near channels, and tidal windows at ports. Vessels API delivers:
- 18 REST endpoints spanning vessel search, live tracking, fleet operations, port intelligence, IMO CII emissions, and a premium real-time AIS feed.
- One API key, one base URL, no OAuth: send X-API-Key with every request.
- Consistent JSON envelope on every response: {status, success, message, data}.
- Global AIS coverage with near real-time refresh rates.
- A 7-day free trial that scales from a single dredger to enterprise fleets.
In this post we’ll use four endpoints that matter most for dredger operations:
- /vessels/search — quickly resolve a dredger by name, MMSI, or IMO
- /vessels/track — live position, 24–168h history, active route, predicted ETA, weather
- /vessels/nearby — traffic picture around your dredging site
- /vessels/fleet — batch data for multiple dredgers and support craft
Reference docs: Documentation. You can also explore our programmable control-plane: MCP.
Authentication and base URL
All endpoints are under https://vessels-api.com/api/V1 and accept an API key in the X-API-Key header. All responses use the same envelope with fields: status (HTTP-like code), success (boolean), message (text), and data (payload). Timestamps are ISO-8601 UTC. Distances are nautical miles, speeds are knots.
1) Resolve your dredger with /vessels/search
Start by looking up the MMSI or IMO you’ll use throughout routing and telemetry. You can search by name or identifiers with optional filters like ship_type, flag, build year, and tonnage. Pagination is supported with page and per_page (max 100).
cURL
curl -H "X-API-Key: YOUR_API_KEY" "https://vessels-api.com/api/V1/vessels/track?mmsi=258785000&hours=48"Sample JSON snippet
{
"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:38+00:00",
"age_minutes": 5111840,
"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
}
}Key fields you’ll actually use:
- imo / mmsi — stable identifiers for subsequent calls
- vessel_type — confirm it’s a Dredger before you onboard it into your ops UI
- dimensions — useful when checking channel clearances or drafting safety zones
2) Live position and history with /vessels/track
This endpoint returns the dredger’s current position, recent AIS track (up to 168 hours), active route, predicted ETA, and optional weather. For hopper cycles, plot position_history points to compute dredge/turnaround phases. For regulatory events, store last_port_visits alongside project logs.
Official sample (copy-paste)
The following cURL and JSON blocks are official. Use them to validate your integration and field mappings.
Field notes for dredger use cases:
- current_position.speed_knots — zero or near-zero can indicate active dredging or anchorage; combine with stationary clustering to detect spoil loading.
- current_position.navigational_status — status code 5 commonly indicates moored; use this to toggle “at-berth” states in your UI.
- route — departure/destination ports and ETA help coordinate dredged material disposal windows or berth bookings.
- last_port_visits — attach to daily reports for port authority coordination.
- hours parameter — default 24, up to 168 for week-long dredging cycle analysis.
JavaScript fetch example
This snippet calls the same MMSI, reads the JSON envelope, and normalizes the location payload for mapping.
async function getDredgerTrack(mmsi = "258785000", hours = 48) {
const url = `https://vessels-api.com/api/V1/vessels/track?mmsi=${encodeURIComponent(mmsi)}&hours=${hours}`;
const res = await fetch(url, {
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 || "API error");
const { vessel, current_position, position_history, route, last_port_visits } = json.data;
return {
id: vessel.mmsi || vessel.imo,
coords: current_position ? {
lat: current_position.latitude,
lon: current_position.longitude,
ts: current_position.timestamp_utc,
speed: current_position.speed_knots,
course: current_position.course_degrees,
status: current_position.navigational_status
} : null,
history: position_history || [],
route,
lastPorts: last_port_visits || []
};
}
// Example usage:
getDredgerTrack().then(console.log).catch(console.error);Practical implementation tips
- Cache current_position for 30–60 seconds in your service to smooth polling across dashboards.
- If you request hours > 24, paginate your UI markers or decimate points to avoid map clutter.
- All timestamps are UTC; annotate your UI with timezones where local port ops care about LT.
- Handle 404 (vessel not found), 401 (missing/invalid key), and 429 (rate limit exceeded) with retries or backoff in your client.
3) Situational awareness with /vessels/nearby
When your dredger is operating in a narrow channel, you’ll want a rolling picture of nearby traffic to manage safety zones, tug escorts, and VTS coordination. Query a radius (nautical miles) around your site centerpoint, optionally filtered by ship_type.
cURL
Sample JSON snippet
Use distance_nm to rank risk proximity. For channels, you may cap radius to 1–3 NM and refresh every 30–60 seconds. Keep limit below 100 to avoid heavy map updates; the default is 50.
4) Multi-vessel dredging ops with /vessels/fleet
Dredging rarely runs in isolation. You’ll coordinate a hopper, a work barge, a survey boat, and a tug. Pull a single payload for multiple vessels and render a cohesive operations board.
POST body and cURL
Sample JSON snippet
Fleet-level counters feed headlines on your dashboard (“2 assets, 1 at sea”). Per-vessel blocks give you map pins, speed/heading badges, and ETAs without N calls to /vessels/track.
Optional: emissions insights for compliance with /vessels/green
Some dredging tenders require emissions reporting. You can obtain an IMO CII-style snapshot over a rolling period, including distance_nm and estimated_emissions. Ratings go from A (best) to E (worst), following IMO MEPC.339(76).
Store the cii.rating and cii.score alongside daily activity logs. For programmatic ESG dashboards, pair this endpoint with last_port_visits for a defensible audit trail.
Port operations: congestion snapshots
If your dredger interfaces with a port (e.g., bunkering or equipment transfer), you may need to check congestion and wait-time statistics before transiting. Use GET /ports/congestion with a UNLOCODE port_id (e.g., ARBUE for Buenos Aires) and a period of interest. Avoid hard-coding assumptions; always read the statistics object and snapshot fields from the API.
Important: use official port IDs present in the title parentheses (e.g., ARBUE, SGSIN, NLRTM). Do not assume wait times. If you need raw port metadata for planning (coordinates, timezone), use GET /ports or GET /ports/data.
Data handling patterns that save time
- Polling cadence: for live dredging views, poll /vessels/track every 30–60s and /vessels/nearby every 60s. Use ETags or short-lived caches to reduce redundant UI work.
- Error handling: map HTTP 4xx/5xx and API status into your client logs. 400 = bad params, 401 = invalid key, 404 = not found, 422 = out of range, 429 = throttled, 500 = server error.
- Pagination: /vessels/search supports page/per_page up to 100. For autocomplete, debounce inputs and keep per_page small (10–20).
- Units: knots for speed, nautical miles for distance, ISO-8601 UTC for times. When exporting to stakeholders, convert to local time at the port timezone from /ports or /ports/data.
- Consistency: every response uses {status, success, message, data}. Always check success before reading data.
End-to-end example: building a dredger ops panel
Inputs
- Primary dredger MMSI (e.g., 258785000)
- Project site center (lat/lon) with a 3 NM safety radius
- Additional support vessels (tug, survey boat) by IMO or MMSI
Workflow
- Resolve MMSI/IMO with /vessels/search for each asset and store identifiers.
- Every 30–60s, hit /vessels/fleet with include_positions and include_routes for your asset list to power map pins and ETAs.
- Every 60s, call /vessels/nearby centered on the dredging site to surface third-party traffic and potential conflicts. Filter by ship_type if needed.
- For detailed playback or incident review, call /vessels/track with hours=168 to pull a week of history.
- If port calls are part of the cycle, periodically query /ports/congestion for your turnaround port to anticipate waiting times.
Python example: minimal backend aggregator
import requests
from typing import List, Dict, Any
BASE_URL = "https://vessels-api.com/api/V1"
HEADERS = {"X-API-Key": "YOUR_API_KEY"}
def track_vessel(mmsi: str, hours: int = 24) -> Dict[str, Any]:
url = f"{BASE_URL}/vessels/track"
resp = requests.get(url, headers=HEADERS, params={"mmsi": mmsi, "hours": hours}, timeout=15)
resp.raise_for_status()
data = resp.json()
if not data.get("success"):
raise RuntimeError(data.get("message", "API error"))
return data["data"]
def nearby(lat: float, lon: float, radius_nm: int = 3) -> List[Dict[str, Any]]:
url = f"{BASE_URL}/vessels/nearby"
resp = requests.get(url, headers=HEADERS, params={
"latitude": lat, "longitude": lon, "radius": radius_nm, "limit": 50
}, timeout=15)
resp.raise_for_status()
data = resp.json()
if not data.get("success"):
raise RuntimeError(data.get("message", "API error"))
return data["data"]["vessels"]
def fleet_snapshot(vessels: List[Dict[str, str]]) -> Dict[str, Any]:
url = f"{BASE_URL}/vessels/fleet"
payload = {"vessels": vessels, "include_positions": True, "include_routes": True}
resp = requests.post(url, headers={**HEADERS, "Content-Type": "application/json"}, json=payload, timeout=20)
resp.raise_for_status()
data = resp.json()
if not data.get("success"):
raise RuntimeError(data.get("message", "API error"))
return data["data"]
# Example usage
if __name__ == "__main__":
dredger_mmsi = "258785000"
dredger_data = track_vessel(dredger_mmsi, hours=48)
print("Dredger position:", dredger_data["current_position"])
site_vessels = nearby(53.33708, 7.17993, radius_nm=3)
print("Nearby traffic count:", len(site_vessels))
ops_fleet = [{"mmsi": dredger_mmsi}, {"imo": "9336717"}]
snapshot = fleet_snapshot(ops_fleet)
print("Fleet totals:", snapshot["fleet"])Field mapping checklist for dredger UX
- Map pin: current_position.latitude/longitude, course_degrees arrow, speed_knots badge
- Status: navigational_status (e.g., moored/under way), derived “At Dredge Site” if distance to site center < threshold
- Route and ETA: route.destination_port and route.eta to coordinate disposal windows
- Playback: position_history plotted as polyline, colored by speed to detect active dredging intervals
- Port ledger: last_port_visits for post-ops reconciliation
FAQ
How often should I poll for a dredger’s live position?
Most dashboards work well at 30–60 second intervals for /vessels/track. Cache responses briefly to avoid redundant map updates.
What if I only know the vessel name, not MMSI/IMO?
Use /vessels/search with query=name and ship_type=Dredger to resolve identifiers, then store MMSI/IMO for subsequent calls.
How do I get a quick picture of multiple assets?
Use /vessels/fleet with include_positions and include_routes to avoid N parallel /vessels/track calls.
What timezone are timestamps in?
All timestamps are ISO-8601 UTC. If you need local time for port operations, retrieve the port timezone from /ports or /ports/data and convert in your UI.
What errors should I handle?
400 for invalid parameters, 401 for missing/invalid X-API-Key, 404 when a vessel or port can’t be found, 422 for out-of-range params (e.g., radius > 200 NM), 429 for rate limiting, and 500 for server errors.
Ready to wire dredger tracking into your ops stack? Start building with a 7-day free trial. Create your key, open the docs, and ship your first integration:
