You need to track an offshore supply vessel (OSV) with reliable AIS positions, recent track history, predicted ETA to the rig or shore base, and quick views across a working fleet. By the end of this guide, you will query live OSV positions, list nearby vessels around a lat/lon (rig area), run voyage analytics, and pull multi-vessel snapshots for dashboards—using a single REST API and one API key.
Why OSV tracking is its own problem
Offshore supply vessels operate on short legs between ports and offshore installations, run frequent port calls, and often hold station near rigs. Operators care about precise, recent positions, actual time at berth, and quick snapshots across a multi-vessel fleet. You also need predictable JSON, simple authentication, and endpoints that scale from a single mmsi lookup to fleet-wide dashboards.
- One API key and one base URL: no OAuth and no per-endpoint differences.
- Consistent JSON envelope across endpoints: {status, success, message, data}.
- 18 REST endpoints spanning search, live tracking, port intelligence, fleet operations, CII emissions, and a premium real-time AIS feed.
- Global AIS coverage with near real-time refresh rates.
- 7-day free trial on all plans; suitable for indie apps through enterprise fleets.
We’ll focus on these endpoints for OSV workflows:
- GET /vessels/search — quickly find the right MMSI/IMO for an OSV
- GET /vessels/track — live position, 0–168h history, active route, predicted ETA, weather
- GET /vessels/nearby — situational awareness around rigs or corridors
- GET /vessels/analytics — voyage statistics over rolling windows
- POST /vessels/fleet — one request for many vessels’ positions/routes
- GET /vessels/green — IMO CII estimate for compliance and ESG
Reference: Documentation, MCP.
Authentication and base patterns
Base URL: https://vessels-api.com/api/V1. Send your API key in the X-API-Key header. All endpoints are GET except /vessels/fleet (POST). Responses share this top-level structure:
{
"status": 200,
"success": true,
"message": "OK",
"data": { ... }
}
For production, favor HTTP keep-alive, a short timeout, and minimal query params per request. Timestamps are UTC ISO-8601. Distances are in nautical miles (nm); speeds are in knots.
1) Identify the offshore supply vessel with /vessels/search
Before tracking, you’ll often start with a fuzzy name or a partial MMSI/IMO. Use filters like ship_type=Offshore or a flag if you have it. You’ll receive paginated results with measures you can surface in a UI.
cURL
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/vessels/search?query=offshore%20supplier&ship_type=Offshore&per_page=5"
JSON (example)
{
"status": 200,
"success": true,
"message": "OK",
"data": {
"vessels": [
{
"imo": "9122556",
"mmsi": "258785000",
"name": "OFFSHORE SUPPLIER",
"flag": "Norway",
"vessel_type": "Offshore",
"gross_tonnage": 3500,
"deadweight_tonnage": 4200,
"year_built": 1995,
"length_m": 83.0,
"width_m": 18.0
},
{
"imo": "9740001",
"mmsi": "257999111",
"name": "OFFSHORE SUPPLY ONE",
"flag": "Norway",
"vessel_type": "Offshore",
"gross_tonnage": 4100,
"deadweight_tonnage": 5200,
"year_built": 2015,
"length_m": 86.5,
"width_m": 19.5
}
],
"pagination": {
"current_page": 1,
"per_page": 5,
"total": 42,
"last_page": 9
}
}
}
Key fields: mmsi and imo identify the target; length_m and width_m help sanity-check the class; pagination tells you how to paginate a results UI.
2) Live OSV tracking, route, and ETA with /vessels/track
This endpoint returns the current position, up to 168 hours of history, the active route, predicted ETA, and last port visits. For OSV control rooms, this powers the map and timeline view.
OFFICIAL cURL (copy verbatim)
curl -H "X-API-Key: YOUR_API_KEY" "https://vessels-api.com/api/V1/vessels/track?mmsi=258785000&hours=48"
OFFICIAL JSON (copy verbatim)
{
"status": 200,
"success": true,
"message": "OK",
"data": {
"vessel": {
"imo": "9122556",
"mmsi": "258785000",
"name": null
},
"current_position": {
"latitude": 53.33708,
"longitude": 7.17993,
"position_precision": "precise",
"position_accuracy_nm": null,
"speed_knots": 0,
"course_degrees": 212,
"heading_degrees": null,
"navigational_status": 5,
"timestamp_utc": "2017-01-24T04:07:38+00:00",
"age_minutes": 5159480,
"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
}
}
How to use it in an OSV view:
- Plot data.current_position.latitude/longitude. Speed is in knots; course_degrees is true course over ground.
- Use route to show the active voyage line with avg_speed_knots; predicted_eta may be null and should be handled gracefully.
- last_port_visits lets you annotate recent port calls in a timeline.
- hours ranges up to 168; default is 24. For OSVs doing frequent short hops, 24–48 hours usually tells the current story without overloading the map.
3) Situational awareness around a rig with /vessels/nearby
OSV dispatchers commonly need to see every vessel within a certain radius of a rig or offshore waypoint. Provide the rig’s lat/lon, tune radius (nm), filter by ship_type=Offshore if desired, and cap with limit.
cURL
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/vessels/nearby?latitude=59.00&longitude=2.00&radius=25&ship_type=Offshore&limit=20"
JSON (example)
{
"status": 200,
"success": true,
"message": "OK",
"data": {
"center": { "latitude": 59.0, "longitude": 2.0 },
"radius_nm": 25,
"total": 7,
"vessels": [
{
"imo": "9122556",
"mmsi": "258785000",
"name": "OFFSHORE SUPPLIER",
"ship_type": "Offshore",
"position": { "latitude": 59.1021, "longitude": 2.0549, "timestamp_utc": "2026-07-30T13:05:00+00:00" },
"distance_nm": 6.1,
"speed_knots": 9.2,
"course_degrees": 42,
"navigational_status": 0
},
{
"imo": "9740001",
"mmsi": "257999111",
"name": "OFFSHORE SUPPLY ONE",
"ship_type": "Offshore",
"position": { "latitude": 58.9910, "longitude": 2.1100, "timestamp_utc": "2026-07-30T13:03:10+00:00" },
"distance_nm": 4.8,
"speed_knots": 0.5,
"course_degrees": 12,
"navigational_status": 5
}
]
}
}
Use distance_nm for sorting and rendering labels (nearest first). navigational_status can help distinguish DP/at anchor versus underway.
4) Voyage stats with /vessels/analytics
OSV operations benefit from trend monitoring: distance covered, speed behavior, and port calls over rolling windows (24h/7d/30d/90d). This endpoint outputs aggregated statistics suited for KPI panels.
cURL
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/vessels/analytics?type=vessel&mmsi=258785000&period=7d"
JSON (example)
{
"status": 200,
"success": true,
"message": "OK",
"data": {
"type": "vessel",
"mmsi": "258785000",
"imo": "9122556",
"name": "OFFSHORE SUPPLIER",
"period": "7d",
"statistics": {
"total_distance_nm": 612.4,
"avg_speed_knots": 9.6,
"max_speed_knots": 15.3,
"port_calls_count": 11,
"total_time_in_port_hours": 86.2,
"ports_visited": ["EMDEN", "HERACLIO"]
}
}
}
These fields drive charts: total_distance_nm for utilization, port_calls_count for turnaround pacing, and total_time_in_port_hours for berth planning.
5) Multi-vessel snapshots with /vessels/fleet
Dispatch dashboards and automated alerts run faster when you fetch multiple OSVs in one call. Use POST /vessels/fleet to get each vessel’s latest position and route under a fleet summary.
cURL
curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"vessels":[{"imo":"9122556"},{"mmsi":"257999111"}],"include_positions":true,"include_routes":true}' \
"https://vessels-api.com/api/V1/vessels/fleet"
JSON (example)
{
"status": 200,
"success": true,
"message": "OK",
"data": {
"fleet": {
"total_vessels": 2,
"vessels_at_sea": 1,
"vessels_in_port": 1
},
"vessels": [
{
"imo": "9122556",
"mmsi": "258785000",
"name": "OFFSHORE SUPPLIER",
"position": {
"latitude": 59.1021,
"longitude": 2.0549,
"speed_knots": 9.2,
"course_degrees": 42,
"timestamp_utc": "2026-07-30T13:05:00+00:00"
},
"route": {
"departure_port": "EMDEN",
"departure_time": "2026-07-30T10:35:00+00:00",
"destination_port": "HERACLIO",
"eta": null,
"distance_nm": 325.0,
"avg_speed_knots": 10.1
}
},
{
"imo": "9740001",
"mmsi": "257999111",
"name": "OFFSHORE SUPPLY ONE",
"position": {
"latitude": 58.9910,
"longitude": 2.1100,
"speed_knots": 0.5,
"course_degrees": 12,
"timestamp_utc": "2026-07-30T13:03:10+00:00"
},
"route": {
"departure_port": "HERACLIO",
"departure_time": "2026-07-30T07:20:00+00:00",
"destination_port": "HERACLIO",
"eta": null,
"distance_nm": null,
"avg_speed_knots": 0.8
}
}
]
}
}
The fleet summary helps drive top-level KPIs (at sea vs in port). For each vessel, render a mini-card with speed, course, and last timestamp_utc, then deep-link to a dedicated track view.
6) ESG and regulatory: CII scoring with /vessels/green
Some charters and internal policies require monitoring estimated emissions and IMOs CII score. OSVs are not exempt from scrutiny. Use /vessels/green to pull a rolling estimate and the rating band (A–E).
cURL
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/vessels/green?mmsi=258785000&period=30d"
JSON (example)
{
"status": 200,
"success": true,
"message": "OK",
"data": {
"imo": "9122556",
"mmsi": "258785000",
"name": "OFFSHORE SUPPLIER",
"period": "30d",
"distance_nm": 1980.5,
"estimated_emissions": {
"co2_tons": 128.4,
"co2_per_nm": 0.0649
},
"cii": {
"score": 6.1,
"rating": "C",
"year": 2026,
"regulation_reference": "IMO MEPC.339(76)"
}
}
}
Use co2_per_nm for normalization across vessels of different sizes and routes. The rating field is the letter-grade used in dashboards and reports.
Build it in code: Python and JavaScript
The following snippets show how to call the live track endpoint for an OSV and extract fields for a map marker and a detail panel. They use the official MMSI fixture and keep the exact URL/params.
Python (requests)
import requests
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=10)
resp.raise_for_status()
payload = resp.json()
if not payload.get("success"):
raise RuntimeError(f"API error: {payload.get('message')}")
data = payload["data"]
v = data["vessel"]
pos = data["current_position"]
marker = {
"id": v.get("mmsi") or v.get("imo"),
"lat": pos["latitude"],
"lon": pos["longitude"],
"speed_knots": pos["speed_knots"],
"course_degrees": pos["course_degrees"],
"ts": pos["timestamp_utc"]
}
route = data.get("route") or {}
panel = {
"name": v.get("name"),
"imo": v.get("imo"),
"mmsi": v.get("mmsi"),
"departure_port": route.get("departure_port"),
"destination_port": route.get("destination_port"),
"avg_speed_knots": route.get("avg_speed_knots"),
"predicted_eta": data.get("predicted_eta")
}
print("Marker:", marker)
print("Panel:", panel)
JavaScript (fetch, Node or browser)
const url = "https://vessels-api.com/api/V1/vessels/track?mmsi=258785000&hours=48";
fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(payload => {
if (!payload.success) throw new Error(payload.message);
const { vessel, current_position, route } = payload.data;
const marker = {
id: vessel.mmsi || vessel.imo,
lat: current_position.latitude,
lon: current_position.longitude,
speed_knots: current_position.speed_knots,
course_degrees: current_position.course_degrees,
ts: current_position.timestamp_utc
};
const panel = {
name: vessel.name,
imo: vessel.imo,
mmsi: vessel.mmsi,
departure_port: route?.departure_port || null,
destination_port: route?.destination_port || null,
avg_speed_knots: route?.avg_speed_knots || null,
predicted_eta: payload.data.predicted_eta
};
console.log(marker, panel);
})
.catch(err => console.error("API error:", err));
Operational details that save time
- Authentication: always send X-API-Key. 401 means the header is missing or invalid.
- Time units: All timestamps are UTC ISO-8601. Use the suffix +00:00 for display or convert to local timezones in your UI.
- Distance/speed: Distances are nautical miles (nm). Speeds are knots. Course/heading are degrees (0–359).
- History window: /vessels/track supports hours up to 168. For OSVs, 24–48 hours usually balances clarity with detail.
- Pagination: /vessels/search uses page and per_page (max 100). Always read pagination.last_page before auto-advancing.
- Filtering: Use ship_type=Offshore where relevant to reduce noise in busy basins.
- Error codes: 400 (bad params), 404 (not found), 422 (out of range), 429 (rate limit), 500 (server). Implement retries with jitter for 429/500.
- Data envelope: Always check success and message before using data to avoid partial renders.
Optional port intelligence for shore bases
Many OSVs cycle through the same shore base. You can combine vessel tracking with port snapshots and expected arrivals to forecast quay and laydown congestion. Explore:
- GET /ports — browse the full catalog (248 ports) and metadata for map layers.
- GET /ports/data — get live counts for a single port (vessels_in_port, vessels_expected).
- GET /port/expected-arrivals — list inbound vessels with ETA and origin.
- GET /ports/congestion — snapshot of anchorage/berth and wait-time stats (use documented UNLOCODEs).
See the Documentation for full parameters, examples, and field notes.
Putting it together for an OSV dashboard
- Search: Resolve the OSV’s mmsi with /vessels/search and let operators favorite vessels.
- Live map: Poll /vessels/track at a sensible interval; render current_position and last 24h trail.
- Rig bubble: Use /vessels/nearby around rig coordinates to highlight approaching supply vessels and standby craft.
- KPIs: Call /vessels/analytics with period=7d or 30d for distance, speed, and port call trends.
- Fleet view: Use /vessels/fleet to load many OSVs at once for a status board.
- ESG: Periodically fetch /vessels/green for rolling CII estimates and surface rating changes.
Additional JSON examples to reuse
/ports/data (illustrative)
{
"status": 200,
"success": true,
"message": "OK",
"data": {
"port_id": "HERACLIO",
"name": "HERACLIO",
"country": "GR",
"latitude": 35.3387,
"longitude": 25.1442,
"timezone": "Europe/Athens",
"vessels_in_port": 12,
"vessels_expected": 5
}
}
/ports (subset)
{
"status": 200,
"success": true,
"message": "OK",
"data": {
"ports": [
{ "port_id": "ARBUE", "name": "BUENOS AIRES", "country": "AR", "latitude": -34.602, "longitude": -58.368, "timezone": "America/Argentina/Buenos_Aires" },
{ "port_id": "SGSIN", "name": "SINGAPORE", "country": "SG", "latitude": 1.264, "longitude": 103.840, "timezone": "Asia/Singapore" },
{ "port_id": "NLRTM", "name": "ROTTERDAM", "country": "NL", "latitude": 51.940, "longitude": 4.138, "timezone": "Europe/Amsterdam" }
],
"total": 248
}
}
FAQ
What’s the minimum required parameter to track an OSV?
Provide either imo or mmsi to /vessels/track. For programmatic reliability, use mmsi when available.
How far back can I request history?
Use hours up to 168 (7 days). The default is 24 hours.
How do I filter Nearby to only show OSVs?
Pass ship_type=Offshore to /vessels/nearby along with latitude, longitude, and optional radius.
What response fields should I cache?
Cache vessel particulars (name, dimensions) longer. For live map tiles, cache current_position briefly; always prefer fresh timestamps.
How are emissions and CII reported?
/vessels/green returns estimated_emissions and a CII object with score and rating (A–E) for the requested period.
Ready to ship your OSV tracking dashboard? Start building with a single API key, global AIS coverage, and consistent JSON across endpoints. Register now, read the Documentation, and explore integrations on the MCP.