Yacht Tracking API: Fleet Positions and Analytics

You manage a yacht fleet and need live positions, route plans, and voyage analytics you can plug straight into dashboards, dispatch tooling, or guest-facing apps. By the end of this guide you’ll query live AIS positions, compute per-yacht and fleet-level voyage stats, surface nearby traffic around an anchorage or regatta course, and batch-update fleet tiles — all using a single REST API and one API key.

What you’ll build with the yacht tracking API

Using the Vessels API, you can:

• Show live yacht positions with up to 168 hours of track history, route, and ETA.
• Pull voyage analytics (distance sailed, average/max speed, port calls) for operations and guest reporting.
• Batch-update your fleet map in one request to reduce round-trips and UI latency.
• Scan nearby traffic around an anchorage or racecourse to augment safety overlays.

Everything runs over a single base URL (https://vessels-api.com/api/V1) with the X-API-Key header. Responses share the same JSON envelope: {"status","success","message","data"} — making it straightforward to standardize error handling and parsing across endpoints.

Why developers use Vessels API for yacht tracking

• 18 REST endpoints across live AIS tracking, fleet ops, search, port intelligence, and IMO CII emissions scoring.
• One API key, one base URL — no OAuth flows or per-endpoint auth quirks.
• Consistent JSON response envelope across endpoints for predictable parsing.
• Global AIS coverage with near real-time refresh cadence.
• 7-day free trial on all plans and scaling paths from indie yacht apps to enterprise fleet ops.

Audience fit: developers building marine apps, yacht management platforms, fleet managers, port operators, and ESG/compliance teams.

Explore the reference: Documentation, register for an API key: Register, and test capabilities via the MCP: MCP.

Core endpoints for yacht fleets

For yachts, the high-leverage set is:

• GET /vessels/track — live position, optional route, predicted ETA, weather, and history (up to 168 hours).
• POST /vessels/fleet — batch positions/routes/stats for multiple yachts in one call.
• GET /vessels/nearby — traffic density and identities within N miles of a location.
• GET /vessels/analytics — aggregated voyage statistics (vessel, port, or fleet mode).

We’ll deep-dive these four and wire them into a simple yacht dashboard flow.

Live yacht tracking with history, route, and ETA

Use GET /vessels/track to retrieve:

• current_position: latest AIS fix with position and kinematics.
• position_history: up to 168 hours when hours is provided (default 24).
• route: departure/destination, ETA, distance, and average speed.
• predicted_eta: model-derived ETA when available (enable include_predicted_eta).
• weather: optional weather layer (enable include_weather).

Required parameter: one of imo or mmsi. Optional parameters include hours (max 168), include_route, include_predicted_eta, include_weather.

Official sample: copy-paste cURL

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

Official sample JSON (unchanged)

{
"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:30+00:00",
"age_minutes": 5094500,
"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
}
}

Fields you’ll commonly render:

• data.vessel.mmsi, data.vessel.imo, data.vessel.name — identity for labeling markers.
• data.current_position.latitude/longitude — map pin location; timestamp_utc is ISO 8601 in UTC.
• data.current_position.speed_knots/course_degrees/heading_degrees — speed (knots) and headings (degrees true).
• data.route.eta — planned ETA for logistics or guest timing; route is included in the response.
• data.last_port_visits — helpful for ops summaries and compliance logs.

Python example: render a yacht marker and ETA

import requests
from datetime import datetime, timezone

API_KEY = "YOUR_API_KEY"
URL = "https://vessels-api.com/api/V1/vessels/track"

params = {
"mmsi": "258785000",
"hours": "48" # up to 168
}

headers = {
"X-API-Key": API_KEY
}

resp = requests.get(URL, params=params, headers=headers, timeout=20)
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"]
route = data.get("route", {})

lat = pos["latitude"]
lon = pos["longitude"]
speed = pos["speed_knots"]
course = pos["course_degrees"]
fix_time = pos["timestamp_utc"] # UTC ISO 8601

eta = (route or {}).get("eta")
name = vessel.get("name") or vessel["mmsi"]

print(f"Marker: {name} at {lat:.5f},{lon:.5f} | {speed} kn @ {course}°")
print(f"Fix time (UTC): {fix_time}")
print(f"Planned ETA: {eta if eta else 'N/A'}")

Tips:

• Use hours=24 to 168 when you need a breadcrumb trail for post-race analysis. Keep it lower (e.g., 6–12) for snappier payloads in live dashboards.
• All timestamps are UTC; format them in your user’s local timezone in the UI.
• If you poll on an interval, prefer conditional updates and client-side throttling. Many yacht dashboards poll every 30–60 seconds while underway and back off at anchor.

Batch fleet updates with one request

When rendering multiple yachts simultaneously (e.g., a management dashboard), round-tripping each yacht’s track wastes time and bandwidth. Use POST /vessels/fleet to retrieve positions and routes for many vessels in one call.

Request

Illustrative response snippet

Implementation notes for yachts:

• identity: Each vessel may be referenced by either IMO or MMSI; provide whichever you have per hull.
• include_positions/include_routes: set both true for full map tiles with route ribbons and ETAs.
• UI batching: Poll /vessels/fleet every 30–60 seconds while at sea and slow down to 5–10 minutes while berthed.

Nearby traffic around an anchorage or racecourse

Use GET /vessels/nearby to visualize surrounding vessels within a radius (nautical miles) of any coordinate. This helps with collision-avoidance layers and spectator boat awareness during regattas.

Request

Illustrative response snippet

