Dredging projects live and die by coordination: where each dredger is right now, how fast it’s moving, whether it’s at the borrow area, en route to a disposal site, or waiting on tide. In this guide you’ll build a dredger tracking flow end to end with vessels-api.com — searching for dredgers, streaming live AIS positions plus recent tracks, aggregating multi-vessel situational awareness, and adding port context for operations and ETAs.
What you can build for dredger operations with one API key
vessels-api.com provides 18 REST endpoints under a single base URL and a single header for authentication. You can stitch together:
- A control-room map of active dredgers with live positions and 48–168 hour trails.
- Automated alerts when a dredger enters a work polygon or approaches a disposal site.
- Operational stats across a fleet: underway vs. in port, recent port calls, and route snapshots.
- Port-level intelligence to plan windows and berth coordination for support craft.
- ESG evidence with per-vessel IMO CII context for compliance teams.
All endpoints return a consistent JSON envelope: {status, success, message, data}. Timestamps are UTC ISO-8601. Distances are nautical miles; speeds are in knots.
Setup: base URL, authentication, and patterns
- Base URL: https://vessels-api.com/api/V1
- Authentication: add X-API-Key: YOUR_API_KEY to every request header
- HTTP methods: all GET except /vessels/fleet which is POST with application/json
This post focuses on endpoints that matter most for dredger tracking:
- /vessels/search — locate dredgers by name/type/flag
- /vessels/track — live AIS + 24–168 h history with route and last port calls
- /vessels/fleet — batch retrieval for multi-dredger dashboards
- /vessels/nearby — quick proximity checks around work sites
- /ports/congestion and /ports/data — situational port intelligence
- /vessels/green — CII scoring context for ESG reporting
1) Find dredgers with fuzzy search and filters
Start by locating dredgers in your project scope. Use fuzzy name search and filter by ship type if you categorize dredgers in your taxonomy.
curl -H "X-API-Key: YOUR_API_KEY" "https://vessels-api.com/api/V1/vessels/track?mmsi=258785000&hours=48"Response fields to use:
- data.vessels[].imo, mmsi, name — stable identifiers to feed into tracking
- vessel_type, length_m, width_m — helpful for berth planning and geofencing tolerances
- pagination — iterate pages (per_page max is 100)
Example (abridged):
{
"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:10+00:00",
"age_minutes": 5132060,
"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
}
}2) Live dredger tracking with route context and history
Once you have an MMSI or IMO, retrieve the current position alongside recent positions, route data, and latest port calls. The hours parameter supports up to 168 hours for a 7-day trail; include_route and include_weather are optional booleans.
Official sample: 48-hour track by MMSI
Copy and run this as-is; it uses the documented MMSI 258785000 and returns a consistent envelope with route and last port visits:
Field notes for dredger ops:
- current_position.latitude/longitude — plot on your map. Units: degrees.
- speed_knots and course_degrees — detect dredging patterns (slow speeds, frequent heading changes).
- navigational_status — integer AIS status; 5 often indicates moored/anchored depending on AIS coding.
- route.* — quick voyage context; avg_speed_knots helps estimate cycles between borrow and dump sites.
- last_port_visits — operational history for lay-bys, crew changes, or maintenance calls.
Python example: fetch and shape a 24–48 h trail
This script calls the exact official endpoint above, reads the envelope, and normalizes key fields for your UI model. You can increase hours up to 168 to fetch a week of AIS points.
import os
import requests
API_KEY = os.getenv("VESSELS_API_KEY", "YOUR_API_KEY")
BASE_URL = "https://vessels-api.com/api/V1"
def track_dredger(mmsi: str, hours: int = 48):
url = f"{BASE_URL}/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", "Unknown API error"))
data = payload["data"]
vessel = data.get("vessel", {})
cur = data.get("current_position", {}) or {}
route = data.get("route", {}) or {}
history = data.get("position_history", []) or []
return {
"mmsi": vessel.get("mmsi"),
"imo": vessel.get("imo"),
"name": vessel.get("name"),
"position": {
"lat": cur.get("latitude"),
"lon": cur.get("longitude"),
"speed_knots": cur.get("speed_knots"),
"course_deg": cur.get("course_degrees"),
"status": cur.get("navigational_status"),
"ts_utc": cur.get("timestamp_utc"),
},
"route": {
"from": route.get("departure_port"),
"to": route.get("destination_port"),
"eta": route.get("eta"),
"avg_speed_knots": route.get("avg_speed_knots"),
},
"trail_points": [
{
"lat": p.get("latitude"),
"lon": p.get("longitude"),
"ts_utc": p.get("timestamp_utc"),
"speed_knots": p.get("speed_knots")
}
for p in history
]
}
if __name__ == "__main__":
model = track_dredger("258785000", hours=48)
print(model)Production tip: Cache track responses for 30–60 seconds in your backend to keep maps smooth and avoid redundant polls. All timestamps are UTC; display in local timezones as needed.
3) Fleet-wide dredger picture in one request
Most dredging spreads involve multiple dredgers, barges, tugs, and survey craft. Use /vessels/fleet to retrieve positions and route snapshots for many MMSIs/IMOs at once. This reduces network overhead and helps you compute aggregate counts (at sea, in port) for your control-room header.
Useful fields:
- data.fleet.vessels_at_sea / vessels_in_port — live rollups for UI badges.
- data.vessels[].position — last known AIS point; merge onto your map without N calls.
- data.vessels[].route — operational context to categorize “transit” vs “on station”.
Example (abridged):
4) Proximity checks: who’s inside the work box?
Need to know which vessels are currently near a dredge area or the disposal site? /vessels/nearby returns all vessels within a radius (nautical miles) of a lat/lon point, with optional ship_type filter. The default radius is 50 NM, maximum is 200 NM.
Use cases:
- Alert when support tugs or split-hoppers enter a hazard or exclusion zone.
- List of active dredgers within range of the borrow area at shift change.
Response (abridged):
5) Port intelligence for staging and windows
Dredger spreads often stage in nearby harbors or require berth windows for bunkering, crew changes, or survey mobilization. Two endpoints add context:
- /ports — a complete catalog to select relevant ports for your region.
- /ports/data — live in-port and expected vessels counts to gauge traffic.
Example — get a port’s live data by identifier:
Response shape:
Tip: Pair /ports/data with your dredger track to estimate congestion-driven delays for support vessel turnarounds.
6) Optional: ESG lens with IMO CII scoring
Some projects require environmental reporting that references IMO CII. While dredging cycles differ from liner trades, /vessels/green gives a consistent CII view per vessel over selectable periods, which can help contextualize emissions for compliance narratives.
Key fields:
- data.estimated_emissions.co2_tons — estimated CO₂ tonnage over the period.
- data.cii.rating — A (best) through E (worst), aligned with IMO MEPC.339(76).
Putting it together: a minimal dredger dashboard flow
- Discover assets: call /vessels/search with query and ship_type=Dredger. Persist IMO/MMSI and particulars.
- Live tracking: poll /vessels/track for each active dredger at 30–60 s intervals; request hours=24 for trails.
- Fleet rollups: refresh /vessels/fleet every 1–2 minutes for status counts and to fill map without N calls.
- Proximity alerts: every minute, call /vessels/nearby centered on the worksite; filter to ship_type=Dredger and support classes you care about.
- Port context: pull /ports/data for staging ports hourly to plan berth windows for tenders and bunker calls.
- ESG snapshot: optionally query /vessels/green monthly to add CII context to reporting packs.
Geofencing tip: Use the vessel’s course_degrees, speed_knots, and your polygon edge crossings to classify states like “on station,” “transit to dump,” or “transit to borrow.” You can also fall back to n-minute deltas of position to detect dredging activity (slow, meandering tracks).
Error handling, limits, and pagination
- HTTP 401 means your X-API-Key header is missing/invalid.
- 422 indicates a parameter out of range (e.g., hours > 168, per_page > 100, radius > 200 NM).
- 404 appears if a vessel or port cannot be found.
- Search pagination: obey pagination.last_page and paginate until complete; per_page max is 100.
Data freshness: Global AIS coverage provides near real-time refresh. Use age_minutes and timestamp_utc in current_position to decide if a point is fresh enough to render as “live” in your UI.
Security and deployment notes
- Keep your API key server-side. Proxy requests from your backend to avoid exposing keys in browsers.
- Time budgets: most calls return quickly; consider 15–20 s timeouts in your HTTP client.
- Backoff: on HTTP 429 (rate limit exceeded), back off and retry with jitter.
- Data model: centralize the {status, success, message, data} envelope parsing and keep your UI model minimal (lat, lon, speed, course, ts_utc, state).
End-to-end example: assemble a dredger’s operational card
Combine search, track, and last port visits to power a compact card in your dashboard:
This card can be fed by /vessels/track alone, updated on a 30–60 s cadence, and augmented with /vessels/nearby to surface nearby support craft (“2 tugs within 1 NM”).
Frequently asked questions
How often should I poll for live dredger positions?
A 30–60 second cadence balances freshness with network load for map UIs. For background analytics or alerting, 1–2 minutes is typical. Use age_minutes and timestamp_utc to decide when to mark a vessel as stale.
Should I use IMO or MMSI for tracking?
Use whichever you have consistently. MMSI is common for AIS tracking; IMO is stable across ownership. /vessels/track accepts either imo or mmsi.
Can I get a week of history?
Yes. Set hours up to 168 on /vessels/track. Be mindful of response sizes; paginate your UI’s rendering of trails or decimate points in your frontend.
How do I track multiple dredgers efficiently?
Use /vessels/fleet to fetch many assets in one POST. For detailed trails per vessel, call /vessels/track selectively (e.g., visible on map or selected by the user).
How do I plan around port congestion?
Use /ports/data for live counts and /ports/congestion for congestion snapshots and wait-time statistics by period. Combine with your dredger’s route context to schedule windows for support calls.
Next steps
Spin up a minimal control-room map that finds dredgers, polls a 48-hour track, and aggregates a two-vessel fleet rollup. When you’re ready, layer in proximity alerts and port context. Start with the API today:
