You need reliable container ship tracking you can wire into dashboards, ETA pipelines, and port operations tools. By the end of this guide you’ll query live AIS positions, plot recent tracks, batch-monitor fleets, and surface port-arrival intelligence using a single, consistent REST API.
What you’ll build with the Vessels API
Container shipping is schedule-driven. Your tooling has to answer: Where’s the box ship now? What’s the predicted ETA? Which vessels are converging on my terminal? How’s the fleet performing this week? With vessels-api.com you can:
- Search and identify container ships by name, IMO, or MMSI.
- Track a live position with up to 168h of historical AIS, route context, and predicted ETA.
- Batch-monitor entire fleets in one request for control-room dashboards.
- Surface expected arrivals for a port to drive yard planning.
- Compute voyage analytics and pull IMO CII emissions data for ESG workflows.
All endpoints share a single base URL and key header, and every response returns the same JSON envelope: {status, success, message, data}.
API setup in one minute
- Base URL: https://vessels-api.com/api/V1
- Authentication: send X-API-Key: YOUR_API_KEY as a request header
- Methods: GET for all endpoints except POST /vessels/fleet
- Time: timestamps are ISO 8601 in UTC (e.g., 2026-04-27T21:35:36+00:00)
- Distances and speed: nautical miles (nm) and knots
Reference the full field list and optional parameters in the Documentation. For local querying and debugging, the MCP is handy for issuing live test calls.
Endpoint focus for container ship tracking
The following endpoints cover the core visibility loop for container trades:
- /vessels/search — find the right vessel by name/IMO/MMSI and filter by type or tonnage
- /vessels/track — live position, recent history, route, predicted ETA, and port visits
- /vessels/fleet (POST) — batch pull positions and routes for many vessels
- /port/expected-arrivals — view inbound vessels with ETAs and origin ports
- /vessels/analytics — aggregate voyage KPIs for trend views
- /vessels/green — IMO CII emissions scoring for ESG reporting
Identify the ship: fuzzy search with filters
When a booking or EDI message provides only a partial vessel name, use /vessels/search to pin down the target container ship. Filter by vessel type, flag, year built, or TEU range to reduce ambiguity.
curl -H "X-API-Key: YOUR_API_KEY" "https://vessels-api.com/api/V1/vessels/track?mmsi=258785000&hours=48"Key behaviors:
- query matches name fuzzy, and it also accepts IMO or MMSI directly.
- Use page and per_page (max 100) to paginate through large result sets.
- Record imo and mmsi for downstream calls to /vessels/track or /vessels/fleet.
Live tracking with route context and predicted ETA
/vessels/track returns a live AIS position, optional up to 168 hours of history, the active route, predicted ETA, and last port calls—everything you need to maintain a ship timeline and update a schedule feed.
Official sample (copy-paste)
cURL:
JSON:
{
"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:53+00:00",
"age_minutes": 5137820,
"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
}
}How to use these fields:
- current_position.latitude/longitude and timestamp_utc: plot the latest point; timestamps are UTC.
- speed_knots, course_degrees, navigational_status: decide if the vessel is underway, drifting, or moored.
- route.departure_port, destination_port, avg_speed_knots: display voyage context in a route header.
- last_port_visits: build a timeline of recent port calls for auditing and exception analysis.
- predicted_eta (when present): feed into your terminal planning or delivery promises.
JavaScript example: poll and render a status badge
async function getVesselStatus(mmsi) {
const url = `https://vessels-api.com/api/V1/vessels/track?mmsi=${encodeURIComponent(mmsi)}&hours=48`;
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(); // { status, success, message, data }
const d = json.data;
const pos = d.current_position;
const route = d.route;
return {
mmsi: d.vessel.mmsi,
lat: pos.latitude,
lon: pos.longitude,
ts: pos.timestamp_utc,
speed: pos.speed_knots, // knots
course: pos.course_degrees, // degrees true
navStatus: pos.navigational_status, // integer AIS nav status
dest: pos.destination || route?.destination_port || null,
eta: d.predicted_eta || pos.eta || route?.eta || null
};
}
getVesselStatus('258785000')
.then(console.log)
.catch(console.error);Practical tips
- History window: set hours up to 168 to retrieve the last 7 days for your track polyline.
- Cache policy: cache immutable position_history points keyed by timestamp_utc; only refresh the latest tick frequently.
- Fallbacks: if predicted_eta is null, fall back to current_position.eta, then route.eta.
Track the whole boxship fleet in one call
Control rooms and NOC dashboards need a single POST that returns positions and route headers for many vessels. Use /vessels/fleet to reduce client–server roundtrips and keep consistent timestamps across rows.
Notes:
- Body fields: vessels is an array of {imo, mmsi}. Either identifier is accepted per row.
- include_positions/include_routes let you control payload size per refresh pass.
- Use data.fleet.vessels_at_sea versus vessels_in_port to render high-level KPIs.
Python snippet: normalize and display ETD/ETA columns
import requests
import json
API = "https://vessels-api.com/api/V1"
HEADERS = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}
payload = {
"vessels": [{"imo": "9122556"}, {"mmsi": "309374000"}],
"include_positions": True,
"include_routes": True
}
r = requests.post(f"{API}/vessels/fleet", headers=HEADERS, data=json.dumps(payload))
r.raise_for_status()
data = r.json()["data"]
rows = []
for v in data["vessels"]:
pos = v.get("position") or {}
route = v.get("route") or {}
rows.append({
"name": v.get("name"),
"mmsi": v.get("mmsi"),
"lat": pos.get("latitude"),
"lon": pos.get("longitude"),
"speed_knots": pos.get("speed_knots"),
"dest": pos.get("destination") or route.get("destination_port"),
"eta": route.get("eta")
})
for row in rows:
print(row)Inbound visibility: expected arrivals for terminal planning
Container terminals, freight forwarders, and trucking dispatchers need an at-a-glance view of inbound ships. /port/expected-arrivals returns vessels expected to arrive at a port with ETA and origin port information.
Common pattern:
- Join expected_arrivals by mmsi/imo with /vessels/track for real-time refinement of ETA and current position.
- Sort by eta and build a 72-hour roll-up board for berth-window planning.
Voyage KPIs for planners and operations reviews
How far did each container ship sail in the last 7 days? How many ports were touched? /vessels/analytics returns aggregated voyage statistics for a vessel, port, or fleet view. For per-vessel weekly trends:
Fields of interest in data.statistics include:
- total_distance_nm — cumulative distance sailed
- avg_speed_knots and max_speed_knots — pace across the period
- port_calls_count and total_time_in_port_hours — dwell and call frequency
- ports_visited — list of port identifiers for mapping trade lanes
ESG and CII readiness for container lines
If you report on fleet sustainability or need to screen voyages for compliance risk, /vessels/green provides an IMO CII score and rating over a selectable period. Ratings are A (best) to E (worst), aligned to IMO MEPC.339(76).
Use cases:
- Highlight vessels trending from C to D across recent periods for corrective actions.
- Expose co2_tons and co2_per_nm for sustainability scorecards in the same dashboard as tracking.
Putting it together: a minimal container ship tracker
Data flow
- Discovery: search for the vessel using /vessels/search if you only have a partial name or booking label.
- Live map: call /vessels/track every few minutes to render current_position and append to a map track (hours parameter up to 168 for last 7 days).
- ETA board: combine /port/expected-arrivals with /vessels/track.predicted_eta for prioritized operations lists.
- Fleet wallboard: POST /vessels/fleet on a fixed cadence, and paint route.destination_port and route.eta inline.
- Weekly review: query /vessels/analytics and /vessels/green for performance and ESG deltas.
Error handling and edge cases
- Authentication: a missing or invalid X-API-Key returns HTTP 401.
- Validation: malformed or out-of-range params return 400 or 422.
- Not found: unknown vessel or port returns 404.
- Throttling: on 429, back off with jitter and reuse cached position_history points.
- Nullability: some fields (e.g., predicted_eta, destination, heading_degrees) may be null; implement fallbacks.
Practical implementation notes
- Identifiers: prefer IMO for static joins and MMSI for AIS-driven lookups; both are supported across endpoints.
- Consistency: every response includes {status, success, message, data}; parse defensively and feature-detect keys.
- Pagination: for /vessels/search, capture data.pagination for page navigation; per_page max is 100.
- Map updates: use age_minutes (when provided) to color-code freshness of AIS ticks.
- Units: speed_knots in knots, distance_nm in nautical miles; keep unit conversions in a dedicated utility.
Frequently asked questions
How often should I poll /vessels/track?
Use a cadence aligned with your UI’s need and caching strategy. Many dashboards poll every 1–5 minutes for the current tick, while historical segments can be cached and refreshed less frequently.
Do I need both IMO and MMSI?
No. Most endpoints accept either. For long-lived joins across systems, store both when available so you can resolve changes in MMSI or callsign over time.
What is the difference between eta, predicted_eta, and route.eta?
predicted_eta is the model-derived prediction when available. current_position.eta can reflect AIS broadcast ETA. route.eta is the voyage plan’s ETA. Prefer predicted_eta, then current_position.eta, then route.eta as a final fallback.
Can I filter to container ships only?
Yes. On /vessels/search, set ship_type=Container Ship (exact string) to narrow results. On /vessels/nearby, you can also provide ship_type to limit matches around a coordinate.
How do I join expected-arrivals with tracking?
Use the common mmsi or imo fields. Pull expected arrivals to seed your arrival board, then enrich each row with /vessels/track for current_position and predicted_eta.
Build your container ship tracker today
Spin up your container-ship visibility stack with a single API key, consistent JSON, and endpoints that cover discovery, tracking, fleet views, port arrivals, analytics, and CII. Start integrating with the Register link, keep the reference nearby with the Documentation, and explore queries interactively via the MCP.
