Moving vehicle logistics live and on schedule depends on knowing exactly where your car carriers are, where they’re headed, and when they’ll dock. By the end of this guide you’ll be able to integrate car carrier tracking into your transportation systems using vessels-api.com: locate a specific Ro-Ro vessel, pull live AIS positions with 48-hour history, compute ETAs for your loads, monitor multiple hulls in a single call, and enrich operations with port-arrival signals and ESG CII scores.
What makes car carrier tracking different (and what the API gives you)
Car carriers (Ro-Ro, PCC/PCTC) run tight windows across export/import terminals. Miss a tide gate and your yard backs up. You need:
- Fast vessel lookup from a booking reference (name), IMO, or MMSI.
- Live AIS location, course, speed, and status—with optional route and ETA.
- Batch telemetry for your whole PCC fleet without N calls per vessel.
- Port arrival feeds to pre-stage trucks and yard space.
- CII emissions scoring for ESG and regulatory reporting.
vessels-api.com provides all of the above via one base URL and one API key. Every response ships in a consistent JSON envelope: {status, success, message, data}. AIS positions are near real-time, timestamps are UTC, distances are in nautical miles (nm), and speeds are in knots (kn).
Endpoints we’ll use for car carrier tracking
- GET /vessels/search — find a car carrier by name, IMO, or MMSI with filters.
- GET /vessels/track — current AIS position, position history, route, ETA.
- POST /vessels/fleet — batch tracking for multiple carriers in one request.
- GET /port/expected-arrivals — plan truck gates and berth resources.
- GET /vessels/green — CII emissions scoring for compliance.
Authentication, base URL, and request model
All requests use the same base URL and header:
- Base URL: https://vessels-api.com/api/V1
- Header: X-API-Key: YOUR_API_KEY
- HTTP methods: all GET except /vessels/fleet which is POST
Response envelope on every endpoint:
{
"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:36+00:00",
"age_minutes": 5133500,
"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
}
}Step 1 — Find your car carrier quickly with /vessels/search
When you have a booking that references a vessel nickname or you only know the flag or year built, use fuzzy search and filters. For PCC/PCTC, ship_type filters help narrow results.
cURL
curl -H "X-API-Key: YOUR_API_KEY" "https://vessels-api.com/api/V1/vessels/track?mmsi=258785000&hours=48"Key parameters:
- query — name (fuzzy), IMO, or MMSI.
- ship_type — e.g., Ro-Ro for car carriers.
- flag, year_built_from/year_built_to, min_dwt/max_dwt, min_teu/max_teu.
- Pagination: page, per_page (max 100).
Response shape (fields you’ll use):
Practical tip: cache the IMO/MMSI from this step. Your downstream tracking requests can then address the exact hull without repeating fuzzy searches.
Step 2 — Get live AIS and 48h history with /vessels/track
/vessels/track is the workhorse for logistics. Pass imo or mmsi. Optionally add hours (up to 168), include_route, include_predicted_eta, include_weather.
Official cURL (copy/paste)
Official JSON (verbatim)
Fields to wire into your dashboards and alerts:
- current_position.latitude/longitude — plot on map; store last seen.
- speed_knots, course_degrees — estimate progress; detect anchorage or berthing when speed ≈ 0 kn.
- navigational_status — AIS nav codes; build simple rules (e.g., 5 often indicates moored).
- timestamp_utc — ISO8601 UTC; base SLAs and staleness checks (age_minutes).
- route — departure, destination, avg_speed_knots; show voyage context.
- last_port_visits — build recent call timeline for compliance and cargo planning.
Python example: consume /vessels/track
import requests
from datetime import datetime, timezone
API_KEY = "YOUR_API_KEY"
MMSI = "258785000"
URL = "https://vessels-api.com/api/V1/vessels/track"
params = {
"mmsi": MMSI,
"hours": 48,
"include_route": "true",
"include_predicted_eta": "true"
}
resp = requests.get(URL, headers={"X-API-Key": API_KEY}, params=params, timeout=15)
resp.raise_for_status()
payload = resp.json()
if not payload.get("success"):
raise RuntimeError(f"API error: {payload.get('message')}")
data = payload["data"]
vessel = data["vessel"]
pos = data["current_position"]
lat = pos["latitude"]
lon = pos["longitude"]
speed = pos["speed_knots"]
course = pos["course_degrees"]
ts = pos["timestamp_utc"]
# Convert timestamp to aware datetime for SLA checks
seen = datetime.fromisoformat(ts.replace("Z", "+00:00")).astimezone(timezone.utc)
print(f"MMSI {vessel['mmsi']} @ {lat},{lon} speed {speed} kn course {course} at {seen.isoformat()}")
route = data.get("route") or {}
print(f"Route: {route.get('departure_port')} → {route.get('destination_port')} avg {route.get('avg_speed_knots')} kn")
pred_eta = data.get("predicted_eta")
if pred_eta:
print(f"Predicted ETA: {pred_eta}")Polling notes:
- Positions are near real-time; poll frequency depends on your load. For live boards, 1–5 minutes is common. Cache previous payloads to minimize UI repaint.
- Handle null/empty position_history on stationary vessels or when hours is small.
Step 3 — Track multiple car carriers in one call with /vessels/fleet
When you manage 10–200 PCC/PCTC hulls, N single-vessel calls become expensive to orchestrate. Use /vessels/fleet to request positions and routes in a single POST.
cURL
Response (trimmed for clarity):
Use cases:
- Operations wallboard: color-code vessels_in_port vs vessels_at_sea.
- Exception alerts: find hulls with staleness (position age_minutes beyond threshold), or speed_knots = 0 within approach zone.
- Capacity snapshots: count carriers approaching a specific discharge port in ±48h (combine with route fields).
Step 4 — Plan truck gates with /port/expected-arrivals
Use expected arrivals to align your yard, drivers, and terminal time windows. This is particularly useful for automotive ramps that must sync customs, inspection, and pre-delivery inspection resources.
cURL
Response shape:
Practical tips:
- Combine /vessels/track predicted_eta with port expected_arrivals to resolve conflicts and update your truck arrival slots.
- All times are UTC; if your gate uses local time, convert using the port’s timezone from GET /ports or GET /ports/data.
Step 5 — Add ESG with /vessels/green (IMO CII)
For automotive logistics, ESG and regulatory reporting are table stakes. Use /vessels/green to get CO2 estimates and the CII rating for each carrier over a defined period.
cURL
Response (key fields):
How to use it:
- Build per-voyage CII snapshots for every hull that carried your units.
- Flag deteriorating ratings (D/E) and escalate to procurement for carrier selection.
- Roll up distance_nm and co2_tons per lane to inform routing choices.
JavaScript example — end-to-end: search → track → green
async function getJson(url, opts = {}) {
const res = await fetch(url, {
headers: { "X-API-Key": "YOUR_API_KEY" },
...opts
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const body = await res.json();
if (!body.success) throw new Error(body.message || "API error");
return body.data;
}
(async () => {
// 1) Find a Ro-Ro carrier by name
const searchUrl = new URL("https://vessels-api.com/api/V1/vessels/search");
searchUrl.searchParams.set("query", "glovis");
searchUrl.searchParams.set("ship_type", "Ro-Ro");
searchUrl.searchParams.set("per_page", "5");
const sdata = await getJson(searchUrl.toString());
const first = sdata.vessels[0];
if (!first) return console.log("No vessels found.");
const mmsi = first.mmsi || "";
console.log("Found:", first.name, first.imo, mmsi);
// 2) Track with 48h history and route context
const trackUrl = new URL("https://vessels-api.com/api/V1/vessels/track");
trackUrl.searchParams.set("mmsi", mmsi);
trackUrl.searchParams.set("hours", "48");
trackUrl.searchParams.set("include_route", "true");
const tdata = await getJson(trackUrl.toString());
const pos = tdata.current_position;
console.log(`Pos: ${pos.latitude},${pos.longitude} ${pos.speed_knots}kn @ ${pos.timestamp_utc}`);
// 3) Pull 30-day CII score
const greenUrl = new URL("https://vessels-api.com/api/V1/vessels/green");
greenUrl.searchParams.set("mmsi", mmsi);
greenUrl.searchParams.set("period", "30d");
const gdata = await getJson(greenUrl.toString());
console.log(`CII: ${gdata.cii.rating} (score ${gdata.cii.score}) over ${gdata.distance_nm} nm`);
})().catch(console.error);Production notes for transportation teams
- Units and timezones: speeds in knots; distances in nm; timestamps in UTC ISO8601. Convert to local TZ for berth windows and truck gates.
- Caching: keep a short-lived cache (e.g., 60–180 seconds) around /vessels/track for list views; fetch on-demand for detail views.
- Staleness: check age_minutes to detect silence; trigger fallbacks if above your SLA threshold.
- Pagination: /vessels/search supports per_page up to 100; use pagination when listing carriers by operator.
- Error handling: 401 = invalid/missing key; 404 = vessel/port not found; 422 = parameter out of range; 429 = rate limit exceeded; retry/backoff responsibly.
How car carrier workflows come together
Fleet board
- Hourly: POST /vessels/fleet for all PCC hulls you manage.
- Map: plot each vessel.position; annotate route.destination_port.
- Status: color code moored/underway via current_position.navigational_status and speed_knots.
Gate scheduling and yard prep
- Daily: GET /port/expected-arrivals for your discharge ports.
- Per vessel: GET /vessels/track include_predicted_eta to narrow arrival windows.
- Result: sequenced truck slots, pre-staged yard lanes, minimized dwell.
ESG and compliance
- Monthly: GET /vessels/green for every hull that carried your units.
- Roll-up: distance_nm and estimated_emissions across lanes and carriers.
- Governance: flag D/E ratings and enforce procurement guardrails.
Reference: ports catalog and single-port details
When you need coordinates or timezone for local conversions, use the ports catalog and single-port detail endpoints.
cURL: list all ports
cURL: single port details
Typical fields:
Use timezone to convert UTC ETA to local terminal time for ramp planning and driver dispatch.
Security, rollout, and observability
- Transport security: always use HTTPS; never embed your X-API-Key in public clients. Proxy through your backend when building browser apps.
- Idempotency: GETs are read-only; /vessels/fleet is a POST but read-only as well. Safe to retry on 429/5xx with exponential backoff.
- Telemetry: log status, message, and request correlation IDs from your stack to spot spikes or missing params (400/422).
Frequently asked questions
Q: How often should I poll /vessels/track for a live car carrier map?
A: Most dashboards use 60–300 seconds. Use age_minutes to detect stale AIS and back off if positions aren’t updating.
Q: Do I need different auth for different endpoints?
A: No. One X-API-Key header works for all endpoints and methods.
Q: What if I only have the vessel name from a booking?
A: Start with /vessels/search using query and ship_type=Ro-Ro, then cache the returned IMO/MMSI for precise tracking.
Q: Can I request predicted ETA and weather along with the track?
A: Yes. Add include_predicted_eta and include_weather to /vessels/track to enrich voyage context.
Q: How do I track multiple car carriers without making many requests?
A: Use POST /vessels/fleet with a list of IMO/MMSI objects and request positions/routes in one response.
Next steps
Build your car carrier tracking workflow in hours, not weeks. Start with the official reference, wire the endpoints shown above, and ship your first live map and ETA board today.
