You need to track a ferry in real time, show its latest AIS position, surface a reliable ETA for the next stop, and push updates into a transportation operations dashboard. By the end of this guide you will be able to search for a ferry by MMSI or name, fetch its live track with route and ETA, monitor nearby ferries to a terminal, and pull concise analytics for planning — all using vessels-api.com over a single REST interface.
Why use vessels-api.com for ferry tracking
Ferry operations are time-sensitive and route-dense. You need consistent AIS data, predictable responses, and endpoints that match transportation workflows. vessels-api.com provides:
- 18 REST endpoints across vessel search, live AIS tracking, fleet operations, port intelligence, IMO CII emissions, and a premium real-time AIS feed.
- One API key and one base URL; no OAuth or per-endpoint auth differences.
- Consistent JSON envelope on every response: {status, success, message, data}.
- Global AIS coverage with near real-time refresh rates.
- A 7-day free trial on all plans with scale from indie devs to enterprise fleets.
- Targeted to developers, logistics startups, fleet managers, port operators, and ESG/compliance teams.
Everything you see below uses the same base URL and authentication header:
- Base URL: https://vessels-api.com/api/V1
- Authentication: X-API-Key: YOUR_API_KEY
Core ferry-tracking endpoints you will use
For transportation use cases focused on ferries, these endpoints cover the key jobs-to-be-done:
- /vessels/search — Resolve MMSI/IMO and confirm you have the right ferry.
- /vessels/track — Live position, short-term history, active route, predicted ETA, and last port calls.
- /vessels/nearby — Snapshot of ferries in a radius around your terminal or waypoint.
- /vessels/analytics — Voyage aggregates (distance, speed, port calls) for planning and service performance.
- Port intelligence (/ports, /ports/data, /ports/congestion, /port/expected-arrivals) — Terminal context, berths, and activity feeds that inform schedule adherence and passenger communications.
1) Resolve the ferry you need with /vessels/search
Before tracking, get a stable identifier. For ferries you’ll typically use MMSI, but name-based search with filters helps when a route hosts multiple vessels or you’re normalizing user input.
Endpoint
GET /vessels/search — Find any vessel by name (fuzzy), IMO, or MMSI. Optional filters include ship_type, flag, DWT/TEU ranges, and build year bounds. Results are paginated (per_page up to 100).
cURL
curl -H "X-API-Key: YOUR_API_KEY" "https://vessels-api.com/api/V1/vessels/track?mmsi=258785000&hours=48"Key fields to use:
- data.vessels[].mmsi or .imo — feed these into /vessels/track and fleet endpoints.
- data.vessels[].name and .vessel_type — use for UI labeling and to confirm you matched a ferry, not a cargo or tanker.
- data.pagination — always check for paging when building typeahead search or admin tools.
2) Track a ferry live with /vessels/track
This is the primary transportation workflow: map the ferry’s current AIS position, render its route, and provide an ETA that you can show in a rider app or an internal control room.
Endpoint
GET /vessels/track — Live position plus up to 168-hour position history, active route, predicted ETA, and optional weather. Required: imo OR mmsi. Optional: hours (default 24, max 168), include_route, include_predicted_eta, include_weather.
Official cURL (copy-paste)
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:03+00:00",
"age_minutes": 5111001,
"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
}
}How to use it in a ferry dashboard:
- data.current_position.latitude/longitude (WGS84) — plot on your map and compute distance to terminal for last-mile ETA corrections.
- data.current_position.speed_knots and course_degrees — show as current speed/course indicators, and use speed_knots to debounce ETA jitter during docking.
- data.current_position.timestamp_utc — UTC ISO 8601; check freshness before notifying passengers. age_minutes provides a quick staleness signal.
- data.route.departure_port, destination_port, eta — render the active leg and expected arrival. For ferries on repetitive loops, this drives headway display.
- data.last_port_visits — build recent activity widgets or detect mid-route diversions.
Tip: Always handle nulls defensively (e.g., predicted_eta, weather) because service conditions vary by coverage and AIS updates. Timestamps are UTC — convert in your UI layer per user’s locale. Coordinates are in decimal degrees. Speed is in knots.
Python example using requests
This example calls the same endpoint, validates the envelope, handles nulls, and prints a rider-facing line with position and ETA when available.
import os
import requests
from datetime import datetime, timezone
API_KEY = os.getenv("VESSELS_API_KEY", "YOUR_API_KEY")
BASE_URL = "https://vessels-api.com/api/V1"
def track_ferry(mmsi: str, hours: int = 48):
url = f"{BASE_URL}/vessels/track"
params = {"mmsi": mmsi, "hours": hours}
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.get("data", {})
vessel = data.get("vessel", {})
pos = data.get("current_position", {}) or {}
route = data.get("route", {}) or {}
predicted_eta = data.get("predicted_eta")
mmsi_val = vessel.get("mmsi")
lat = pos.get("latitude")
lon = pos.get("longitude")
speed = pos.get("speed_knots")
ts = pos.get("timestamp_utc")
eta = predicted_eta or route.get("eta")
# Convert timestamps to local/UTC-aware for display
def parse_iso(t):
try:
return datetime.fromisoformat(t.replace("Z", "+00:00"))
except Exception:
return None
ts_dt = parse_iso(ts) if ts else None
eta_dt = parse_iso(eta) if eta else None
print(f"Ferry MMSI {mmsi_val} @ {lat},{lon} speed {speed} kn")
if ts_dt:
print(f"Position time (UTC): {ts_dt.astimezone(timezone.utc).isoformat()}")
if route:
print(f"Route: {route.get('departure_port')} → {route.get('destination_port')}")
if eta_dt:
print(f"ETA (UTC): {eta_dt.astimezone(timezone.utc).isoformat()}")
else:
print("ETA not available")
if __name__ == "__main__":
track_ferry("258785000", hours=48)3) Show ferries around a terminal with /vessels/nearby
Use this for terminal boards (“next 5 ferries within 10 NM”), dispatcher maps, or to identify unplanned arrivals near a route segment.
Endpoint
GET /vessels/nearby — Required: latitude, longitude. Optional: radius (default 50 NM, max 200), ship_type, limit.
cURL
Implementation tips:
- Filter client-side for ferry ship_type when rendering a mixed AIS picture.
- Use distance_nm to quick-sort the closest ferries for wharf allocation and berth calls.
- Limit to a small radius for city ferry ops; increase radius when monitoring coastal or inter-island services.
4) Summarize service performance with /vessels/analytics
For operations reviews and schedule planning, you need aggregated stats without running your own rollups.
Endpoint
GET /vessels/analytics — Required: type=vessel|port|fleet. For a single ferry, set type=vessel with imo or mmsi. Optional period=24h|7d|30d|90d.
cURL
Key outputs for transportation teams:
- statistics.total_distance_nm — compare against expected route mileage to spot skipped legs or detours.
- avg_speed_knots and max_speed_knots — check for slowdowns that ripple into missed headways.
- port_calls_count and total_time_in_port_hours — evaluate turnaround efficiency and berth utilization.
- ports_visited — cross-check that the ferry served only authorized terminals.
5) Port context: congestion, catalog and expected arrivals
Terminal conditions directly affect ferry punctuality. Use the port endpoints to add situational awareness around berths and approach channels.
Available endpoints
- GET /ports — Full catalog of 248 ports with identifiers and coordinates.
- GET /ports/data — Detailed info for a single port including live vessel counts.
- GET /ports/congestion — Real-time congestion snapshot and wait-time statistics for a given port_id (UNLOCODE such as ARBUE, SGSIN, NLRTM). Do not infer or invent values; rely on the API output.
- GET /port/expected-arrivals — Vessels expected to arrive at a port, with ETA and origin.
cURL examples
Port catalog:
Port data (single port):
Expected arrivals feed (useful for forewarning a busy terminal team):
Congestion snapshot (integrate as a capacity signal; respect the API’s output as authoritative):
Design notes for reliable transportation apps
- Response envelope: Every endpoint returns {status, success, message, data}. Check success and handle message across all calls consistently.
- Timestamps: Provided as ISO 8601 in UTC (e.g., 2026-04-30T09:00:00+00:00). Convert to local time in the UI only.
- Units: Positions in decimal degrees; distances in nautical miles; speed in knots.
- Freshness: Use current_position.timestamp_utc and age_minutes when deciding whether to alert riders or switch to timetable fallback.
- Pagination: Search endpoints include a pagination object. Always page when building typeahead admin tools.
- Error handling: Align retries with HTTP codes — 400/422 are client errors (fix params), 401 needs a valid X-API-Key, 404 means not found, 429 indicates rate limiting (backoff), 500 is server error (retry with jitter).
- Caching: You can cache /vessels/search results and static port metadata aggressively. For /vessels/track, keep cache very short (seconds) if you need real-time boards.
- Null-safe rendering: predicted_eta, weather, and some route fields may be null depending on signal and coverage; always guard for nulls.
Fleet workflows for ferry operators
If you operate multiple ferries on parallel routes, fetch state for all of them in one call and render a unified board. This reduces client-side fan-out and simplifies concurrency control.
Endpoint
POST /vessels/fleet — Batch positions, routes, and stats for multiple vessels.
cURL
Design it so that each row in your fleet table can render:
- name, imo, mmsi — identity and quick actions.
- position.latitude/longitude, speed_knots — map marker and motion state.
- route.destination_port, route.eta — next stop card.
ESG compliance for public transportation teams
Public ferry services increasingly report emissions performance. If you need a quick view of a ferry’s estimated footprint over the last month, use the green endpoint aligned with IMO CII.
Endpoint
GET /vessels/green — Required: imo OR mmsi. Optional period=24h|7d|30d|1y (default 30d). Ratings A (best) → E (worst) based on IMO MEPC.339(76).
cURL
Use data.cii.rating for a one-letter indicator on route detail pages and data.estimated_emissions.co2_tons in monthly sustainability rollups.
Putting it together: a minimal ferry tracking flow
- Resolve the ferry’s MMSI or IMO with /vessels/search if you don’t already have it.
- Call /vessels/track with mmsi and hours=48, request include_route and include_predicted_eta when you want the ETA model in addition to route’s ETA.
- For terminal context, call /vessels/nearby with the terminal’s lat/lon and a small radius (e.g., 10–20 NM).
- For rider-facing boards, cache /vessels/track for a few seconds to debounce; display ETA in UTC converted to local time zone and show last update age.
- Optionally, schedule /vessels/analytics daily to populate service performance reports.
Explore and integrate faster
- Register to get your API key and start the 7-day trial.
- Read the Documentation for full parameter lists and endpoint details.
- Use the MCP to interactively test requests in a controlled environment.
FAQ
Does /vessels/track include both the active route and a predicted ETA?
Yes. The route object contains the current voyage leg and its ETA. You can also request a separate predicted_eta model output; always handle potential nulls and prefer the most recent field that’s present.
What time zone are timestamps in?
All timestamps are returned as ISO 8601 in UTC (e.g., 2026-04-30T09:00:00+00:00). Convert to the user’s local time zone in your application UI.
How do I filter only ferries with /vessels/nearby?
Use the ship_type filter if you know the ferry classification used in your data. Otherwise, request nearby vessels and filter by ship_type client-side. Always check the position.timestamp_utc age before showing live badges.
What should I do if I receive a 429 rate limit exceeded error?
Back off and retry with jitter. Cache search and static port responses. Keep real-time track polling at a cadence that matches your UI needs and the freshness of AIS updates.
How can I monitor multiple ferries without overloading the client?
Use POST /vessels/fleet to fetch several vessels in a single request. Render your fleet grid from that response and update selectively based on timestamp deltas.
Ship your ferry tracker
With a single X-API-Key and a small set of endpoints, you can search a ferry by name or MMSI, track it live with route and ETA, monitor vessels near a terminal, and roll up analytics for transportation planning. Use the official examples above to plug into your map, rider app, or control room dashboard. When you’re ready, get your key from the Register page and keep the Documentation and MCP handy while you integrate.