Developer tips:

• radius: defaults to 50 NM, max 200 NM; keep it tight (5–15 NM) for local anchorage views.
• limit: cap to your map’s clustering budget; 50 is a good default for high-zoom tiles.
• ship_type filter: when you only want yachts/sailing vessels, pass ship_type=Sailing to reduce noise.

Voyage analytics for post-cruise reporting

Use GET /vessels/analytics for summary statistics across a selected period. Modes:

• type=vessel with mmsi or imo
• type=port with port_id
• type=fleet with mmsi_list (comma-separated)

Per-yacht weekly analytics

Illustrative response snippet

Use cases:

• Charter wrap-ups: generate a PDF/HTML report with distance sailed, ports visited, and average speed.
• Ops KPIs: track utilization and time-in-port across a fleet to optimize scheduling and maintenance windows.
• Guest experience: recap highlights on onboard screens with maps and voyage stats.

Putting it together: a minimal yacht dashboard flow

Here’s a pragmatic way to wire these endpoints for a production-grade yacht dashboard.

1. Identity sync:
   • Persist per-yacht MMSI and optional IMO in your database. The /vessels/search endpoint is available when you need to resolve an MMSI or name with fuzzy match.
2. Fleet loop (server-side cron or WebSocket publisher):
   • Every 30–60s while underway, call POST /vessels/fleet with include_positions=true and include_routes=true for all active yachts.
   • Publish only changed markers to clients (compare by mmsi and timestamp_utc to skip stale frames).
3. Detail panel:
   • On vessel selection, call GET /vessels/track?mmsi=...&hours=24 to hydrate the detail drawer with breadcrumb history and ETA.
   • For performance, memoize the 24h trail in session state and update with only the latest fix on subsequent polls.
4. Safety overlay:
   • On high zoom levels, query GET /vessels/nearby around the active yacht’s position with radius=5–10 NM and limit=50.
   • Cluster markers and draw CPA/TCPA heuristics if desired (course_degrees + speed_knots).
5. Weekly report:
   • On Mondays, batch over your hulls and call GET /vessels/analytics?type=vessel&period=7d for each yacht to build e-mail or dashboard cards.

Error handling, consistency, and performance notes

• Authentication: Always pass X-API-Key in the request header.
• Response envelope: Parse {"status","success","message","data"} consistently. status mirrors HTTP (e.g., 200, 400, 401, 404, 422, 429, 500).
• Timezones: All timestamps are UTC in ISO 8601 format. Convert on the client for user locale.
• Units: Distances are nautical miles (nm); speeds in knots (kn); bearings in degrees true.
• Pagination: /vessels/search supports page/per_page (max 100). Batch flow (/vessels/fleet) removes most pagination concerns for live maps.
• Polling and caching: Poll faster at sea and back off at anchor/berth. Use ETags/If-None-Match if you front your calls with an edge proxy; otherwise cache payloads client-side keyed by mmsi+timestamp_utc.
• Input validation: Handle 400/422 for missing/invalid parameters or out-of-range values (e.g., radius > 200 NM on /vessels/nearby).
• Rate limiting: On 429, implement exponential backoff and jitter. Use the fleet endpoint to minimize call volume.

Optional: sustainability and compliance signals for larger yachts

For superyachts and support vessels, GET /vessels/green returns estimated CO2 emissions and IMO CII ratings (A→E) over a period (default 30d). This can be useful for internal sustainability dashboards or when interacting with marinas and events that request impact metrics.

Note: Not all yachts are subject to CII regulation; use this as an internal KPI unless rules apply.

Security and deployment checklist

• Never commit YOUR_API_KEY to source control. Inject via server-side environment variables.
• Call the API server-side whenever practical. If calling from the browser, proxy through your backend.
• Log the API’s status and message fields alongside your request IDs to streamline support and debugging.
• Normalize positions to a single precision (e.g., 5–6 decimals) for deterministic diffing in WebSocket streams.

Common pitfalls and how to avoid them

• Confusing course_degrees with heading_degrees: course is track over ground; heading can be null when not broadcast or stationary.
• Ignoring navigational_status: treat “at anchor” or “moored” as low-frequency polling states to reduce noise.
• Overfetching history: keep hours tight for live UIs; fetch longer histories only for analysis pages.
• Underusing /vessels/fleet: your map will feel snappier when you batch.

FAQ

Q: How do I authenticate?
A: Include your key in the X-API-Key header for every request. There’s no OAuth — one key works across all endpoints.

Q: What’s the update cadence for live positions?
A: Positions are refreshed on a near real-time AIS cadence. Poll every 30–60s while underway for a responsive map, and back off while berthed or at anchor.

Q: How far back can I fetch history with /vessels/track?
A: Up to 168 hours using the hours parameter. The default is 24 hours.

Q: Can I query multiple yachts in one request?
A: Yes. Use POST /vessels/fleet with a vessels array containing MMSIs and/or IMOs. Set include_positions and include_routes per your needs.

Q: What errors should I handle?
A: 400 for invalid/missing parameters, 401 for missing/invalid X-API-Key, 404 when a vessel or port isn’t found, 422 for out-of-range inputs (e.g., radius), 429 when rate-limited, and 500 for server errors.

Next steps

If you’re building yacht maps, race viewers, or fleet ops dashboards, wire up the four endpoints covered here and you can ship a credible MVP in hours. The API surface is consistent, the JSON envelope is predictable, and you’ll avoid bespoke integrations. Get your key and start testing with the official examples:

• Register
• Documentation
• MCP