Car Carrier Tracking API: Search, Track and Nearby

Your logistics team needs reliable, developer-friendly vessel data to keep car carriers on schedule: search the right ship, watch its live track and route, and query what’s nearby a factory port or PDI anchorage. By the end of this guide you’ll be able to integrate three core capabilities for roll-on/roll-off (Ro-Ro) car carriers using vessels-api.com: search, track, and nearby—with fleet and ESG extensions for production use.

Why car-carrier tracking needs purpose-built endpoints

Car carriers operate on tight windows: yard availability, Ro-Ro ramps, time-sensitive handoffs with rail and trucking. You need:

Illustration: Car Carrier Tracking API: Search, Track and Nearby

Discovery: find a specific Ro-Ro by IMO/MMSI or fuzzy name to seed a dashboard.
Live tracking: course, speed, predicted ETA, and last port calls to power ETL pipelines and ops screens.
Context: nearby traffic around a terminal to understand congestion risk before a ramp opens.
Scale: batch updates for a full fleet and emissions scoring for compliance reporting.

Vessels API delivers 18 REST endpoints over a single base URL and API key, with a consistent JSON envelope across all responses, and global AIS coverage with near real-time refresh. It’s built to get developers to working code fast while staying robust enough for enterprise transportation operations.

Getting started: base URL, auth, and response envelope

All endpoints share:

Base URL: https://vessels-api.com/api/V1
Authentication: X-API-Key header (no OAuth)
HTTP methods: GET for all endpoints except POST for /vessels/fleet
Consistent envelope: {"status", "success", "message", "data"}

Time values are ISO 8601 UTC (e.g., 2026-04-27T21:35:36+00:00). Distances are in nautical miles (nm). Speeds are in knots. For list endpoints, watch pagination and limits noted below.

Search: locate your car carrier with /vessels/search

Use /vessels/search to resolve fuzzy names, IMO, or MMSI. You can filter by ship_type (e.g., “Vehicles Carrier”), flag, tonnage ranges, and build years—useful when your TMS exports only partial identifiers.

Example: find a carrier by fuzzy name and flag

curl -H "X-API-Key: YOUR_API_KEY" "https://vessels-api.com/api/V1/vessels/track?mmsi=258785000&hours=48"

Key parameters:

query: name, IMO, or MMSI. Fuzzy string matches are supported for names.
ship_type: narrow to Ro-Ro or vehicle carriers to reduce false positives.
page/per_page: paginate through results (per_page max is 100).

From the response, store imo, mmsi, name, vessel_type, and year_built to your database; these seed subsequent tracking calls. Use pagination to backfill a reference catalog of carriers your network frequently encounters.

Track: live AIS positions, routes, and ETAs with /vessels/track

/vessels/track returns a vessel’s current AIS position, optional history up to 168 hours, active route details, predicted ETA, and last port visits. This is your backbone for a live operations board, connection to your yard allocation logic, and downstream alerts when a vessel changes course or speed.

Official sample (copy and run)

{
"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:00+00:00",
"age_minutes": 5093061,
"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 transportation workflows:

current_position.latitude/longitude, speed_knots, course_degrees: to plot live tracks and detect slowdowns.
current_position.timestamp_utc: ingestion and freshness checks; timestamps are UTC ISO 8601.
route.departure_port, destination_port, eta, avg_speed_knots: to compute terminal handoffs and alert drayage partners.
last_port_visits: build reliable port-call histories and transit-time analytics across car carrier loops.

Parameters to tune:

hours: up to 168 hours of history; default 24. Use more for trend lines and ETA sanity checks.
include_route, include_predicted_eta, include_weather: request only what you need to control payload size.

Python example: track a car carrier and normalize fields

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
}
headers = {"X-API-Key": API_KEY}

resp = requests.get(url, params=params, headers=headers, timeout=20)
resp.raise_for_status()
envelope = resp.json()

if not envelope.get("success"):
raise RuntimeError(f"API error: {envelope.get('message')}")

data = envelope["data"]
vessel = data.get("vessel", {})
pos = data.get("current_position", {}) or {}

# Core fields for your ops dashboard
track_point = {
"mmsi": vessel.get("mmsi"),
"imo": vessel.get("imo"),
"lat": pos.get("latitude"),
"lon": pos.get("longitude"),
"sog_kn": pos.get("speed_knots"),
"cog_deg": pos.get("course_degrees"),
"ts_utc": pos.get("timestamp_utc"), # ISO 8601 UTC
"nav_status": pos.get("navigational_status"),
}

route = data.get("route") or {}
route_summary = {
"from_port": route.get("departure_port"),
"to_port": route.get("destination_port"),
"eta_utc": route.get("eta"),
"avg_speed_kn": route.get("avg_speed_knots"),
}

print("Track point:", track_point)
print("Route:", route_summary)

# Basic staleness check
if track_point["ts_utc"]:
t = datetime.fromisoformat(track_point["ts_utc"].replace("Z", "+00:00"))
age_minutes = (datetime.now(timezone.utc) - t).total_seconds() / 60.0
print(f"Age (minutes): {age_minutes:.1f}")

Nearby: traffic context around PDI ramps and anchorage with /vessels/nearby

