API to Track a Naval Vessel

You need to programmatically track a naval vessel in near real time, build situational awareness around its last known position, and stitch that into fleet dashboards and alerting. By the end of this guide you’ll query live AIS positions, retrieve recent voyages and routes, scan an area for nearby traffic, and roll up multi-ship telemetry for operational views using a consistent REST API.

What you’ll build with Vessels API

vessels-api.com provides a single, consistent REST surface for vessel search, live AIS tracking, fleet operations, and analytics. All endpoints share the same base URL and authentication method, return a uniform JSON envelope, and are designed to be called directly from backends, cron jobs, or serverless functions.

• Base URL: https://vessels-api.com/api/V1
• Authentication: X-API-Key header (X-API-Key: YOUR_API_KEY)
• Consistent envelope: {"status", "success", "message", "data"}
• 18 REST endpoints spanning vessel intelligence, fleet ops, and port intelligence
• Global AIS coverage with near real-time refresh

Reference: Documentation, MCP. When you’re ready to integrate, Register.

Core endpoints for tracking a naval vessel

For naval use cases, prioritize:

• /vessels/track — live position, history (up to 168h), route, ETA, and last port visits
• /vessels/nearby — area scan by lat/lon and radius to build a local COP (common operational picture)
• /vessels/fleet — batch calls to reduce round-trips and power dashboards
• /vessels/analytics — aggregated voyage stats for mission debriefs and KPIs
• /vessels/search — bootstrap by name/IMO/MMSI if you only know a callsign or fuzzy name

1) Live tracking for a single naval vessel

Use GET /vessels/track with either an IMO or MMSI. You can request up to 168 hours of history, and optionally include route, predicted ETA, and weather overlays.

Official cURL sample (copy/paste)

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

Official JSON sample (exact fixture)

{
"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": 5114721,
"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 to use immediately:

• data.current_position.latitude/longitude — plot point on your map (WGS84). Units are decimal degrees.
• data.current_position.speed_knots — SOG in knots (kt). Useful for alerts (e.g., “dead in water”).
• data.current_position.course_degrees — COG in degrees (0–359). Overlay a vector on your UI.
• data.current_position.timestamp_utc — ISO 8601 UTC timestamp. Use for clock skew and recency checks.
• data.route — current voyage snapshot with departure/destination ports and ETA (if available).
• data.last_port_visits — recent port calls for context and audit trails.

Notes:

• hours: supports up to 168 for one-week trails; default is 24.
• Timestamps are UTC; do not localize server-side unless your UI requires it.
• Set include_route, include_predicted_eta, and include_weather when you need them; omit to minimize payload.

Python example: Fetch and map critical fields

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_vessel(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, headers=headers, params=params, timeout=20)
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")
cog = pos.get("course_degrees")
ts = pos.get("timestamp_utc")
# Parse the ISO 8601 if present
ts_dt = datetime.fromisoformat(ts.replace("Z", "+00:00")) if ts else None
return {
"mmsi": data.get("vessel", {}).get("mmsi"),
"imo": data.get("vessel", {}).get("imo"),
"lat": lat,
"lon": lon,
"speed_knots": speed,
"course_degrees": cog,
"timestamp_utc": ts_dt.astimezone(timezone.utc).isoformat() if ts_dt else None,
"route": data.get("route"),
"last_ports": data.get("last_port_visits", []),
}

if __name__ == "__main__":
snapshot = track_vessel("258785000", hours=48)
print(snapshot)

2) Scan the operating area around a naval unit

To build a live operational picture around a naval vessel (e.g., 50–200 NM bubble), use GET /vessels/nearby. Pass the center latitude/longitude and an optional radius in nautical miles.

Official cURL sample:

Key output fields to wire up:

• data.vessels[].position.latitude/longitude/timestamp_utc — plot contacts and annotate freshness.
• data.vessels[].ship_type — filter civilian/commercial traffic vs. unknowns.
• data.vessels[].distance_nm — prioritize closest contacts for on-screen focus or alerts.
• data.radius_nm and data.center — helpful for verifying your search scope on the map.

Tips:

• Use limit to control payload and rendering performance; default is 50.
• If you already know the own-ship position from /vessels/track, center your /vessels/nearby query on that coordinate.

3) Batch calls for naval fleet dashboards

When monitoring multiple naval assets, round-trip latency matters. POST /vessels/fleet returns positions, routes, and rollups for a list of vessels in one call. Send IMO or MMSI per vessel object and choose which sections to include.

Official cURL sample:

Key output fields to plug into your dashboard widgets:

• data.fleet.total_vessels, vessels_at_sea, vessels_in_port — headline KPIs.
• data.vessels[] — roll through and draw each asset’s marker, route, or status badge.

Design consideration: If you’re updating frequently (e.g., 10–60 seconds), cache immutable parts (e.g., vessel particulars) and only repaint deltas from the latest response to reduce UI churn.

4) Mission analytics and debriefs

GET /vessels/analytics aggregates voyage and activity statistics. For naval tracking, this helps quantify patrol distance, average speed, and port call cadence across time windows.

Official cURL sample:

Key output fields:

