Naval Vessel Tracking API: Search, Track and Nearby

Your team needs an API that can search naval vessels by identity, stream live AIS positions with history, and detect nearby traffic around a patrol area—all in one consistent interface. By the end of this guide, you will be able to integrate vessels-api.com to build a naval operations dashboard that searches assets, tracks live positions with route context, and queries nearby vessels around any lat/lon within a few lines of code.

Why developers use vessels-api.com for naval tracking

vessels-api.com is a single, developer-friendly REST API that exposes 18 endpoints for vessel search, live AIS tracking, fleet operations, port intelligence, and IMO CII emissions scoring. You authenticate once with X-API-Key and hit one base URL. Every response returns the same JSON envelope: {status, success, message, data}. Coverage is global with near real-time refresh rates, and the platform scales from prototyping to enterprise operations. There’s a 7-day free trial on all plans.

• Base URL: https://vessels-api.com/api/V1
• Auth: X-API-Key header only (no OAuth)
• Response envelope: {status, success, message, data} on every endpoint
• Focus of this post: /vessels/search, /vessels/track, /vessels/nearby, plus /vessels/analytics for mission reporting

Core workflow for naval operations

1. Identify a vessel of interest (VOI) using /vessels/search by name, IMO, or MMSI.
2. Stream live positioning, view up to 168h history, and inspect active route with /vessels/track.
3. Scan the patrol area for nearby contacts using /vessels/nearby, filtering by ship_type if needed.
4. Summarize operational tempo (distance, speed, port calls) via /vessels/analytics for post-mission reports.

1) Search naval or auxiliary vessels with /vessels/search

Start by resolving uncertain identities. The search endpoint supports fuzzy name matches, IMO, or MMSI. You can refine by flag, ship_type, tonnage, build years, and paginate results (per_page up to 100).

cURL example

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

Python example

import requests

API_KEY = "YOUR_API_KEY"
url = "https://vessels-api.com/api/V1/vessels/search"
params = {
"query": "atlantic", # fuzzy match
"flag": "Panama",
"per_page": 50
}
resp = requests.get(url, headers={"X-API-Key": API_KEY}, params=params, timeout=20)
resp.raise_for_status()
payload = resp.json()

# Consistent envelope: {status, success, message, data}
vessels = payload.get("data", {}).get("vessels", [])
for v in vessels:
print(v.get("imo"), v.get("mmsi"), v.get("name"), v.get("vessel_type"))

Response shape

{
"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
}
}

Key fields you’ll use immediately: imo, mmsi, name, vessel_type, and pagination to iterate through long result sets. All timestamps in this API are UTC. For client caching, store search results by IMO/MMSI and re-query on demand.

2) Track live positions, history, and route with /vessels/track

Use /vessels/track to follow a VOI in real time, pull the last 24–168 hours of AIS positions, and examine route context. For naval operations, route and last_port_visits provide quick situational awareness for intent assessment, while predicted ETA (when available) guides interception or rendezvous planning.

OFFICIAL SAMPLE (copy-paste as-is)

How to use these fields:

• current_position.latitude/longitude: plot on your map; all coordinates are WGS84.
• speed_knots, course_degrees, heading_degrees: for movement vectors and CPA/TCPA calculations.
• navigational_status: integer AIS nav status; combine with speed=0 to catch anchorage or restricted maneuvering.
• route and last_port_visits: quick context for recent port activity and current voyage.
• position_history: if hours>0 and available, contains time-ordered points for track lines.

Python example (parsing the official sample fields)

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}

r = requests.get(url, headers={"X-API-Key": API_KEY}, params=params, timeout=20)
r.raise_for_status()
data = r.json()["data"]

vessel = data["vessel"]
pos = data["current_position"]
route = data.get("route", {})
visits = data.get("last_port_visits", [])

print("VOI:", vessel.get("imo"), vessel.get("mmsi"))
print("Lat/Lon:", pos.get("latitude"), pos.get("longitude"))
print("Speed/Course:", pos.get("speed_knots"), pos.get("course_degrees"))
print("UTC timestamp:", pos.get("timestamp_utc"))
print("Route ETA:", route.get("eta"))

# If you need recent track points
for p in data.get("position_history", []):
# Each position has latitude, longitude, timestamp_utc, etc. (when available)
pass

Tips

• hours parameter defaults to 24 and caps at 168. For mission replays, request 168h, then downsample client-side.
• Use include_route and include_predicted_eta when you need voyage context; omit for minimal payloads.
• Timestamps are UTC ISO8601. Convert to local timezones in the UI as needed.

3) Detect nearby vessels around a patrol area with /vessels/nearby

For perimeter security, interdiction, or SAR coordination, query all vessels within a radius of a given lat/lon in nautical miles. Filter by ship_type to focus on targets like Tanker, Cargo, Tug, Passenger, or Fishing. Default radius is 50 NM; you can extend up to 200 NM.

