You need to track a general cargo ship end-to-end: search it by name or MMSI, stream its live AIS position and recent track, compute voyage stats, and surface port-side events to your transportation ops stack. By the end of this guide you’ll integrate a production-ready workflow using vessels-api.com to find a general cargo vessel, follow its movements, estimate ETAs, power fleet dashboards, and feed port intelligence to your TMS or control tower.
What you’ll build: end-to-end tracking for a general cargo ship
We’ll wire together a minimal but robust pipeline around a single general cargo vessel and then generalize it to a fleet:
- Find the vessel by name, IMO, or MMSI with /vessels/search
- Stream live AIS, route, and port calls with /vessels/track
- Compute voyage statistics with /vessels/analytics
- Scale to multiple hulls using the fleet batch endpoint /vessels/fleet
- Overlay port-side context with port activity and expected arrivals
Every endpoint returns JSON in the same envelope: {status, success, message, data}. Authentication is a single X-API-Key header across the entire surface area. Base URL for all calls: https://vessels-api.com/api/V1.
Why vessels-api.com for general cargo tracking
- 18 REST endpoints spanning vessel search, live tracking, fleet ops, port intelligence, IMO CII emissions, and a premium real-time AIS feed
- Global AIS coverage with near real-time refresh rates to support transportation decisioning
- One API key, one base URL — no OAuth, no per-endpoint auth differences
- Consistent response contract for simpler error handling and logging
- 7-day free trial on all plans and scaling paths for indie devs up to enterprise fleets
Core endpoint 1: locate the general cargo vessel with /vessels/search
When cargo ops teams get a booking reference or a vessel nickname, they still need to resolve it to a canonical identity. Use /vessels/search to find a vessel by name (fuzzy), IMO, or MMSI. Filter by ship_type if you want to restrict to general cargo.
cURL
curl -H "X-API-Key: YOUR_API_KEY" "https://vessels-api.com/api/V1/vessels/track?mmsi=258785000&hours=48"Useful fields in data.vessels include:
- imo, mmsi, name — primary identifiers
- vessel_type — check this equals “General Cargo” or a similar cargo subtype
- length_m, width_m, deadweight_tonnage — often needed for berth planning and port validations
Notes:
- Pagination: use page and per_page (max 100). Read data.pagination for total and last_page.
- Fuzzy name search is helpful when upstream EDI feeds have slight spelling drift.
Core endpoint 2: live tracking and voyage context with /vessels/track
Once you have MMSI or IMO, use /vessels/track to fetch the current position, up to 168 hours of history, route metadata, and predicted ETA (if available). This is the backbone of a transportation control tower for general cargo operations.
Official sample: copy-paste this request and JSON
The following call and response are provided as a real fixture. Use them as a working template in your application.
{
"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:35+00:00",
"age_minutes": 5109740,
"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
}
}What to read:
- data.current_position.latitude/longitude — map the live fix
- speed_knots and course_degrees — compute movement state; speed in knots
- timestamp_utc — ISO-8601 in UTC; use it to age data and drive caching policies
- route.departure_port/destination_port/eta — stage ETAs into your planning UI
- last_port_visits — build port call timelines for your shipments
Request options:
- hours: default 24, max 168, controls the length of position_history
- include_route, include_predicted_eta, include_weather: toggle payload breadth
JavaScript example: fetch, parse, and map essential fields
async function trackVessel() {
const url = "https://vessels-api.com/api/V1/vessels/track?mmsi=258785000&hours=48";
const res = await fetch(url, {
headers: { "X-API-Key": "YOUR_API_KEY" }
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const payload = await res.json();
if (!payload.success) {
throw new Error(payload.message || "Tracking failed");
}
const { vessel, current_position, route, last_port_visits } = payload.data;
// Map the essentials
const point = {
lat: current_position.latitude,
lon: current_position.longitude,
speed: current_position.speed_knots, // knots
course: current_position.course_degrees, // degrees
ts: current_position.timestamp_utc // UTC ISO8601
};
const voyage = {
from: route?.departure_port || null,
to: route?.destination_port || null,
eta: route?.eta || null
};
const recentPorts = (last_port_visits || []).map(p => ({
id: p.port_id,
name: p.port_name,
arrived: p.arrival_time,
departed: p.departure_time
}));
return { vessel, point, voyage, recentPorts };
}
trackVessel()
.then(data => console.log("Tracked vessel:", data))
.catch(err => console.error(err));Implementation notes:
- Units: speed in knots; distances in nautical miles (nm).
- Time: timestamp_utc is always UTC. Keep your database in UTC; convert at the UI layer.
- Caching: if age_minutes is high, fall back to last known and surface staleness to users.
Core endpoint 3: voyage analytics for transportation KPIs
Transportation teams need robust KPIs: distance sailed, average speed, and port calls over a planning window. Use /vessels/analytics with type=vessel to compute these over 24h, 7d, 30d, or 90d.
cURL
Response fields of interest in data.statistics:
- total_distance_nm — cumulative sailing distance
- avg_speed_knots, max_speed_knots — speed envelope
- port_calls_count, total_time_in_port_hours — dwell vs. sail time
- ports_visited — list for auditing and routing visuals
These metrics drive interventions such as rebooking berth windows for general cargo or alerting when dwell exceeds SLA.
Core endpoint 4: scale to a general cargo fleet with /vessels/fleet
For transportation planners managing multiple general cargo vessels, fetch aggregated state for positions and routes in one POST.
POST request
In data.fleet you’ll see total_vessels, vessels_at_sea, and vessels_in_port, which power a live fleet banner in your dashboard. The data.vessels array includes each vessel’s position and route details to render map markers and voyage tooltips.
Engineering tips:
- Batch vessels into shards (e.g., 50 at a time) to parallelize in the client without stressing UI threads.
- Persist only deltas by hashing the position object; most refreshes are unchanged during dwell at berth.
Port-side context for general cargo operations
General cargo ships can face variable berthing and anchorage processes. Two endpoints augment your control tower:
- /port/activity — get arrivals and departures to correlate with your vessel’s last_port_visits
- /port/expected-arrivals — estimate port congestion upstream of your vessel’s destination
Examples
Combine these feeds with a vessel’s route.destination_port for proactive notifications to terminal partners, truck dispatchers, or barge schedulers in complex transportation chains.
ESG and compliance: CII scoring for your general cargo vessels
For ESG teams, /vessels/green exposes IMO CII scoring. Although KPIs are not strictly operational, surfacing a ship’s recent rating alongside voyage performance helps planners pick the appropriate hull for a trade lane while supporting compliance reporting.
cURL
Fields:
- estimated_emissions.co2_tons and co2_per_nm — estimated emissions basis
- cii.score and cii.rating (A–E) — aligned to IMO MEPC.339(76)
Use this to annotate a shipment view or to support periodic compliance exports.
Error handling, units, and operational guardrails
Every response ships as JSON with status, success, message, and data. Common HTTP codes:
- 400 — invalid/missing parameter: check required identifiers like mmsi
- 401 — missing or invalid X-API-Key
- 404 — vessel/port not found: ensure you’re passing a valid IMO/MMSI or port ID
- 422 — parameter out of range: e.g., hours over the max 168
- 429 — rate limit exceeded: backoff and retry with jitter
- 500 — server error: surface a retry and alert
Operational notes:
- Speed is in knots; distances are nautical miles (nm).
- Times are ISO-8601 in UTC; compute local times using port.timezone from /ports.
- Pagination for listing endpoints: inspect data.pagination and the per_page cap of 100.
- Cache position tracks based on timestamp_utc and age_minutes; avoid redundant map redraws.
Putting it together: a minimal workflow for a general cargo control tower
1) Resolve identity
Use /vessels/search to map human-entered names to canonical identifiers and confirm vessel_type is a cargo vessel you control or monitor.
2) Track live state
Call /vessels/track on a timer (e.g., 60–180 seconds during sailing, 5–10 minutes at berth) and store the latest current_position and route for the vessel’s detail view.
3) Compute KPIs
Trigger /vessels/analytics daily to refresh voyage metrics and render distance_nm, avg_speed_knots, and port_calls_count on fleet dashboards.
4) Scale to multiple hulls
Use /vessels/fleet to refresh fleet-wide indicators (vessels_at_sea/in_port) and generate a single update cycle for all general cargo ships under your scope.
5) Add port context
Resolve the vessel’s route.destination_port. Use /port/expected-arrivals and /port/activity to line up terminal resources and notify downstream transport legs (trucking, rail, barge) ahead of time.
Security and integration tips
- Always send X-API-Key in headers; do not log it client-side. Proxy calls through your backend where possible.
- Normalize vessel keys to MMSI internally for tracking, but store IMO as the stable hull reference for compliance and asset records.
- Use idempotent upserts when storing position data keyed by timestamp_utc to avoid duplicates.
- Feature flag predicted ETA display. When predicted_eta is null, fall back to route.eta if present, or hide ETA until reliable.
Reference links
FAQ
Q: What identifiers should I use for a general cargo ship — IMO or MMSI?
A: Use MMSI for live AIS tracking (/vessels/track). Store IMO as the long-lived hull identifier for analytics, compliance, and deduplication.
Q: How often should I poll /vessels/track for transportation use cases?
A: Sailing legs typically tolerate 60–180s. At berth or anchorage, 5–10 minutes reduces noise. Respect age_minutes to avoid unnecessary refresh when the last signal is stale.
Q: Can I filter /vessels/search to general cargo vessels only?
A: Yes. Use ship_type to restrict results and combine with other filters like flag, deadweight ranges, and year built as needed.
Q: How do I join port events to my vessel’s timeline?
A: Read route.destination_port and last_port_visits from /vessels/track. Query /port/activity and /port/expected-arrivals with that port ID to enrich timelines and alert ETAs to landside partners.
Q: How do I handle null predicted ETA?
A: If predicted_eta is null, check route.eta. If both are null, hide ETA or display “TBD” and notify users when it becomes available.
Get started
Build your general cargo tracking pipeline with a single API key and a consistent JSON contract. Start with /vessels/search to identify the hull, plug in /vessels/track for live AIS and voyage context, add /vessels/analytics for KPIs, and scale with /vessels/fleet. Explore the endpoints, copy the cURL and JavaScript from this guide, and ship your integration today via the Register page. For endpoint details, see the Documentation, and use the MCP to experiment interactively.
