Motor yachts operate on tight schedules and high expectations. Owners, captains, fleet managers, and charter operators all want the same thing: a single source of truth for where a yacht is right now, where it is headed, when it will arrive, what weather lies ahead, and how operations impact emissions and compliance. Building this capability from scratch—ingesting AIS, normalizing positions, predicting ETAs, tracking port activity, and surfacing analytics—takes months. The Motor Yacht Tracking API from vessels-api.com collapses that timeline to minutes with production-grade endpoints that deliver real-time maritime data and analytics out of the box.
Why motor yacht teams need a maritime API now
In modern yacht operations, visibility gaps translate directly into costs and risk:
- Guest logistics and concierge timing hinge on reliable ETAs and last-mile tracking.
- Marina coordination requires insight into congestion and expected arrivals.
- Weather and route deviations need to be captured and analyzed continuously.
- Compliance teams increasingly need emissions estimates and CII scoring.
- Technical teams must unify multiple data sources with reliable uptime and clear SLAs.
The Vessels API addresses these challenges with a globally consistent REST interface. It delivers:
- 18 REST endpoints covering vessel search, live AIS tracking, fleet operations, port intelligence, IMO CII emissions, and a premium real-time AIS feed.
- One base URL with a stable response envelope on every call: {status, success, message, data}.
- Global AIS coverage with near real-time refresh rates and actionable analytics.
- Developer ergonomics: straightforward request patterns, predictable pagination, and JSON contracts that are easy to integrate into existing dashboards and services.
In the rest of this post, we’ll walk through the endpoints and patterns that matter most for motor yacht operations, then expand across the full API surface to show how you can build an end-to-end maritime intelligence stack—from a single motor yacht up to a diversified fleet of tenders and chase boats.
Quick overview: Endpoint map for maritime motor yacht use cases
Below is a categorized map of the endpoints exposed by vessels-api.com that are most relevant for motor yacht tracking and analytics. We’ll go deep on several of these with hands-on examples and realistic responses.
Vessel intelligence
- GET /vessels/search — Search by name, IMO, MMSI; filter by type, flag, DWT, TEU, and build years.
- GET /vessels/track — Live position, historical track (up to 168h), active route, predicted ETA, weather.
- GET /vessels/nearby — Proximity lookup by lat/lon with filters by type and distance radius.
- GET /vessels/analytics — Aggregated voyage analytics by vessel, port, or fleet (24h to 90d).
Fleet operations
- POST /vessels/fleet — Batch routes/positions/stats for multiple vessels in a single request.
- GET /vessels/green — IMO CII emissions scoring for ESG and regulatory workflows.
Port intelligence
- GET /ports/congestion — Real-time congestion and wait-time statistics.
- GET /ports — Full port catalog with coordinates and timezone data.
- GET /ports/data — Detailed port information including live vessel counts.
- GET /port/expected-arrivals — Upcoming arrivals with ETA and origin.
- GET /port/activity — Recent arrivals and departures for event feeds.
Legacy endpoints (stable; use /vessels/ for richer data)
- GET /vessel/info?imo=IMO — Static particulars.
- GET /vessel/route?imo=IMO — Current voyage route.
- GET /vessel/position?imo=IMO — Last known AIS position by IMO.
- GET /vessel/mmsi-position?mmsi=MMSI — Last known AIS position by MMSI.
- GET /vessel/port?port=PORT_ID — Vessels currently at a port.
- GET /vessel/port/mmsi?mmsi=MMSI — Current port call for a vessel by MMSI.
Across all endpoints, responses follow the same high-level JSON structure, which makes client code simpler and error handling predictable.
Core workflow for motor yachts: Track, predict ETA, monitor ports, and analyze voyages
For a high-value motor yacht program, four pillars drive the bulk of daily operations:
- Identification: find the right vessel reliably.
- Tracking: live position, speed, course, and track history.
- Prediction: route understanding and ETA estimates.
- Context: port congestion, expected arrivals, and voyage analytics.
The following sections illustrate how to stitch these pillars together using the most impactful endpoints.
Find and verify the right yacht: GET /vessels/search
The first step is resolving a vessel’s unique identity. Yachts often share similar names; fuzzy matching paired with IMO and MMSI disambiguation is critical. The search endpoint provides robust filters and pagination so your front end can present a confident, narrowed selection to operations staff.
When to use it
- Onboarding a new motor yacht into your dashboard by name, MMSI, or IMO.
- Resolving ambiguous name searches with additional filters like flag or vessel type.
- Building a typeahead UX that suggests the correct yacht in real time.
Request example (cURL)
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/vessels/search?query=MY+Atlantic&flag=Panama&ship_type=Yacht&per_page=5"
Sample JSON response
{
"status": 200,
"success": true,
"message": "OK",
"data": {
"vessels": [
{
"imo": "9654321",
"mmsi": "258785000",
"name": "MY ATLANTIC",
"flag": "Panama",
"vessel_type": "Yacht",
"gross_tonnage": 1450,
"deadweight_tonnage": 320,
"year_built": 2017,
"length_m": 72.0,
"width_m": 13.5
},
{
"imo": "9787654",
"mmsi": "235114400",
"name": "ATLANTIC DREAM",
"flag": "United Kingdom",
"vessel_type": "Yacht",
"gross_tonnage": 980,
"deadweight_tonnage": 210,
"year_built": 2019,
"length_m": 60.2,
"width_m": 11.4
}
],
"pagination": {
"current_page": 1,
"per_page": 5,
"total": 2,
"last_page": 1
}
}
}
Field breakdown and practical tips
- imo/mmsi: Use these as primary identifiers for all subsequent tracking calls.
- vessel_type: Filter for “Yacht” to avoid false positives from commercial shipping.
- length_m/width_m: Useful for marina assignment planning and berth compatibility checks.
- pagination: Drive infinite scroll and “Load more” UX for long result sets.
Implementation guidance
- Debounce user input to minimize requests when building a typeahead.
- Prefer exact MMSI/IMO queries when you have them; fall back to fuzzy name searches otherwise.
- Cache a small profile object (IMO/MMSI/name/flag/length/width) locally to accelerate subsequent interactions.
Real-time motor yacht tracking and route intelligence: GET /vessels/track
This is the operational heartbeat for motor yachts. The tracking endpoint fuses current position with up to 168 hours of historical track, optional route context, predicted ETA, and optional weather. This single call powers your live map, breadcrumb trails, ETA widgets, and alerting systems.
Request example (cURL)
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/vessels/track?mmsi=258785000&hours=48&include_route=true&include_predicted_eta=true&include_weather=true"
Sample JSON response
{
"status": 200,
"success": true,
"message": "OK",
"data": {
"vessel": {
"imo": "9654321",
"mmsi": "258785000",
"name": "MY ATLANTIC"
},
"current_position": {
"latitude": 36.5271,
"longitude": -5.3458,
"speed_knots": 14.2,
"course_degrees": 249,
"heading_degrees": 250,
"navigational_status": "Under way using engine",
"timestamp_utc": "2026-09-14T10:22:40Z",
"destination": "GIBRALTAR",
"eta": "2026-09-14T12:55:00Z"
},
"position_history": [
{
"latitude": 36.7300,
"longitude": -5.1200,
"speed_knots": 15.1,
"course_degrees": 248,
"timestamp_utc": "2026-09-14T08:22:40Z"
},
{
"latitude": 36.9000,
"longitude": -4.8500,
"speed_knots": 12.9,
"course_degrees": 247,
"timestamp_utc": "2026-09-14T06:22:40Z"
}
],
"route": {
"departure_port": "ESAGP",
"departure_time": "2026-09-14T04:05:00Z",
"destination_port": "GIGIB",
"eta": "2026-09-14T12:55:00Z",
"distance_nm": 78.2,
"avg_speed_knots": 13.5
},
"last_port_visits": [
{
"port_id": "ESAGP",
"port_name": "Algeciras",
"arrival_time": "2026-09-13T18:04:10Z",
"departure_time": "2026-09-14T04:05:00Z"
}
]
}
}
Field breakdown and practical tips
- current_position: Drives your live map. Use speed_knots and course_degrees to animate vessel markers.
- position_history: Render breadcrumb trails; enable time scrubbing for ops reviews.
- route: Power ETA cards, distance remaining, and speed advisories for guest transfers.
- last_port_visits: Context for concierge and provisioning teams.
Best practices for yachts
- Use hours to tailor history length (e.g., 24–48h for daily ops; 168h for weekly playback).
- Combine predicted ETA with marina congestion (see ports/congestion) to anticipate berthing delays.
- If weather is included, align safety thresholds (e.g., reduce speed if forecast headwinds exceed a threshold).
JavaScript example: Updating a live map
async function fetchTrack(mmsi) {
const url = new URL("https://vessels-api.com/api/V1/vessels/track");
url.searchParams.set("mmsi", mmsi);
url.searchParams.set("hours", "24");
url.searchParams.set("include_route", "true");
url.searchParams.set("include_predicted_eta", "true");
const res = await fetch(url.toString(), {
headers: { "X-API-Key": "YOUR_API_KEY" }
});
if (!res.ok) {
// Handle errors comprehensively; see error section below.
const err = await res.json().catch(() => ({}));
throw new Error(`Track error: ${res.status} ${JSON.stringify(err)}`);
}
const payload = await res.json();
const data = payload.data;
// Update UI layers.
updateVesselMarker(data.current_position);
drawBreadcrumbs(data.position_history);
updateRouteCard(data.route, data.current_position.eta);
}
fetchTrack("258785000").catch(console.error);
Know what’s around you: GET /vessels/nearby for tenders and traffic awareness
Motor yacht bridges often coordinate with tenders, chase boats, and service vessels. A proximity view supports quick deconfliction and helps security teams maintain situational awareness. It also powers “Meet the yacht” rendezvous UIs for heli, limo tender, or provisioning craft.
Request example (cURL)
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/vessels/nearby?latitude=36.5271&longitude=-5.3458&radius=20&ship_type=Yacht&limit=25"
Sample JSON response
{
"status": 200,
"success": true,
"message": "OK",
"data": {
"center": {
"latitude": 36.5271,
"longitude": -5.3458
},
"radius_nm": 20,
"total": 7,
"vessels": [
{
"imo": "9812345",
"mmsi": "247312900",
"name": "SEA LILY",
"ship_type": "Yacht",
"position": {
"latitude": 36.6001,
"longitude": -5.4002,
"timestamp_utc": "2026-09-14T10:19:20Z"
},
"distance_nm": 4.2,
"speed_knots": 10.8,
"course_degrees": 251,
"navigational_status": "Under way using engine"
}
]
}
}
Practical applications
- Security: Identify unidentified contacts closing within a 10–20 NM ring.
- Rendezvous: Display closest tenders by distance_nm with live bearing/course for intercept planning.
- Ops overlay: Filter ship_type to focus on yachts or service craft depending on the task.
Implementation tips
- Use limit to bound list rendering and map clutter.
- Trigger refreshes at operationally relevant intervals (e.g., every 60–120 seconds) to balance freshness and UI performance.
- Combine with /vessels/track for selected contacts to fetch richer route and ETA data on demand.
Port intelligence for yacht itineraries: congestion, expected arrivals, and activity
Berth availability and port flow can make or break an itinerary. For motor yachts transitioning through busy marinas or commercial ports, a data-driven view ensures smoother arrivals and guest experiences. Three endpoints provide the backbone of this picture: /ports/congestion, /port/expected-arrivals, and /port/activity. The /ports and /ports/data endpoints enrich port selection and context in your UI.
GET /ports/congestion
Use this snapshot to assess anchorage vs berth load and recent wait-time performance.
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/ports/congestion?port_id=ARBUE&period=7d"
{
"status": 200,
"success": true,
"message": "OK",
"data": {
"port_id": "ARBUE",
"port_name": "Buenos Aires",
"period": "7d",
"snapshot": {
"vessels_in_anchorage": 12,
"vessels_at_berth": 18
},
"statistics": {
"avg_wait_time_hours_last_7d": 14.6,
"max_wait_time_hours_last_7d": 36.0,
"avg_berth_time_hours_last_7d": 22.3,
"port_calls_count": 204
}
}
}
- snapshot: Pair with your ETA to inform go/no-go decisions or alternative ports.
- statistics: Expectations management for guests and operations; show likely delays.
GET /port/expected-arrivals
See the upcoming traffic load and identify potential berthing conflicts.
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/port/expected-arrivals?port=ARBUE"
{
"status": 200,
"success": true,
"message": "OK",
"data": {
"port_id": "ARBUE",
"port_name": "Buenos Aires",
"expected_arrivals": [
{
"mmsi": "258785000",
"imo": "9654321",
"name": "MY ATLANTIC",
"vessel_type": "Yacht",
"eta": "2026-09-14T12:55:00Z",
"departure_port": "ESAGP"
}
],
"total": 53
}
}
- expected_arrivals: Build an arrivals board and prioritize docking windows.
- eta: Cross-check with your own /vessels/track ETA for consistency.
GET /port/activity
Generate real-time event feeds for arrivals and departures—ideal for port agents and concierge teams.
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/port/activity?port=ARBUE"
{
"status": 200,
"success": true,
"message": "OK",
"data": {
"port_id": "ARBUE",
"port_name": "Buenos Aires",
"arrivals": [
{
"mmsi": "247312900",
"name": "SEA LILY",
"arrival_time": "2026-09-14T09:35:00Z",
"from_port": "GIGIB"
}
],
"departures": [
{
"mmsi": "258785000",
"name": "MY ATLANTIC",
"departure_time": "2026-09-14T04:05:00Z",
"to_port": "GIGIB"
}
]
}
}
- arrivals/departures: Trigger notifications for ground teams to prepare lines, fuel, and provisions.
- from_port/to_port: Validate itinerary legs and share context with brokers or owners.
GET /ports and GET /ports/data
Use /ports to present a selectable list of destinations, then fetch /ports/data to enrich a port’s detail page with vessel counts and locality info (coordinates, country, timezone) for meeting planners and crew scheduling.
Voyage analytics for motor yachts: GET /vessels/analytics
Analytics turn raw positions into meaningful KPIs. Whether you need a weekly ops review, charter post-mortem, or season summary, the analytics endpoint provides rollups across vessels, ports, or custom fleets. For motor yachts, this is where you quantify distance sailed, time in port vs at sea, and the cadence of port calls.
Vessel-level analytics
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/vessels/analytics?type=vessel&mmsi=258785000&period=7d"
{
"status": 200,
"success": true,
"message": "OK",
"data": {
"type": "vessel",
"mmsi": "258785000",
"imo": "9654321",
"name": "MY ATLANTIC",
"period": "7d",
"statistics": {
"total_distance_nm": 482.6,
"avg_speed_knots": 12.7,
"max_speed_knots": 18.2,
"port_calls_count": 4,
"total_time_in_port_hours": 36.5,
"ports_visited": ["GIGIB", "ESAGP", "ESSCT"]
}
}
}
- total_distance_nm: Charter reporting and maintenance planning (engine hours correlation).
- avg_speed_knots/max_speed_knots: Fuel strategy and comfort thresholds for guests.
- port_calls_count/ports_visited: Season summaries for owners and brokers.
- total_time_in_port_hours: Optimize downtime and provisioning windows.
Port and fleet modes
- type=port with port_id: Understand port demand and refine itineraries.
- type=fleet with mmsi_list: Summarize tender and chase boat utilization alongside the mothership.
Operate multiple yachts and tenders: POST /vessels/fleet
When your program spans the main yacht plus tenders, support boats, or a managed fleet, batch queries cut network overhead and simplify orchestration. With /vessels/fleet, you can grab positions, routes, and rollups in a single payload.
Request example (cURL)
curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{
"vessels": [
{ "imo": "9654321" },
{ "mmsi": "247312900" },
{ "mmsi": "235114400" }
],
"include_positions": true,
"include_routes": true
}' \
"https://vessels-api.com/api/V1/vessels/fleet"
Sample JSON response
{
"status": 200,
"success": true,
"message": "OK",
"data": {
"fleet": {
"total_vessels": 3,
"vessels_at_sea": 2,
"vessels_in_port": 1
},
"vessels": [
{
"imo": "9654321",
"mmsi": "258785000",
"name": "MY ATLANTIC",
"position": {
"latitude": 36.5271,
"longitude": -5.3458,
"speed_knots": 14.2,
"timestamp_utc": "2026-09-14T10:22:40Z"
},
"route": {
"departure_port": "ESAGP",
"destination_port": "GIGIB",
"eta": "2026-09-14T12:55:00Z"
}
},
{
"imo": null,
"mmsi": "247312900",
"name": "SEA LILY",
"position": {
"latitude": 36.6001,
"longitude": -5.4002,
"speed_knots": 10.8,
"timestamp_utc": "2026-09-14T10:19:20Z"
},
"route": null
},
{
"imo": null,
"mmsi": "235114400",
"name": "ATLANTIC DREAM",
"position": {
"latitude": 36.1450,
"longitude": -5.3530,
"speed_knots": 0.0,
"timestamp_utc": "2026-09-14T10:10:00Z"
},
"route": {
"departure_port": "GIGIB",
"destination_port": "GIGIB",
"eta": null
}
}
]
}
}
Usage patterns
- Single-screen fleet map showing the mothership, tenders, and escorts.
- Ops widget summarizing vessels_at_sea vs vessels_in_port to plan crew shifts.
- Batch refresh in background workers to keep dashboards snappy.
ESG and compliance for yachts: GET /vessels/green (IMO CII)
While many motor yachts are below thresholds that mandate exhaustive reporting, owners and managers increasingly track emissions for transparency and sustainability. The CII endpoint calculates distance, estimated CO2, and a rating aligned with IMO MEPC.339(76). It’s ideal for seasonal summaries and voluntary disclosure.
Request example (cURL)
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/vessels/green?mmsi=258785000&period=30d"
Sample JSON response
{
"status": 200,
"success": true,
"message": "OK",
"data": {
"imo": "9654321",
"mmsi": "258785000",
"name": "MY ATLANTIC",
"period": "30d",
"distance_nm": 1820.4,
"estimated_emissions": {
"co2_tons": 96.3,
"co2_per_nm": 0.053
},
"cii": {
"score": 0.92,
"rating": "B",
"year": 2026,
"regulation_reference": "IMO MEPC.339(76)"
}
}
}
How to use these fields
- distance_nm: Cross-check against analytics totals to validate voyage modeling.
- estimated_emissions: Visualize CO2 trends; benchmark routes and operating speeds.
- rating: Provide an easy-to-understand grade for stakeholders.
Legacy endpoints: When a lightweight call is enough
Legacy endpoints offer minimal, focused data for fast-loading widgets and health checks. While the richer /vessels/ suite is recommended for most new builds, these remain stable and useful:
- /vessel/info — static particulars for quick reference cards.
- /vessel/position or /vessel/mmsi-position — heartbeat pings to verify connectivity.
- /vessel/route — rapid route-only card without track history.
- /vessel/port and /vessel/port/mmsi — quick lookups for current port presence.
Practical use: ping /vessel/mmsi-position every few minutes in a background worker to update a “Last seen” badge, while the main dashboard uses /vessels/track for full context on demand.
End-to-end implementation blueprint for motor yacht apps
Below is a reference architecture and practical guidance to build robust, responsive yacht applications with vessels-api.com.
Data flow and routing
- Client apps (bridge tablets, shore dashboards) call a thin backend that fans out to selected endpoints: /vessels/track for the focused yacht, /vessels/fleet for batch updates, and port endpoints for context.
- Implement regional routing and DNS-level health checks to minimize latency from the yacht’s current theater of operations (e.g., Med vs Caribbean seasons).
- Use circuit breakers in your backend: on transient errors, fall back to last-known-good cache for maps and ETAs.
Retries, backoff, and observability
- Apply exponential backoff for 5xx responses with jitter; bound retries to preserve UI responsiveness.
- Instrument response times and payload sizes; monitor how include_route, include_weather, or long history windows affect latency.
- Log the standard envelope fields {status, success, message} for consistent alerting and structured analytics.
Governance and controls
- Issue per-app or per-device credentials in your own backend to maintain least-privilege and auditability.
- Maintain role mapping to determine which UI surfaces can access fleet-wide views vs a single yacht.
- Implement data locality controls by region in your infrastructure to meet internal governance requirements.
Performance patterns
- Cache /ports and /ports/data since they change less frequently than live tracks.
- Fetch /vessels/track on an interval aligned to operational tempo; reduce hours to speed up responses when historical detail isn’t needed.
- Use /vessels/fleet for initial dashboard hydration; follow with targeted /vessels/track calls only when a user drills down.
Python example: A minimal backend poller
import os
import time
import json
import requests
API_KEY = os.getenv("VESSELS_API_KEY")
BASE = "https://vessels-api.com/api/V1"
def get_track(mmsi, hours=24):
params = {
"mmsi": mmsi,
"hours": str(hours),
"include_route": "true",
"include_predicted_eta": "true"
}
r = requests.get(f"{BASE}/vessels/track", headers={"X-API-Key": API_KEY}, params=params, timeout=15)
if r.status_code != 200:
raise RuntimeError(f"Track error {r.status_code}: {r.text}")
return r.json()["data"]
def get_port_congestion(port_id):
r = requests.get(f"{BASE}/ports/congestion", headers={"X-API-Key": API_KEY}, params={"port_id": port_id, "period": "7d"}, timeout=15)
if r.status_code != 200:
raise RuntimeError(f"Congestion error {r.status_code}: {r.text}")
return r.json()["data"]
def loop():
while True:
try:
track = get_track("258785000", hours=24)
congestion = get_port_congestion("GIGIB")
payload = {"track": track, "congestion": congestion}
# Persist to cache or publish to WebSocket bus
print(json.dumps(payload)[:500])
except Exception as e:
print(f"Poller error: {e}")
time.sleep(60)
if __name__ == "__main__":
loop()
Error handling and troubleshooting
All endpoints use a consistent response envelope and standard HTTP status codes. Your client should inspect both the HTTP status and the JSON envelope for robust handling.
Common status codes
- 200: OK — Proceed to parse data.
- 400: Missing/invalid parameter — Check query/body; validate types and required fields.
- 401: Invalid or missing X-API-Key — Ensure correct headers are present in requests.
- 404: Vessel/port not found — Confirm IMO/MMSI/port_id identifiers; fall back to /vessels/search.
- 422: Parameter out of range — For example, radius beyond max in /vessels/nearby or per_page > 100.
- 429: Rate limit exceeded — Back off and retry later; cache results to reduce bursts.
- 500: Server error — Retry with exponential backoff and jitter; use last-known-good cache.
Defensive parsing
- Check data presence before rendering (e.g., route may be null for stationary vessels).
- Use timestamp_utc for time math; display in the yacht or port’s timezone as needed.
- Handle partial results gracefully; position_history may be short for recently activated transponders.
Validation and testing
- Write schema validators for the standard envelope and core data objects (positions, routes, analytics).
- Create synthetic tests for edge ports and high-traffic marinas where congestion and activity change rapidly.
- Test long-hour windows (e.g., hours=168) for performance; measure payload sizes in your environment.
Advanced scenarios for motor yachts
Concierge ETA orchestration
- Use /vessels/track with include_predicted_eta to drive guest pickup timing.
- Cross-reference with /ports/congestion to adjust for likely anchorage hold times.
- Alert ground teams via your messaging bus when ETA drifts beyond a threshold.
Security and close-range coordination
- Poll /vessels/nearby around the yacht’s latest known position to create a dynamic contact picture.
- Filter by ship_type to focus on small craft; flag unknowns for watchstander attention.
- On selection, fetch /vessels/track for that contact to get directionality and potential intercept.
Season wrap-up reporting
- Aggregate /vessels/analytics for the yacht and its tenders over 90 days.
- Pull /vessels/green for a sustainability section with distance and CO2 breakdowns.
- Enrich with /port/activity highlights for marquee arrivals and departures on a timeline.
Full endpoint catalog: Purposes and business value
For completeness, here’s a consolidated view of every endpoint and how it maps to motor yacht operations and supporting apps:
- GET /vessels/search — Onboarding and identity resolution. Business value: accuracy in tracking and reduced ops confusion.
- GET /vessels/track — Live/past position, route, ETA, weather. Business value: real-time decisions and improved guest experience.
- GET /vessels/nearby — Situational awareness. Business value: safety and rendezvous efficiency.
- GET /vessels/analytics — KPIs: distance, speed, port calls, time in port. Business value: performance reviews and planning.
- POST /vessels/fleet — Batch view for yachts, tenders, and chase boats. Business value: operational simplicity and faster dashboards.
- GET /vessels/green — Emissions estimates and CII rating. Business value: ESG transparency and owner communications.
- GET /ports/congestion — Real-time load and wait times. Business value: berth strategy and risk reduction.
- GET /ports — Port catalog for itinerary planning. Business value: quick discovery and UI enrichment.
- GET /ports/data — Detailed port profile with live vessel counts. Business value: operational context for scheduling and services.
- GET /port/expected-arrivals — Forward-looking port load. Business value: avoiding conflicts and timing arrivals.
- GET /port/activity — Event feed for arrivals and departures. Business value: live ops visibility and logs.
- Legacy: /vessel/info, /vessel/route, /vessel/position, /vessel/mmsi-position, /vessel/port, /vessel/port/mmsi — Lightweight utilities for specific widgets and health checks.
Putting it all together: Practical UI composition
- Top bar: Yacht identity from /vessels/search (cached) with length, flag, and year built.
- Main map: /vessels/track current_position + position_history; dotted breadcrumb line; course vector ahead.
- Right rail: Route card with destination, distance_nm, avg_speed_knots from /vessels/track.route.
- ETA module: Predicted ETA with port congestion risk indicator from /ports/congestion.
- Nearby panel: /vessels/nearby list filtered to “Yacht” and “Service” craft; click-through to quick track.
- Analytics tab: /vessels/analytics 7d rollup; sparkline of speed; cumulative distance and port calls.
- ESG tab: /vessels/green 30d snapshot with rating; CO2 per NM trend line.
- Port intel tab: /port/expected-arrivals and /port/activity timeline; /ports/data overview card.
- Fleet view: /vessels/fleet to show mothership + tenders; summary chips for at-sea vs in-port.
Security, reliability, and operational excellence in maritime apps
Motor yacht solutions must work in bandwidth-constrained, mobile, and occasionally disconnected scenarios. Design for resilience:
- Adopt an offline-first cache for last-known position and ETA; expire gracefully with user messaging.
- Use a streaming transport within your app (e.g., WebSockets) to broadcast API updates to multiple panels.
- Implement a watchdog that compares timestamp_utc with system time and warns when AIS data is stale.
- Roll out health checks that call a lightweight endpoint (e.g., a legacy /vessel/mmsi-position) on an interval to validate connectivity.
- Maintain audit logs for critical transitions (e.g., port arrival) using the consistent {status, success, message} envelope to simplify parsing.
Frequently asked developer questions
How often should I refresh tracking data?
For bridge displays and live ops, 30–120 seconds is typical. Choose shorter intervals during arrivals or security-sensitive maneuvers. For background dashboards, 2–5 minutes balances freshness and compute.
Should I use IMO or MMSI?
Use whichever you have reliably. MMSI is common in AIS workflows; IMO is more static and globally unique. The /vessels/search endpoint helps reconcile when you only have a name.
How do I visualize historical tracks efficiently?
Limit hours to a contextually relevant window (e.g., 24h) and resample points client-side if necessary. Render breadcrumbs with reduced opacity and show speed or course changes as color bands or arrows.
End-to-end JSON integration example: From search to live ETA to port context
The following quick script demonstrates the flow of resolving a yacht by name, pulling its track and ETA, and overlaying port congestion so an ops tool can surface an arrival risk indicator.
async function yachtEtaWithPortRisk(name, portId) {
// 1) Resolve the vessel
const sUrl = new URL("https://vessels-api.com/api/V1/vessels/search");
sUrl.searchParams.set("query", name);
sUrl.searchParams.set("ship_type", "Yacht");
const sRes = await fetch(sUrl, { headers: { "X-API-Key": "YOUR_API_KEY" }});
if (!sRes.ok) throw new Error("Search failed");
const sData = (await sRes.json()).data;
if (!sData.vessels.length) throw new Error("Yacht not found");
const mmsi = sData.vessels[0].mmsi;
// 2) Get live track + ETA
const tUrl = new URL("https://vessels-api.com/api/V1/vessels/track");
tUrl.searchParams.set("mmsi", mmsi);
tUrl.searchParams.set("include_route", "true");
tUrl.searchParams.set("include_predicted_eta", "true");
const tRes = await fetch(tUrl, { headers: { "X-API-Key": "YOUR_API_KEY" }});
if (!tRes.ok) throw new Error("Track failed");
const track = (await tRes.json()).data;
// 3) Port congestion
const cUrl = new URL("https://vessels-api.com/api/V1/ports/congestion");
cUrl.searchParams.set("port_id", portId);
cUrl.searchParams.set("period", "3d");
const cRes = await fetch(cUrl, { headers: { "X-API-Key": "YOUR_API_KEY" }});
if (!cRes.ok) throw new Error("Congestion failed");
const congestion = (await cRes.json()).data;
return { track, congestion };
}
// Example usage:
yachtEtaWithPortRisk("MY Atlantic", "GIGIB")
.then(res => console.log(JSON.stringify(res, null, 2)))
.catch(console.error);
Performance tuning and payload economics
- Scope responses: Only request optional fields you need (e.g., include_route, include_weather) to keep payloads lean.
- Temporal windows: Smaller hours windows in /vessels/track return faster and render quicker on mobile.
- Spatial bounds: Limit in /vessels/nearby prevents overdraw and UI overload.
- Batch wisely: Use /vessels/fleet to hydrate a dashboard once, then switch to incremental calls.
Key developer takeaways
- One consistent JSON contract across endpoints accelerates client development and testing.
- Real-time tracking plus analytics and port intelligence solves end-to-end operational needs for motor yachts.
- The API’s breadth—search, live AIS, fleet, ports, analytics, and CII—means fewer external dependencies, lower integration risk, and faster delivery.
Build your motor yacht solution with vessels-api.com
Whether you are integrating a live bridge display, building a guest-facing charter tracker, streamlining marina coordination, or assembling a season-long operational review, vessels-api.com gives you the maritime building blocks you need—reliable AIS data, robust analytics, and port intelligence in a single, developer-friendly platform.
Explore the docs and start composing your application today:
Bring your design, we’ll bring the maritime data. Together, we can deliver real-time visibility, operational reliability, and guest-grade experiences for motor yachts anywhere in the world.
