You need to monitor refrigerated cargo (reefer) vessels with enough fidelity to protect cold chains: where each ship is, where it’s headed, how long it may wait at anchorage, and whether it’s on track to hit a temperature-critical ETA. By the end of this walkthrough, you’ll query live AIS, route/ETA, fleet snapshots, port congestion, and CII emissions from a single REST API and wire those fields into a reefer operations dashboard.
What’s unique about tracking reefer ships
Refrigerated cargo has tight delivery windows and discharge constraints. For many teams, “in range” isn’t enough—you need speed-over-ground for power load estimates, route and ETA to plan pre-cooling and labor at terminals, and congestion signals for diversion decisions. The API calls below focus on the data points that matter most to reefer operations: live position and recent history, active route with ETA, nearby port conditions, and fleet-wide status at a glance.
How the API works (quick orientation)
- Base URL: https://vessels-api.com/api/V1
- Auth: X-API-Key header on every request (no OAuth)
- Response envelope is always JSON with fields: {status, success, message, data}
- Most endpoints are GET; /vessels/fleet is POST
- Time fields are UTC (ISO-8601). Distances are nautical miles. Speed is in knots.
You can explore the full surface and schema details in the Documentation, or interactively test APIs using the MCP.
Live tracking for reefer voyages
Use GET /vessels/track to retrieve the current position, up to 168 hours of history, active route, predicted ETA, and last port visits—everything needed to decide if a cargo will make its temperature-critical window or if an alternative plan is required.
Official sample: copy-paste cURL
curl -H "X-API-Key: YOUR_API_KEY" "https://vessels-api.com/api/V1/vessels/track?mmsi=258785000&hours=48"Official sample JSON
{
"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:06+00:00",
"age_minutes": 5142140,
"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
}
}What you’ll actually use for reefer tracking:
- data.current_position.speed_knots and course_degrees to validate movement vs. drift or anchorage holding.
- data.route.destination_port and avg_speed_knots to sanity-check timeline assumptions.
- data.last_port_visits[] to confirm recent handling and potential cold-chain handoffs.
- data.predicted_eta and current_position.eta (if present) to drive uplifts in your delivery ETA model.
Tip: include_route=true and include_predicted_eta=true are optional query flags. If you need forecasted ETA explicitly, pass them to ensure your payload includes those objects when available.
Python example: parse fields for a reefer ETA panel
import requests
from datetime import datetime, timezone
API_KEY = "YOUR_API_KEY"
BASE_URL = "https://vessels-api.com/api/V1"
def get_reefer_track(mmsi: str, hours: int = 48):
url = f"{BASE_URL}/vessels/track"
params = {"mmsi": mmsi, "hours": hours}
resp = requests.get(url, headers={"X-API-Key": API_KEY}, params=params, timeout=20)
resp.raise_for_status()
payload = resp.json()
if not payload.get("success"):
raise RuntimeError(payload.get("message"))
data = payload["data"]
vessel = data["vessel"]
pos = data.get("current_position") or {}
route = data.get("route") or {}
last_ports = data.get("last_port_visits") or []
predicted_eta = data.get("predicted_eta")
# Extract the key values for a reefer dashboard
summary = {
"imo": vessel.get("imo"),
"mmsi": vessel.get("mmsi"),
"lat": pos.get("latitude"),
"lon": pos.get("longitude"),
"sog_knots": pos.get("speed_knots"),
"course_deg": pos.get("course_degrees"),
"timestamp_utc": pos.get("timestamp_utc"),
"destination_port": route.get("destination_port"),
"route_avg_speed_knots": route.get("avg_speed_knots"),
"predicted_eta": predicted_eta or pos.get("eta")
}
# Example: flag stale AIS if older than 60 minutes
ts = pos.get("timestamp_utc")
if ts:
seen = datetime.fromisoformat(ts.replace("Z", "+00:00"))
age_minutes = (datetime.now(timezone.utc) - seen).total_seconds() / 60.0
summary["stale"] = age_minutes > 60
# Include the most recent port call if available
if last_ports:
summary["last_port"] = {
"name": last_ports[0].get("port_name"),
"arrival_time": last_ports[0].get("arrival_time")
}
return summary
if __name__ == "__main__":
track = get_reefer_track("258785000", 48)
print(track)Discover and onboard reefer vessels
To bootstrap a reefer fleet in your app, use GET /vessels/search with fuzzy name search or identifiers (IMO/MMSI). Filter by ship_type if you maintain a catalog of reefer-only assets.
The response returns data.vessels[] plus pagination metadata. Useful fields include imo, mmsi, name, flag, vessel_type, deadweight_tonnage, and dimensions (length_m, width_m). For bulk onboarding, iterate through pages with per_page up to 100.
Run reefer operations at fleet scale
When supervising dozens of reefers, polling a single endpoint per vessel is not efficient. Use POST /vessels/fleet to get positions and routes for multiple assets in a single request.
From the response’s data.vessels[], map mmsi/imo to your internal reefer IDs and render status tags like “At sea”, “In port”, “Anchorage” based on position.navigational_status and sog.
Port-side risk: congestion and expected arrivals
For cold-chain reliability, pairing vessel ETA with port conditions is critical. Use port intelligence endpoints to anticipate bottlenecks and schedule power and labor appropriately.
Congestion snapshot
GET /ports/congestion provides a real-time snapshot and wait-time statistics. Use the UNLOCODE in port_id.
Key fields: snapshot.vessels_in_anchorage, snapshot.vessels_at_berth, and statistics.avg_wait_time_hours_last_7d. For diversion logic, compare projected reefer arrival vs average wait time to estimate plug-in availability and turnaround risk.
Expected arrivals
To line up pre-cooling and cold storage, query expected arrivals for a port:
Fields to integrate: expected_arrivals[].name, vessel_type (reefer vs general cargo), eta, and departure_port. Combine with your tracked reefer’s predicted_eta to forecast berth competition in the same window.
ESG and compliance: track CII for reefer trades
Many reefer operators report emissions for ESG or regulatory audits. Use GET /vessels/green to retrieve distance, estimated emissions, and the IMO CII rating for a specified period.
Response highlights: data.estimated_emissions.co2_tons and data.cii.rating (A to E). Store these alongside voyage segments to trace how slow steaming or port congestion impacted CII outcomes across reefer lanes.
Build a reefer tracking dashboard: wiring the pieces
Core panels and the fields behind them
- Vessel card: name, imo/mmsi (from /vessels/search), last AIS fix timestamp_utc, speed_knots, course_degrees (/vessels/track).
- Voyage status: route.departure_port, route.destination_port, route.avg_speed_knots, predicted_eta (/vessels/track).
- Cold-chain alerts: flag stale AIS (>60 minutes), zero speed with non-anchorage status, or ETA slipping relative to cargo delivery window.
- Port risk strip: ports/congestion snapshot metrics for the destination; expected-arrivals overlap window for berth competition.
- Fleet map: /vessels/fleet positions; cluster reefers in port vs at sea; show vessels_in_port vs vessels_at_sea from data.fleet.
- ESG widget: latest CII rating and co2_tons from /vessels/green for the reporting period.
Caching and polling cadence
- Use If-Modified-Since semantics in your app logic (store last timestamp_utc) to skip UI updates when no new AIS fix is available.
- Poll /vessels/track more frequently inside a 12–24 hour ETA window; otherwise, relax polling to preserve quota.
- Cache /ports/congestion for short intervals (e.g., 5–15 minutes) to avoid duplicate fetches across multiple vessel cards targeting the same port.
Implementation tips that save time
- Authentication: include X-API-Key on every call; no OAuth flow is required.
- Consistent structure: every response nests data under the same envelope—always check success and status before dereferencing data.
- Units and coordinates: speeds in knots; distance_nm in nautical miles; latitude/longitude in decimal degrees (WGS84).
- Timestamps: ISO-8601 in UTC; render with the destination port’s timezone for on-the-ground teams if needed.
- Pagination: /vessels/search supports page and per_page (max 100); use pagination.total and last_page to complete imports.
- Errors: handle 401 for missing/invalid API key, 404 for unknown vessel/port, 422 for parameter range issues (e.g., hours > 168).
- Batching: prefer /vessels/fleet for synchronous map refreshes across multiple reefers to reduce client fan-out.
End-to-end example flow (reefer ETA + port risk)
- Search and store identifiers with /vessels/search (persist imo/mmsi, vessel_type).
- Fetch live track with /vessels/track?mmsi=...&hours=48 including route and predicted ETA.
- Query /ports/congestion for the route.destination_port UNLOCODE to estimate anchorage risk.
- Overlay /port/expected-arrivals to gauge berth competition around the predicted ETA window.
- If congestion risk is high, compare alternate ports and re-run the above calls to simulate diversion impact.
- Log /vessels/green every 7–30 days for ESG rollups, correlating voyage choices with CII movement.
FAQ
Which identifiers should I store for reefer vessels?
Persist both imo and mmsi. Use imo for long-term identity across MMSI changes; use mmsi for real-time tracking when available.
How far back can I request position history?
/vessels/track supports hours up to 168 (7 days). Use the hours parameter to balance payload size with your analytics needs.
How do I know if a vessel is at anchorage vs under way?
Combine current_position.speed_knots with navigational_status. Zero or near-zero speed plus an anchorage status generally indicates waiting. Always check timestamp_utc to avoid stale conclusions.
Can I query multiple reefers at once for a live map?
Yes. Use POST /vessels/fleet with include_positions and optionally include_routes for a single aggregated response.
What timezone are timestamps in?
All timestamps are UTC. Convert to the destination port’s timezone for terminal operations displays.
Get your reefer tracking integration live
Build your reefer dashboard with a single API key and consistent JSON across vessel search, live AIS, fleet snapshots, port congestion, and CII. Start with the official samples above, then explore deeper fields in the Documentation, test interactively in the MCP, and Register to begin integrating.
