Research teams, marine robotics labs, and environmental NGOs all share the same problem: you need reliable AIS-powered positions, routes, and port touches for research vessels without spending weeks normalizing feeds. By the end of this post, you’ll be able to search for a research vessel, stream its latest position plus 48–168 hours of history, map nearby ships around a survey area, and compute voyage analytics—all with a few requests to a single, consistent REST API.
What makes this API practical for research vessel tracking
The API at https://vessels-api.com/api/V1 provides 18 REST endpoints that cover vessel intelligence, live tracking, fleet operations, port intelligence, and IMO CII emissions. You authenticate every request with one X-API-Key header, and every response uses the same JSON envelope: {status, success, message, data}. For developers building dashboards, alerts, and field tools, this consistency pays off immediately.
- Global AIS coverage with near real-time refresh rates
- Simple auth: X-API-Key only; no OAuth flows
- Uniform response shape across endpoints
- 7-day free trial on all plans; scales from single-vessel projects to enterprise fleets
In this article, we’ll focus on the five endpoints that matter most to research vessel workflows:
- GET /vessels/search — discover and filter research vessels
- GET /vessels/track — live position, history, route, and ETA
- GET /vessels/nearby — build safety and deconfliction views around survey zones
- GET /vessels/analytics — voyage statistics for planning and post-cruise reports
- POST /vessels/fleet — multi-vessel snapshots for program-level oversight
Search and discovery: find the right research vessel record
Whether you’re tracking your own hull or correlating third-party data by IMO/MMSI, start with /vessels/search. It supports fuzzy name queries and filters that help you narrow to research ship classes or flags relevant to your operations.
cURL: search by fuzzy name and flag
curl -H "X-API-Key: YOUR_API_KEY" "https://vessels-api.com/api/V1/vessels/track?mmsi=258785000&hours=48"Example JSON (truncated)
{
"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:43+00:00",
"age_minutes": 5140700,
"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": null,
"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 typically use:
- imo/mmsi: stable identifiers for downstream calls
- vessel_type and flag: filter confirmation for research fleets
- length_m/width_m: berth/air-draft planning, survey gear clearances
- pagination: use page/per_page (max 100) to iterate results
Live tracks and history: position, route, ETA, and port touches
/vessels/track is the core of a research vessel dashboard. It returns the latest position, up to 168 hours of position history, current route with departure/destination, and predicted ETA when available. You can also request weather with include_weather if your operations layer needs it for safety evaluations.
Official sample: 48-hour track by MMSI
The following request and JSON are provided as-is. You can copy and run this cURL by adding your API key.
Key details to wire into your UI:
- current_position.timestamp_utc is ISO 8601 in UTC
- speed_knots and course_degrees are numeric; render knots and degrees true north
- last_port_visits helps annotate cruise legs and port logistics
- position_history contains up to hours points (max 168); use for breadcrumb trails on the map
- route.avg_speed_knots and departure_time help compute schedule variance when predicted_eta is present
Python: fetch the same MMSI track and map fields
import requests
API_KEY = "YOUR_API_KEY"
url = "https://vessels-api.com/api/V1/vessels/track"
params = {"mmsi": "258785000", "hours": 48}
resp = requests.get(url, headers={"X-API-Key": API_KEY}, params=params, timeout=20)
resp.raise_for_status()
payload = resp.json()
if payload.get("success"):
d = payload["data"]
vessel = d["vessel"]
pos = d["current_position"]
print("IMO:", vessel.get("imo"))
print("MMSI:", vessel.get("mmsi"))
print("Timestamp (UTC):", pos.get("timestamp_utc"))
print("Lat/Lon:", pos.get("latitude"), pos.get("longitude"))
print("Speed (kn):", pos.get("speed_knots"))
print("Course (deg):", pos.get("course_degrees"))
route = d.get("route", {})
print("From:", route.get("departure_port"), "To:", route.get("destination_port"))
print("Avg speed (kn):", route.get("avg_speed_knots"))
visits = d.get("last_port_visits", [])
if visits:
latest = visits[0]
print("Last known port:", latest.get("port_name"), "arrived:", latest.get("arrival_time"))
else:
raise SystemExit(f"API error: {payload.get('message')}")Safety and deconfliction: who’s near my survey grid?
When deploying AUVs/ROVs or conducting acoustic transects, it’s essential to visualize traffic around your operations area. Use /vessels/nearby with a center point and radius in nautical miles. Filter by ship_type to focus on cargo, tankers, or passenger ships depending on your risk model.
cURL: 30 NM radius around a survey waypoint
Example JSON (truncated)
Use distance_nm for alert thresholds and position.timestamp_utc to age out stale targets. For dynamic map layers, poll every few minutes and coalesce by MMSI to smooth marker updates.
Voyage analytics: quantify effort and throughput for cruises
Post-cruise reporting and grant deliverables often need simple metrics: distance steamed, average speed, port call counts, and total time in port. /vessels/analytics provides these aggregates on a per-vessel basis. Switch period=24h|7d|30d|90d to match your cruise window.
cURL: 7-day analytics for a research vessel by MMSI
Example JSON
These fields map directly to performance summaries. For reproducible reports, store the input parameters (mmsi, period) alongside the returned values and note that all times are UTC.
Program-level oversight: batch updates for fleets
Research programs often coordinate multiple platforms (primary research vessel, chase boats, gear tenders). With /vessels/fleet you can fetch positions and routes for many vessels in one call, reducing round trips and simplifying UI state.
cURL: batch two vessels with positions and routes
Example JSON (truncated)
Tip: post a minimal vessel identity {imo} or {mmsi} for each item. Include include_positions and include_routes for dashboard tiles that show both current fix and voyage intent.
Implementation details that save time
- Authentication: add X-API-Key: YOUR_API_KEY to every request. No OAuth or per-endpoint tokens.
- Base URL: https://vessels-api.com/api/V1
- Response envelope: expect {status, success, message, data} on all endpoints.
- Timestamps: ISO 8601 strings in UTC (e.g., 2026-07-30T13:00:10+00:00).
- Distance and speed units: nautical miles (nm) and knots (kn).
- Search pagination: per_page up to 100; follow pagination.last_page to complete result sets.
- History windows: /vessels/track hours max is 168 (7 days).
- Error handling: check HTTP status and the JSON envelope. Typical errors include:
- 400: missing/invalid parameter
- 401: invalid or missing X-API-Key
- 404: vessel/port not found
- 422: parameter out of range (e.g., radius beyond 200 NM)
- 429: rate limit exceeded
- 500: server error
JavaScript example: compose a research ops view
This snippet retrieves a live track for a research vessel and a deconfliction layer within 20 NM of its current position, then merges the data for a single render pass.
async function fetchJSON(url, options = {}) {
const res = await fetch(url, {
headers: { "X-API-Key": "YOUR_API_KEY", ...(options.headers || {}) },
...options
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const body = await res.json();
if (!body.success) throw new Error(body.message || "API error");
return body.data;
}
(async () => {
const base = "https://vessels-api.com/api/V1";
// 1) Track the research vessel
const track = await fetchJSON(`${base}/vessels/track?mmsi=258785000&hours=48`);
const fix = track.current_position;
console.log("Fix:", fix.latitude, fix.longitude, "kn:", fix.speed_knots);
// 2) Query nearby traffic around the latest fix
const nearbyUrl =
`${base}/vessels/nearby?latitude=${encodeURIComponent(fix.latitude)}` +
`&longitude=${encodeURIComponent(fix.longitude)}&radius=20&limit=100`;
const nearby = await fetchJSON(nearbyUrl);
// 3) Prepare render data
const markers = [
{
type: "research",
mmsi: track.vessel.mmsi,
lat: fix.latitude,
lon: fix.longitude,
speed: fix.speed_knots,
ts: fix.timestamp_utc
},
...nearby.vessels.map(v => ({
type: v.ship_type,
mmsi: v.mmsi,
lat: v.position.latitude,
lon: v.position.longitude,
speed: v.speed_knots,
distance_nm: v.distance_nm
}))
];
console.table(markers.slice(0, 5));
})().catch(err => console.error(err));ESG and compliance notes for research organizations
If your funding requires environmental disclosures, use GET /vessels/green for IMO CII estimates over 24h to 1y. The response includes co2_tons, co2_per_nm, and a cii.rating (A to E) aligned with IMO MEPC.339(76). While research vessels may have unique duty cycles, these standardized fields make internal reviews and external filings easier to assemble. Example:
Putting it together: common research vessel use cases
- Field dashboard: combine /vessels/track (include route) + /vessels/nearby to show own-ship, breadcrumb history, planned leg, and proximate traffic in one map.
- Cruise reports: run /vessels/analytics at the end of each leg (e.g., period=7d, 30d) for total_distance_nm and port_calls_count. Export to PDF with your mission notes.
- Program operations: poll /vessels/fleet every 2–5 minutes during active transits to keep a multi-platform board current without hammering individual endpoints.
- ESG rollups: schedule /vessels/green monthly to maintain a traceable emissions ledger by IMO/MMSI.
FAQ
How often should I poll /vessels/track for live updates?
For research ops UIs, a 1–5 minute interval balances freshness and network load. Use current_position.age_minutes to decide if a point is stale before drawing.
What’s the maximum history window I can request?
/vessels/track supports hours up to 168 (7 days). If you omit hours, the default is 24.
Can I filter nearby traffic by vessel type?
Yes. /vessels/nearby supports ship_type plus radius (NM) and limit. Radius defaults to 50 NM and cannot exceed 200 NM.
Are all timestamps in local time?
No. All timestamps returned by these endpoints are UTC ISO 8601 strings. Convert on the client if you need local timezones.
How do I handle errors consistently?
Always check both the HTTP status and the JSON envelope. For example, a 200 may still include success=false in rare cases, with a message that explains the issue. Handle 401 for missing/invalid API keys, 404 for not found, and 429 for rate limits.
Next steps
Build your research vessel tracker with a single base URL, one API key, and consistent JSON across endpoints. Start with the official track sample above, layer in nearby traffic, and fold analytics into your reporting pipeline. When you’re ready, use the batch fleet endpoint to keep multiple platforms in view.
Register for an API key to begin integrating. Explore every endpoint in the Documentation, and if you’re building tools with server-side orchestration or plugins, check out the MCP for advanced integration patterns.