• data.statistics.total_distance_nm — total sailed distance across the period (nautical miles).
• data.statistics.avg_speed_knots and max_speed_knots — for performance baselines.
• data.statistics.port_calls_count, total_time_in_port_hours, ports_visited — operational tempo.

Other modes you can switch to:

• type=port with port_id for port-focused rollups
• type=fleet with mmsi_list for multi-vessel aggregation

5) Bootstrap tracking: find a naval vessel by ID or fuzzy name

If you have a partial name or a callsign scribble, start with GET /vessels/search. You can filter by ship_type and flag when needed and paginate through matching candidates.

Official cURL sample:

Response fields worth storing server-side for de-duplication and joins:

• imo and mmsi — your stable identifiers for subsequent calls
• name, flag, vessel_type — for UI labeling and filters
• pagination — build paging UI; per_page max is 100

Response envelope, units, and error handling

Every endpoint returns the same top-level envelope so your client can centralize success checks and error parsing:

• status: HTTP-like integer (e.g., 200)
• success: boolean
• message: human-readable
• data: object with endpoint-specific payload

Units and formats:

• Coordinates: decimal degrees (WGS84)
• Speed: knots
• Course/Heading: degrees (0–359)
• Distances: nautical miles (nm)
• Timestamps: ISO 8601 in UTC (e.g., 2026-04-27T21:35:36+00:00)

Error codes to handle explicitly:

• 400: Missing/invalid parameter
• 401: Invalid or missing X-API-Key
• 404: Vessel/port not found
• 422: Parameter out of range (e.g., hours > 168)
• 429: Rate limit exceeded
• 500: Server error

Implementation tips:

• Retry idempotent GETs on 500 with exponential backoff; do not retry 4xx without changing inputs.
• When polling, respect data.current_position.timestamp_utc to avoid treating stale AIS as fresh.
• If a field is null (e.g., heading_degrees), guard your UI renderers to prevent NaN vectors.

Composing a naval operational view

Step 1: Identify or verify the target

Call /vessels/search to confirm MMSI/IMO. Save the chosen ID in your system of record.

Step 2: Pull the live position and route

Use /vessels/track with hours=24–48 for short trails. Plot data.current_position as the marker, draw a short COG vector from course_degrees, and breadcrumb the last N points in position_history if included. Show route.destination_port and route.eta when present.

Step 3: Generate a local COP

Feed /vessels/nearby with the own-ship’s coordinate. Set radius from 30–100 NM depending on your mission profile. Display distance_nm as contact labels and filter by ship_type where appropriate.

Step 4: Roll up multi-asset views

For multiple vessels, switch to /vessels/fleet to reduce per-asset polling. Track the derived KPIs (vessels_at_sea vs. vessels_in_port) as dashboard badges and trigger alerts when a unit transitions.

Step 5: Analyze tempo

For mission recap, call /vessels/analytics with period=7d or 30d. Chart total_distance_nm and avg_speed_knots across time; summarize port_calls_count to understand port dwell vs. underway ratio.

Security, caching, and performance notes

• Always pass your API key via the X-API-Key header. Do not expose it in client-side code.
• For serverless or cron polling, set timeouts and circuit breakers. Cache last successful payload per vessel for graceful degradation.
• Normalize timestamps to UTC in your backend and localize only in the presentation layer.
• Use pagination fields on /vessels/search to stream results to your UI rather than fetching large pages.
• Batch where possible via /vessels/fleet to minimize latency and cost of coordination.

End-to-end example workflow

1. Search the vessel by name or confirm identifiers:
2. Track it live (48-hour context):
3. Scan nearby contacts around the last known coordinate (choose your own center/radius):
4. When monitoring more than one naval unit, switch to batch:
5. Generate mission-level stats for debrief:

Common integration pitfalls to avoid

• Confusing course_degrees (COG) with heading_degrees. Heading may be null; COG is typically sufficient for vector drawing.
• Assuming ETA is always present. Use route.eta and predicted_eta defensively; null means unknown or unavailable.
• Over-polling without checking age_minutes. If age is high, treat the position as stale and back off polling or mark as “AIS silent.”
• Mixing units. All distances are nautical miles; do not convert to km unless you annotate your UI.

FAQs

Q: Which identifier should I prefer: IMO or MMSI?
A: Use whatever you have. MMSI is common for radio/AIS workflows; IMO is stable across the vessel’s life. All relevant endpoints accept either IMO or MMSI for a single vessel.

Q: How fresh is the AIS data?
A: The platform provides global AIS coverage with near real-time refresh. Use current_position.timestamp_utc and age_minutes to judge the recency for each report.

Q: What’s the max lookback for position history?
A: The hours parameter on /vessels/track supports up to 168 (seven days). The default is 24.

Q: How do I reduce request overhead for multiple vessels?
A: Use POST /vessels/fleet to batch positions and routes for multiple assets in one call. Include only the sections you need (e.g., include_positions) to optimize payload size.

Q: How are errors communicated?
A: Check the standard envelope (status, success, message). On non-2xx HTTP responses, the body will include message; handle 400/401/404/422/429/500 distinctly as per your retry and UX strategy.

Next steps

Build your naval tracking integration against a single base URL with consistent JSON and global AIS coverage. Explore endpoints in the Documentation, try live calls in the MCP, and get your key to start shipping: Register.