You need to programmatically track a research vessel in near real time, see where it has been, where it is going, and when it is likely to arrive—all in a format you can plug straight into your ops dashboard or mission-control scripts. By the end of this post, you will be able to search for a research vessel by MMSI or IMO, fetch its live AIS track with up to 168 hours of history, compute ETAs and routes, geofence activity near a point of interest, and roll up analytics for a voyage—using the Vessels API in a few lines of code.
What makes this API useful for tracking research vessels
Research vessels operate dynamically: extended station-keeping, survey lines at low speed, opportunistic port calls, and sometimes rapid transits to new study areas. You need flexible data views that work with those mission profiles. Vessels API exposes:
- 18 REST endpoints across search, live tracking, fleet ops, port intelligence, emissions, and a premium real-time AIS feed.
- One API key, one base URL, and a consistent JSON envelope on every response: {status, success, message, data}.
- Global AIS coverage with near real-time refresh.
- Scales from a single mission to multi-vessel observatory fleets.
We will focus on four endpoints that map directly to research workflows:
- /vessels/track — live position + history + route + predicted ETA + weather
- /vessels/search — fuzzy lookup by name, IMO, or MMSI
- /vessels/nearby — geofencing and local situational awareness
- /vessels/analytics — voyage statistics for a given period
Authentication, base URL, and response envelope
Base URL: https://vessels-api.com/api/V1. All endpoints use the same header-based auth:
- X-API-Key: YOUR_API_KEY
Every response is wrapped consistently:
{
"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:39+00:00",
"age_minutes": 5120480,
"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
}
}That lets you standardize error handling across the 18 endpoints (400 for invalid parameters, 401 for missing/invalid key, 404 for not found, 422 for out-of-range inputs, 429 for rate limits, 500 for server errors). Timestamps are UTC (ISO 8601) and distances/speeds are nautical miles and knots.
1) Get a live AIS track for a research vessel
For a mission dashboard, the tracking endpoint is your anchor: current position, up to 168h of history, route context, and optional ETA and weather. Required parameter: imo or mmsi.
Official cURL: 48-hour track by MMSI
Copy and run this as-is, replacing YOUR_API_KEY with your key.
curl -H "X-API-Key: YOUR_API_KEY" "https://vessels-api.com/api/V1/vessels/track?mmsi=258785000&hours=48"Official JSON response
Key fields you’ll actually use:
- data.current_position.latitude/longitude — plot on your map; speeds in knots, course/heading in degrees.
- data.current_position.timestamp_utc — UTC ISO 8601; use to compute staleness; age_minutes is provided too.
- data.position_history — up to 168 hours; great for survey-line visualization and drift analysis.
- data.route — departure/destination context, ETA, average speed; useful when the vessel resumes transit.
- data.last_port_visits — research port turnaround context for logistics and resupply planning.
Python example: parse and display the live fix and route
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"}
headers = {"X-API-Key": API_KEY}
resp = requests.get(URL, headers=headers, params=params, 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"]
cp = data["current_position"]
route = data.get("route") or {}
lat = cp["latitude"]
lon = cp["longitude"]
sog = cp["speed_knots"]
cog = cp["course_degrees"]
ts_utc = cp["timestamp_utc"]
print(f"Fix: {lat:.5f}, {lon:.5f} | SOG {sog} kn | COG {cog}° | time {ts_utc}")
if route:
print(f"Voyage: {route.get('departure_port')} → {route.get('destination_port')}")
print(f"ETA: {route.get('eta')} | Avg speed: {route.get('avg_speed_knots')} kn")
hist = data.get("position_history", [])
print(f"Positions in last 48h: {len(hist)}")
Notes that save time:
- UTC timestamps: if you need local times for UI, convert with the destination port’s timezone from the ports catalog.
- Nulls: some research missions don’t broadcast destination/ETA; check for nulls before rendering.
- History window: hours defaults to 24 and maxes at 168. Cache it client-side if redrawing the same mission view.
2) Find your research vessel by name, IMO, or MMSI
If you start with a callsign on a whiteboard or a rough vessel name, use the search endpoint. It supports fuzzy matching and useful filters like flag or build year range.
Tips when ingesting search results:
- Pagination: per_page is capped at 100; use pagination fields for UI navigation.
- Disambiguation: validate by IMO or MMSI before persisting to your fleet table.
- Type filtering: ship_type can narrow to Research when available; always keep a fallback match by IMO.
3) Geofence a study area and monitor nearby traffic
While on station, research vessels often need situational awareness—support craft, merchant traffic, fishing vessels. The nearby endpoint returns all vessels within a radius of a lat/lon point in nautical miles.
Implementation details:
- radius defaults to 50 NM and maxes at 200 NM.
- Each item includes position.timestamp_utc and distance_nm from your center.
- Filter by ship_type for deconfliction (e.g., exclude passenger traffic, include tugs/support).
4) Summarize a mission with vessel analytics
For post-mission reporting or weekly status, roll up distance, speeds, and port calls using the analytics endpoint with type=vessel. Use either imo or mmsi and select a period window.
Typical usage:
- Read statistics.total_distance_nm to compute fuel model inputs or coverage estimates.
- Use ports_visited and port_calls_count to annotate resupply cycles.
- Compare avg_speed_knots vs. mission plan to flag off-nominal transits or persistent station-keeping.
Optional: Batch monitor a small research fleet
If you operate multiple research platforms or support vessels, reduce HTTP chatter with a single batch call. The fleet endpoint aggregates positions and routes in one response.
Use the fleet summary (vessels_at_sea vs. in_port) to power status cards and ops alerts without multiple round-trips.
Field guide: interpreting research-vessel AIS signals
- navigational_status: integer codes from AIS; 5 typically indicates moored—useful to detect alongside or anchor states.
- speed_knots near zero with jittering course can mean DP (dynamic positioning) or station-keeping.
- destination and eta fields may be null for missions without declared legs. When present, route.eta is the primary value.
- position_history is valuable for rendering survey transects; smooth with a simple Kalman filter only if your UI needs it—don’t overfit and lose corner maneuvers.
Practical integration notes
- HTTP semantics: GET for all endpoints shown here; only /vessels/fleet uses POST.
- Timeouts: 10–20 seconds is reasonable in most clients; handle 429 with exponential backoff.
- Caching: Cache position_history for a given hours window; refresh current_position more frequently.
- Units: distance_nm and speed_knots are nautical; port congestion times (if used) are in hours.
- Pagination: search returns pagination.{current_page, per_page, total, last_page}—persist these to improve UX.
End-to-end workflow for a mission dashboard
- Bootstrap vessel identity with /vessels/search and pin the mmsi/imo.
- Call /vessels/track with hours=48 (or 168 for longer legs) to render the live fix and recent path.
- Overlay /vessels/nearby for deconfliction around the vessel’s current lat/lon (e.g., 30 NM radius).
- On a scheduled job, hit /vessels/analytics with period=7d to summarize mission progress and port calls.
- If multiple platforms: POST /vessels/fleet to consolidate updates on one interval.
Links you will use while building
FAQ
How fresh is the “live” position?
Positions are updated on a near real-time basis where AIS is available. Check current_position.timestamp_utc and age_minutes to quantify freshness in your UI.
What’s the difference between course_degrees and heading_degrees?
Course is the direction of motion over ground; heading is the bow direction. During DP or drift, heading can diverge from course or be null.
Can I get more than 24 hours of history?
Yes. Set hours up to a maximum of 168 to retrieve up to seven days of position_history on /vessels/track.
What if I only know the vessel’s name?
Use /vessels/search with query and optionally ship_type=Research to narrow results. Confirm with IMO or MMSI before tracking.
How do I avoid multiple requests for a small fleet?
Use POST /vessels/fleet with include_positions and include_routes to fetch multiple vessels in one round-trip.
Build your research-vessel tracker
Start with the track endpoint to render a live fix and history, layer in nearby traffic for situational awareness, and use analytics to roll up weekly distance and port calls. The endpoints are consistent, the payloads are predictable, and the units are maritime-native—so you can ship faster with fewer edge cases. Get your key and start building: Register and explore the Documentation. If you’re integrating with an MCP runtime, see the MCP resources.