/vessels/nearby answers “who else is near this terminal?”—critical when a car carrier is ready to berth and you want early signals for potential conflicts. It returns vessels within a radius of a coordinate, with optional ship_type filtering.

Example: 30 nm around a port coordinate

Key parameters:

latitude/longitude: center point in decimal degrees.
radius: nautical miles (default 50, max 200).
ship_type: narrow to car carriers to monitor competitive congestion.
limit: control payload size for maps and widgets.

Use distance_nm and speed_knots from each result to anticipate arrival sequencing, and navigational_status to distinguish anchored vs. underway traffic.

Fleet: batch tracking at scale with /vessels/fleet (POST)

When you operate multiple car carriers or track partner vessels, batch calls reduce overhead and help ensure your UI and alerts stay in sync.

Example: positions and routes for multiple vessels

Tips:

Mix imo and mmsi in a single request; the API will resolve both.
include_routes when you need ETA and voyage context; omit for lightweight heartbeat updates.
Use the top-level fleet summary (vessels_at_sea vs. in_port) to power management rollups.

ESG and compliance for Ro-Ro with /vessels/green

For sustainability and regulatory reporting, /vessels/green returns IMO CII estimates aligned with MEPC.339(76), including a rating A (best) to E (worst). For car carriers with recurring loops, this helps benchmark emissions per nautical mile over the period you choose.

Example: 30-day CII snapshot by MMSI

Fields to store:

estimated_emissions.co2_tons and co2_per_nm for unit costs and ESG dashboards.
cii.score, rating, and year for compliance attestations.

Implementation details that will save you time

Units and coordinates: distances in nautical miles (nm), speeds in knots, bearings in degrees; positions are WGS84 lat/lon.
Timestamps: ISO 8601 in UTC. Normalize to UTC internally; convert to local timezones only in UI layers.
Selective fields: include_route, include_predicted_eta, include_weather on /vessels/track let you trim payload sizes for polling loops.
Polling cadence: leverage your own cache for map tiles; when a carrier is slow or anchored, poll less frequently to reduce compute.
Pagination: /vessels/search supports page/per_page (max 100). Capture pagination.total to provision storage.
Status codes: handle 400 (validation), 401 (API key), 404 (not found), 422 (out of range), 429 (rate limit), 500 (server) with backoff and retries where appropriate.
Identifiers: prefer IMO for vessel identity, MMSI for radio transponder tracking; track both so you can bridge data sources.

Putting it together: a car-carrier ops pipeline

A minimal production flow for Ro-Ro transportation teams might look like this:

Seed: call /vessels/search nightly for ship_type=Vehicles Carrier to maintain a reference list of carriers with imo, mmsi, name, dimensions.
Live board: every few minutes, call /vessels/fleet for your tracked list with include_positions=true. For vessels approaching destination, augment with /vessels/track?include_route=true.
Terminal view: when a berth window opens, call /vessels/nearby around the terminal’s coordinates with ship_type=Vehicles Carrier to see approaching peers.
ESG job: weekly, compute emissions aggregates by calling /vessels/green for each vessel over 7d or 30d.

This pattern keeps your TMS, yard ops, and partner notifications aligned without overfetching, and it uses only five endpoints with a single auth model.

Field notes for Ro-Ro specifics

ETD/ETA mismatches: Prefer route.eta from /vessels/track over AIS destination strings when scheduling ramps; AIS free-text destinations may be null or stale.
Anchorage detection: navigational_status plus speed_knots≈0 indicates anchorage; combine with distance to terminal to flag near-berth readiness.
Loop analytics: last_port_visits enable time-in-port and voyage cycle KPIs for automotive supply chains.
Map clustering: when using /vessels/nearby for dense port areas, cluster by distance_nm buckets to keep UIs performant.

Security, rollout, and observability

Auth: use the X-API-Key header from your secrets manager; never bake keys into front-end code.
Circuit breakers: on 429 and 500, exponential backoff protects your job workers.
Schema stability: the response envelope is consistent across endpoints; log status and message for fast diagnostics.
Change control: stage your own normalization layer for fields like navigational_status and vessel_type to avoid downstream schema drift.

FAQs

Can I query by either IMO or MMSI?
Yes. /vessels/search, /vessels/track, and /vessels/green all accept either IMO or MMSI (at least one is required for /vessels/track and /vessels/green).

What timezone are timestamps in?
All timestamps are UTC in ISO 8601 format. Convert in your UI only, and keep storage/indexing in UTC.

How often should I poll for live tracking?
It depends on your SLA. Many teams poll every 2–5 minutes while underway and back off when at anchor or alongside. Use speed_knots and navigational_status to adapt.

How do I get historical tracks?
Use the hours parameter on /vessels/track to retrieve up to 168 hours of position history in one call. For longer horizons, store snapshots in your own data store.

Can I filter nearby to only car carriers?
Yes. Pass ship_type=Vehicles Carrier to /vessels/nearby to restrict results to Ro-Ro vehicle carriers.

Build your car-carrier tracking in hours, not weeks

All the examples above use one API key and one base URL with a consistent JSON envelope, so you can move from prototype to production without reworking authentication or schemas. Start a 7-day trial and wire up search, track, and nearby for your car-carrier operations today with the links below.