You need to track a car carrier in real time, check where it’s headed, estimate arrival at the next port, and roll those updates into a transportation dashboard that your ops and logistics teams can trust. By the end of this guide, you’ll query a live AIS track for a car carrier, filter by vessel type, aggregate fleet stats, and integrate port-facing signals—all through a consistent REST API with one key and one base URL.
What You Can Build for Car Carrier Operations
Car carriers (PCC/PCTC) run tight schedules and call specialized ro-ro terminals. A minimal, production-ready integration should allow you to:
- Search for a car carrier by name, IMO, or MMSI and resolve its core identifiers.
- Stream its live AIS position, recent history, and current route with predicted ETA.
- Batch-query multiple carriers for a fleet map and “at sea vs in port” snapshot.
- Compute voyage analytics (distance, speeds, port calls) for weekly performance tracking.
- Cross-check port activity and expected arrivals for berth planning and landside scheduling.
All of the above is available from vessels-api.com through a single header (X-API-Key) and a consistent JSON envelope: {status, success, message, data}.
Core Endpoints for Tracking a Car Carrier
Vessels API covers 18 REST endpoints. For car carrier tracking, these 5 are the most relevant:
- GET /vessels/search — find a carrier by name, IMO, or MMSI; filter by type and flag.
- GET /vessels/track — live AIS position, 24–168h history, route, and predicted ETA.
- POST /vessels/fleet — fetch positions and routes for multiple carriers in one call.
- GET /vessels/analytics — voyage stats per vessel (or fleet) over 24h to 90d.
- GET /port/expected-arrivals — carriers inbound to a port with ETA and origin.
Base URL: https://vessels-api.com/api/V1. Authentication is via the X-API-Key header only; no OAuth and no per-endpoint auth variations.
1) Find the Car Carrier You Need: /vessels/search
Start by resolving the vessel you’ll track. When a planner or dispatcher types “Glovis” or “Höegh,” you’ll return a small list with key identifiers (IMO, MMSI), gross/deadweight tonnage, and build year. Use filters like ship_type to narrow to PCC/PCTC carriers in your logistics app.
Search cURL (with filters)
curl -H "X-API-Key: YOUR_API_KEY" "https://vessels-api.com/api/V1/vessels/track?mmsi=258785000&hours=48"Notes for implementation:
- Fuzzy name search via query matches partials and alternative spellings.
- Paginate with page and per_page (max 100). Cache list responses briefly in your UI to reduce redundant calls.
- If your UX prefers a fixed ship type, store the selected IMO/MMSI once and proceed with /vessels/track.
2) Live AIS Track for a Car Carrier: /vessels/track
Once you have the MMSI or IMO, pull the live position, recent history, current route, and predicted ETA. Time fields are ISO8601 with +00:00; treat all timestamps as UTC. Speed is in knots, distances in nautical miles.
Official cURL (car carrier track)
Official JSON Response
{
"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:04+00:00",
"age_minutes": 5113281,
"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 use in a transportation dashboard:
- data.current_position: latitude, longitude, speed_knots, course_degrees for your map and speed overlays.
- data.route: departure_port, destination_port, eta to automate ETA and port-call workflows.
- data.last_port_visits: drive “last called” widgets and dwell-time insights.
- Optional fields: predicted_eta and weather are toggled via include_predicted_eta and include_weather. If you need these, add the query flags.
Python example (requests)
import requests
from datetime import datetime, timezone
API_KEY = "YOUR_API_KEY"
URL = "https://vessels-api.com/api/V1/vessels/track"
params = {
"mmsi": "258785000", # documented MMSI track fixture
"hours": "48" # up to 168 supported
}
headers = {"X-API-Key": API_KEY}
r = requests.get(URL, params=params, headers=headers, timeout=15)
r.raise_for_status()
payload = r.json()
if not payload.get("success"):
raise RuntimeError(f"API error: {payload.get('message')}")
data = payload["data"]
pos = data.get("current_position", {}) or {}
lat = pos.get("latitude")
lon = pos.get("longitude")
speed = pos.get("speed_knots")
course = pos.get("course_degrees")
ts = pos.get("timestamp_utc")
route = data.get("route", {}) or {}
eta_iso = route.get("eta") or pos.get("eta")
eta_dt = None
if eta_iso:
eta_dt = datetime.fromisoformat(eta_iso.replace("Z", "+00:00"))
print(f"Lat/Lon: {lat}, {lon}")
print(f"Speed (kn): {speed}, Course (deg): {course}")
print(f"ETA (UTC): {eta_dt.isoformat() if eta_dt else 'unknown'}")
Implementation tips:
- Track polling: For near real-time dashboards, poll every 1–5 minutes and deduplicate positions by timestamp_utc. The response envelope is consistent across endpoints.
- History window: hours ranges 24–168. For voyage replay UIs, request longer windows; for live maps, keep it short and cache.
- Statuses: navigational_status is an integer AIS code; map to your business states (e.g., at anchor, underway, moored) in your application.
3) Batch Track a Fleet of Car Carriers: /vessels/fleet
Transportation teams often manage 10–50 carriers. Instead of calling /vessels/track per vessel, use /vessels/fleet to get positions and routes in one request. This reduces client-side overhead and simplifies summary metrics (e.g., “vessels at sea” vs “in port”).
Fleet cURL (POST JSON)
Design notes:
- Body takes IMO or MMSI per vessel; mix is allowed.
- Response includes a fleet aggregate object and a per-vessel array with position and route when requested.
- For large fleets, segment requests logically (by trade lane or operator) and cache per segment for ~60s to smooth spikes.
4) Voyage Analytics for Performance: /vessels/analytics
Daily or weekly operations reviews benefit from objective stats: total distance sailed, average and max speed, time in port, and port calls. Use these to benchmark carriers, spot slowdowns, and feed reliability models.
Analytics cURL (single vessel)
Key fields you’ll use:
- statistics.total_distance_nm for planning and bunker estimations.
- statistics.avg_speed_knots and max_speed_knots to validate schedules.
- statistics.port_calls_count and total_time_in_port_hours to detect congestion or slow turnarounds.
Switch type to fleet with mmsi_list when you want a roll-up view across your PCC/PCTC set.
5) Port-Facing Context: /port/expected-arrivals
For berth planning and landside yard scheduling, expected arrivals provide the next inbound carriers with their ETA and origin port. This works well alongside /vessels/track for a hybrid “push” and “pull” model of port activity.
Expected arrivals cURL
Practical usage:
- Cross-check a tracked carrier’s route. If a given MMSI appears in expected_arrivals, surface a port-specific ETA in your UI.
- Join with /vessels/search results to filter only vehicle carriers when building port arrival grids.
Authentication, Responses, and Error Handling
All requests use the same header: X-API-Key: YOUR_API_KEY. The response envelope is uniform: {status, success, message, data}. This makes it easy to implement centralized error handling and logging across services.
- 200 OK: successful call. Check success is true, then read data.
- 400/422: validate your parameters, types, and ranges (e.g., hours ≤ 168).
- 401: ensure the X-API-Key header is present and correct in every call.
- 404: retry logic should not loop indefinitely; surface a clear “not found” to the user.
- 429: back off and add simple client-side rate limiting; cache non-personalized data (e.g., search results) briefly.
Field Semantics and Units That Matter
Carriers change states often (moored, underway, at anchor). Use these conventions in your app:
- Coordinates: latitude/longitude in decimal degrees. Plot directly on web maps.
- Speed/course/heading: knots and degrees (0–359). Use course for directional arrows in your UI.
- Distances: nautical miles (nm). Avoid automatic conversions that could confuse operators.
- Timestamps: ISO8601 with UTC (“+00:00”). Keep everything UTC in your backend; convert to local time zones only at the presentation layer if required.
- Pagination: /vessels/search supports page and per_page (max 100). De-duplicate across pages using IMO or MMSI.
Building the Transportation Workflow
Step 1: Resolve the vessel once
Use /vessels/search to find the car carrier by name, then store its IMO and MMSI in your system of record. This avoids fuzzy matching on every refresh.
Step 2: Poll the live track
Call /vessels/track every 1–5 minutes for live dashboards. Store the last successful data.current_position.timestamp_utc to avoid re-rendering identical points. Use include_route and include_predicted_eta for ETA-critical milestones.
Step 3: Aggregate your fleet
Every 2–5 minutes, call /vessels/fleet for 10–50 carriers. Maintain a fleet-level cache and expose a “staleness” indicator in the UI (e.g., “as of 12:34 UTC”).
Step 4: Weekly analytics
Nightly, run /vessels/analytics with period=7d. Persist the output to a warehouse for trend views, KPI alerts, and SLA audits.
Step 5: Port visibility
Every 15–30 minutes, call /port/expected-arrivals for the ports you care about (e.g., ro-ro terminals within your network). Integrate these expected arrivals with your carrier routes for reliable gate windows and yard staffing plans.
Operational Reliability and Caching Tips
- Idempotency by timestamp: Use timestamp_utc as your dedupe key for point inserts.
- Graceful nulls: destination, eta, and heading can be null. Default your UI widgets conservatively (e.g., “–” or “unknown”).
- Short-lived caches: 30–90 seconds for track responses, 5–10 minutes for analytics, and 15–30 minutes for expected arrivals (depending on your SLA).
- Retry/backoff: For 5xx or transient network errors, exponential backoff with jitter; do not retry on 4xx except 429 after a delay.
Why Transportation Teams Choose This API
- 18 REST endpoints spanning vessel search, live AIS, fleet, port intelligence, and emissions.
- One key, one base URL, consistent JSON envelope across every response.
- Global AIS coverage with near real-time refresh, built for developers integrating transportation data.
- Works for indie tools and enterprise fleets. There is a free trial period to validate fit before rollout.
For schema details and parameter options, see the official Documentation. To try endpoints interactively with model context tooling, open the MCP.
FAQ
Q: What’s the minimum input to start tracking a car carrier?
A: Provide either imo or mmsi to /vessels/track. If you only have a fuzzy name, call /vessels/search first to resolve identifiers.
Q: How often should I poll /vessels/track?
A: For live dashboards, 1–5 minutes per vessel is typical. Use timestamp_utc and position age to avoid redundant updates. Batch fleets via /vessels/fleet to reduce request overhead.
Q: Can I filter only car carriers in search results?
A: Yes. Use /vessels/search with ship_type and your preferred constraints (e.g., flag, year_built). Store IMO/MMSI and then track by identifier going forward.
Q: How do I get a port’s expected inbound vessels?
A: Use GET /port/expected-arrivals with the port identifier (e.g., ARBUE). Join expected arrivals with /vessels/track to validate ETA and current leg.
Q: What does the response envelope look like across endpoints?
A: Every endpoint returns {status, success, message, data}. Always check success and handle errors centrally. Distances are nautical miles, speeds are knots, timestamps are UTC.
Ship It
Use the endpoints above to wire a dependable transportation workflow for car carriers: resolve the vessel, stream its AIS track and route, roll up your fleet, and add port context where it matters. Start integrating now—get an API key and a 7-day trial, review schemas, and test live calls in minutes.
Register · Documentation · MCP
