You’re moving general cargo across congested ports and unpredictable weather windows, and your team needs reliable AIS tracking, port congestion signals, and ETAs you can defend. By the end of this guide you’ll connect to vessels-api.com, fetch live positions and predicted ETAs for general cargo ships, overlay real-time port congestion, and wire these into a transportation dashboard or workflow that reduces dwell time and missed handoffs.
What you’ll build for general cargo operations
General cargo schedules hinge on whether a ship is still at anchorage, how fast it’s making way, and if the destination port is backed up. With vessels-api.com you can:
- Track a specific general cargo ship by IMO or MMSI and read its live AIS position, recent track, active route, and predicted ETA.
- Query destination ports for live congestion and wait-time statistics to adjust buffers in your last-mile plan.
- List expected arrivals to coordinate berth, trucking slots, and crane teams before a ship crosses the pilot boarding point.
- Batch multiple general cargo vessels into a single fleet call to refresh a board without N requests.
All endpoints use a single base URL and the same header-based API key. Responses share a consistent JSON envelope so your parsing code is uniform across vessel tracking, port intelligence, and fleet ops.
Endpoints we’ll use
- GET /vessels/track — live position, history, route, and predicted ETA for a vessel
- GET /ports/congestion — real-time congestion and wait-time statistics for a port
- GET /port/expected-arrivals — vessels scheduled to arrive at a specific port (with ETA)
- GET /vessels/search — fuzzy search by name/IMO/MMSI to kick off tracking
- POST /vessels/fleet — refresh a board of multiple general cargo ships (optional but useful)
Prerequisites and conventions you’ll rely on
- Base URL: https://vessels-api.com/api/V1
- Authentication: X-API-Key header on every request (no OAuth)
- Response envelope: {"status","success","message","data"} across endpoints
- Units: speed in knots; distances in nautical miles (nm); wait/berth time in hours
- Timestamps: UTC strings (timestamp_utc, arrival_time, departure_time)
- Pagination: search endpoints expose pagination.current_page, per_page, total, last_page
Step 1 — Identify the general cargo ship to track
Use the search endpoint to resolve a vessel by name or directly by IMO/MMSI. For general cargo fleet onboarding, this reduces errors when names have variants or prefixes.
Example: search by name and filter by ship type
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/vessels/search?query=atlantic&ship_type=General%20Cargo&per_page=5"
Response fields of interest:
- data.vessels[].imo, data.vessels[].mmsi, data.vessels[].name
- data.vessels[].vessel_type and dimensions to confirm you have the right hull
- data.pagination for paging through results
Step 2 — Live AIS tracking with ETAs
Once you have an IMO or MMSI, call /vessels/track. This is the core for transportation use cases: it gives the latest AIS fix, a rolling history (up to 168 hours), the active route with ETA, and optionally weather for contextual risk assessment.
cURL: live tracking over the past 48 hours with predicted ETA
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/vessels/track?mmsi=258785000&hours=48&include_route=true&include_predicted_eta=true"
Python: fetch and read current position, route, and ETA
import os
import requests
API_KEY = os.getenv("VESSELS_API_KEY", "YOUR_API_KEY")
BASE_URL = "https://vessels-api.com/api/V1"
def track_vessel(mmsi: str, hours: int = 48):
url = f"{BASE_URL}/vessels/track"
params = {
"mmsi": mmsi,
"hours": hours,
"include_route": "true",
"include_predicted_eta": "true"
}
headers = {"X-API-Key": API_KEY}
r = requests.get(url, headers=headers, params=params, timeout=20)
r.raise_for_status()
payload = r.json()
# Uniform envelope: status / success / message / data
data = payload.get("data", {})
vessel = data.get("vessel", {})
current = data.get("current_position", {})
route = data.get("route", {})
# Fields you’ll use in a transportation dashboard:
return {
"name": vessel.get("name"),
"imo": vessel.get("imo"),
"mmsi": vessel.get("mmsi"),
"latitude": current.get("latitude"),
"longitude": current.get("longitude"),
"speed_knots": current.get("speed_knots"),
"course_degrees": current.get("course_degrees"),
"navigational_status": current.get("navigational_status"),
"timestamp_utc": current.get("timestamp_utc"),
"declared_destination": current.get("destination"),
"declared_eta": current.get("eta"),
"route_destination_port": route.get("destination_port"),
"predicted_eta": route.get("eta"),
"distance_nm_remaining": route.get("distance_nm"),
"avg_speed_knots": route.get("avg_speed_knots")
}
if __name__ == "__main__":
result = track_vessel("258785000", hours=48)
print(result)
Illustrative JSON: tracking payload highlights
The following example shows only documented fields and sample values for clarity:
{
"status": 200,
"success": true,
"message": "ok",
"data": {
"vessel": { "imo": "9123456", "mmsi": "258785000", "name": "ATLANTIC TRADER" },
"current_position": {
"latitude": 41.352,
"longitude": -8.742,
"speed_knots": 12.1,
"course_degrees": 84,
"heading_degrees": 85,
"navigational_status": "Under way using engine",
"timestamp_utc": "2026-09-28T11:22:30Z",
"destination": "ESBCN",
"eta": "2026-09-29T03:00:00Z"
},
"position_history": [
{ "latitude": 41.120, "longitude": -9.201, "speed_knots": 11.7, "course_degrees": 82, "timestamp_utc": "2026-09-28T09:22:30Z" }
],
"route": {
"departure_port": "PTLEI",
"departure_time": "2026-09-27T18:05:00Z",
"destination_port": "ESBCN",
"eta": "2026-09-29T02:47:00Z",
"distance_nm": 275.4,
"avg_speed_knots": 12.3
},
"last_port_visits": [
{ "port_id": "PTLEI", "arrival_time": "2026-09-26T02:00:00Z", "departure_time": "2026-09-27T18:05:00Z" }
]
}
}
What you’ll actually wire up:
- Use current_position.timestamp_utc to drive staleness indicators; all timestamps are UTC.
- route.eta is the predicted ETA you’ll show to planners; keep declared ETA from current_position.eta visible for context.
- route.distance_nm combined with speed_knots lets you sanity-check the ETA assumptions.
- position_history enables breadcrumb trails for ops playback (up to 168 hours with hours=).
Step 3 — Congestion-aware planning at destination ports
ETAs without port context mislead downstream transportation. Query congestion and expected arrivals to decide whether to pad buffer, resequence berths, or re-slot trucks and cranes.
Check real-time congestion and wait times
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/ports/congestion?port_id=ESBCN&period=7d"
Fields to drive decisions:
- snapshot.vessels_in_anchorage and vessels_at_berth to see current load.
- statistics.avg_wait_time_hours_last_7d and max_wait_time_hours_last_7d to translate into realistic buffer times for general cargo handling.
- statistics.avg_berth_time_hours_last_7d to plan crane shifts and yard moves.
List expected arrivals with ETA and origin
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/port/expected-arrivals?port=ESBCN"
Use expected_arrivals[].eta and departure_port to spot inbound cargo flows by origin and conflict windows with your target vessel’s ETA. In an ops view, sort by ETA ascending, then highlight conflicts where arrivals per hour exceed yard throughput.
Step 4 — Build a congestion-adjusted ETA workflow
For general cargo ships, berth windows depend on both the vessel’s progress and the port state. A pragmatic approach:
- Call /vessels/track for the MMSI or IMO, read route.destination_port and route.eta.
- Query /ports/congestion for that destination_port and retrieve avg_wait_time_hours_last_7d.
- Optionally check /port/expected-arrivals to detect ETA clusters around the same hour.
- Compute an operational ETA buffer:
- base_eta = route.eta
- buffer_hours = min(max_wait_time cap, avg_wait_time)
- ops_eta = base_eta + buffer_hours
- Expose both predicted ETA and ops ETA so port teams know the delta source (congestion adjustment).
Step 5 — Refresh a board of general cargo ships in one call
When you manage multiple general cargo vessels, a single POST to /vessels/fleet reduces request overhead and simplifies your scheduler.
curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"vessels":[{"imo":"9122556"},{"mmsi":"309374000"}],"include_positions":true,"include_routes":true}' \
"https://vessels-api.com/api/V1/vessels/fleet"
The response includes fleet aggregates (e.g., vessels_at_sea) and per-vessel position/route blocks, keeping your dashboard within one polling cycle.
Data handling details that save time
- Staleness: Use current_position.timestamp_utc to detect outdated AIS. If a point is older than your SLA (e.g., 30–60 minutes), surface a warning.
- Timestamps: All time fields are UTC. Store and compare in UTC; convert for UI only.
- Units: speeds are knots, distances are nautical miles (nm), durations are hours.
- History windows: /vessels/track supports hours up to 168 (7 days). Request only what you display to control payload size.
- Pagination: /vessels/search returns pagination metadata; set per_page up to 100 and iterate until last_page.
- Error handling: Rely on HTTP status and the envelope. Examples:
- 400 Missing/invalid parameter — verify you passed imo or mmsi.
- 401 Invalid or missing X-API-Key — check header spelling and value.
- 404 Vessel/port not found — re-check identifiers (IMO, MMSI, port_id).
- 422 Parameter out of range — e.g., hours above 168, radius above 200 NM.
- 429 Rate limit exceeded — back off with jitter; cache and reuse responses.
- 500 Server error — apply retries with exponential backoff.
- Caching: For dashboards, cache /ports/congestion for a short TTL (e.g., 5–10 minutes) and /port/expected-arrivals for 10–15 minutes. Keep /vessels/track near-real-time for en-route ships (e.g., 1–3 minutes) unless at berth.
Putting it together: a minimal transport ops loop
- Resolve MMSI/IMO with /vessels/search (once per ship or on demand by the operator).
- Fetch /vessels/track every few minutes for active voyages; store latest point, route.eta, and destination_port.
- Fetch /ports/congestion every 5–10 minutes for the likely arrival port, then compute ops_eta = route.eta + avg_wait_time_hours_last_7d.
- Show both ETAs in the UI with color-coded delta; if ops_eta drifts, alert the ground team to re-slot trucking.
- Refresh a list view for multiple general cargo ships via /vessels/fleet to keep requests bounded.
Port lookups and catalogs for transportation planning
When you need to map codes to names and time zones or pre-populate dropdowns, use the ports catalog and per-port data endpoints:
- GET /ports — list of 248 ports with id, coordinates, and timezone for UI scaffolding.
- GET /ports/data?port=PORT_ID — extended info plus live vessel counts (vessels_in_port, vessels_expected) if you need a quick density read.
ESG and compliance for general cargo vessels
If your transportation operations also report environmental metrics, call GET /vessels/green for IMO CII scoring. You’ll receive distance_nm, estimated_emissions, and a CII rating (A–E) per the referenced regulation. Tie this to route and port events to contextualize your emissions per completed voyage.
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/vessels/green?mmsi=258785000&period=30d"
Developer resources
For a broader overview of the platform and examples across search, tracking, fleet ops, ports, and CII, see the Vessels API docs. To start building, use the 7-day free trial on all plans and bring your transportation workflows online quickly: Register for Vessels API. If you need hosted MCP integration capabilities, explore Vessels API MCP.
FAQ
Which identifier should I prefer for general cargo tracking: IMO or MMSI?
Use whichever you have reliably. If you have both, pass one; the API requires either imo or mmsi. IMO is hull-specific and stable over the vessel’s life; MMSI can change with flag or equipment updates.
How often should I poll /vessels/track for transportation-grade ETAs?
Many teams poll every 1–3 minutes while the vessel is at sea and relax to 5–10 minutes near berth or at anchor. Use timestamp_utc to detect stale AIS and pause if the vessel is in port.
What’s the difference between declared ETA and predicted ETA?
current_position.eta is often the master’s or ECDIS-reported ETA; route.eta is the API’s predicted ETA based on recent track and route assumptions. Show both to your ops team and apply congestion buffers from /ports/congestion as an operational overlay.
How do I detect port congestion spikes that may affect a single ship’s ETA?
Query /ports/congestion for the destination_port and inspect snapshot plus the last-7-day wait-time statistics. Combine this with /port/expected-arrivals to see clusters in the same arrival window.
Can I get a quick roll-up for multiple general cargo ships?
Yes. POST /vessels/fleet with an array of vessels (imo or mmsi) and include_positions/include_routes to refresh a board in one call. The response also includes fleet aggregates for at-sea vs in-port counts.
Build your general cargo transportation dashboard today. Use the single-header auth, consistent JSON envelope, and focused endpoints to wire live AIS tracking with ETAs and port congestion in hours, not weeks. Start here: Register and keep the Documentation and MCP links handy while you integrate.