cURL example

JavaScript example (fetch)

const url = new URL("https://vessels-api.com/api/V1/vessels/nearby");
url.searchParams.set("latitude", "-34.60");
url.searchParams.set("longitude", "-58.38");
url.searchParams.set("radius", "30"); // nautical miles
url.searchParams.set("limit", "50");

fetch(url.toString(), { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => {
if (!r.ok) throw new Error("HTTP " + r.status);
return r.json();
})
.then(json => {
const payload = json.data;
console.log("Center:", payload.center, "Radius:", payload.radius_nm, "Total:", payload.total);
for (const v of payload.vessels) {
// v: {imo, mmsi, name, ship_type, position:{latitude, longitude, timestamp_utc}, distance_nm, speed_knots, course_degrees, navigational_status}
console.log(v.mmsi, v.name, v.distance_nm + " NM");
}
})
.catch(console.error);

Response shape

Use distance_nm to prioritize targets for interception. Combine speed_knots and course_degrees for predicted intercept points, or feed the contacts into your AIS deconfliction or alerting pipeline. The optional limit parameter controls the number of contacts returned.

4) Summarize activity with /vessels/analytics

When you need quick operational metrics for a VOI or task group, use /vessels/analytics. Set type=vessel with an imo or mmsi, or type=fleet with mmsi_list. For port-centric briefs, use type=port with a port_id. The period switch supports 24h, 7d, 30d, and 90d.

cURL example (vessel mode)

Response shape

These aggregates compress what happened without replaying the whole track. Store them with your mission ID for rapid brief generation.

Implementation notes that save time

• Authentication: include X-API-Key: YOUR_API_KEY on every request. No OAuth refresh logic required.
• Envelope: always read data from the top-level data key after confirming success=true.
• Units: distances in nautical miles (nm); speed in knots; coordinates in decimal degrees (WGS84); timestamps in UTC.
• Pagination: /vessels/search provides pagination info. Set per_page up to 100 for fewer round-trips.
• Filtering: Prefer server-side filters (e.g., ship_type, flag) to reduce bandwidth and client CPU.
• Caching: Cache search lookups by IMO/MMSI for minutes to hours. For /vessels/track, respect your refresh cadence and only poll the deltas you need.
• Error handling: check status codes. You may see 400 (invalid parameter), 401 (invalid/missing key), 404 (not found), 422 (out of range), 429 (rate limit), 500 (server error).

Combining endpoints for a naval common operating picture

Here’s a minimal flow you can wire into your dashboard:

1. Resolve VOI identity via /vessels/search by MMSI or fuzzy name.
2. Start a periodic poll to /vessels/track for current_position plus 24–48h position_history. Plot vectors and build breadcrumb trails.
3. For a patrol sector, query /vessels/nearby every N minutes to see evolving traffic, then filter and alert by distance_nm and ship_type.
4. At shift change or after an operation, call /vessels/analytics to produce a succinct movement and port-call summary.

If you manage multiple hulls, consolidate with /vessels/fleet (POST) to pull positions and routes for many MMSIs/IMOs in a single call. That’s ideal for fleet-level status cards and map overlays.

Security, compliance, and ESG context

For missions intersecting compliance or environmental reporting, /vessels/green provides IMO CII emissions metrics over 24h, 7d, 30d, or 1y windows. Ratings follow IMO MEPC.339(76) with a letter grade A–E. While not central to pursuit or interdiction, these values can inform port-state interactions or ESG reporting for auxiliary fleets.

Developer resources

• Register
• Documentation
• MCP

FAQ

What is the maximum history window I can request for a vessel track?
Use the hours parameter up to 168 hours (7 days). The default is 24 hours if you omit it.

How do I authenticate my requests?
Include the X-API-Key header with your key on every call. There is no OAuth; the same header works across all endpoints.

What coordinate system and units are returned?
Coordinates are decimal degrees (WGS84). Distances are nautical miles, speeds are knots, and all timestamps are UTC ISO8601.

Can I restrict nearby results to certain ship types?
Yes. /vessels/nearby supports an optional ship_type filter and a limit parameter. The default radius is 50 NM (max 200 NM).

How do I handle long search result sets?
Use page and per_page (up to 100). The response includes pagination with current_page, per_page, total, and last_page for iteration.

Build your naval tracking workflow today

With a single API key and a consistent JSON envelope, you can ship a reliable naval tracking stack: search identities, stream live tracks with history and route context, and continuously scan for nearby contacts around any patrol sector. Get started with the 7-day trial, wire in /vessels/search, /vessels/track, /vessels/nearby, and ship your first operational dashboard in hours. Explore the endpoints in the Documentation, request your key via Register, and test live calls in the MCP.