Cold-chain logistics teams need reliable, near real-time visibility into reefer ships carrying perishable cargo across oceans. By the end of this guide, you’ll be able to search for a reefer, stream its live AIS position and route, compute voyage analytics, monitor port activity that can impact ETAs, and roll those into a fleet dashboard—all using vessels-api.com with a few HTTP calls.
What makes vessels-api.com fit for reefer ship tracking
Reefer ships operate on tight schedules and temperature-controlled SLAs. vessels-api.com exposes 18 REST endpoints for search, live tracking, fleet operations, port intelligence, and ESG/CII scoring. You get:
- One API key, one base URL—no OAuth or per-endpoint auth differences
- Consistent JSON envelope on every response: {status, success, message, data}
- Global AIS coverage with near real-time refresh rates
- 7-day free trial on all plans; scales from indie tools to enterprise fleets
Base URL: https://vessels-api.com/api/V1. Authenticate every request with the X-API-Key header.
Core endpoints for reefer operations
Below are the endpoints I recommend starting with for Transportation use cases focused on reefer ships:
- /vessels/search — find a target vessel (by name, IMO, MMSI) with optional filtering by type, flag, tonnage, and build year
- /vessels/track — live AIS position, up to 168h history, active route, predicted ETA, and optional weather
- /vessels/fleet — batch tracking for multiple reefers in one call (positions, routes, high-level status)
- /port/expected-arrivals and /port/activity — understand inbound reefer traffic and recent port calls for logistics eventing
- /vessels/green — IMO CII emissions scoring for ESG and supplier reporting
Search for a reefer ship
Start by resolving an IMO or MMSI so you can track that reefer in downstream calls. If you know only a partial name or the flag, use the filters to de-duplicate common names.
cURL
curl -H "X-API-Key: YOUR_API_KEY" "https://vessels-api.com/api/V1/vessels/track?mmsi=258785000&hours=48"Key notes for developers:
- Pagination: use page and per_page (max 100). The response includes pagination.current_page, per_page, total, last_page.
- Filter by ship_type=Reefer to get temperature-controlled cargo ships specifically.
- Capture both IMO and MMSI from the match you want; downstream endpoints accept either.
Track a reefer in near real time
Once you have a unique identifier, pull the live position, recent history, and voyage route. For time-sensitive reefer cargo, the route/ETA context is often as important as the dot on the map.
Official cURL sample (live track fixture)
Official JSON response
{
"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:04+00:00",
"age_minutes": 5121921,
"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
}
}What to use from this payload:
- data.current_position: latitude/longitude (WGS84), speed_knots (knots), course_degrees (0–359), timestamp_utc (ISO 8601, UTC)
- data.route: departure_port, destination_port, eta. Combine with last_port_visits for context.
- data.position_history: if you pass hours up to 168, you’ll get waypoints for recent movement analytics.
JavaScript (Node.js) example
import fetch from "node-fetch";
const API_KEY = process.env.VESSELS_API_KEY || "YOUR_API_KEY";
const url = "https://vessels-api.com/api/V1/vessels/track?mmsi=258785000&hours=48";
async function trackReefer() {
const res = await fetch(url, {
headers: { "X-API-Key": API_KEY }
});
if (!res.ok) {
throw new Error(`HTTP ${res.status}`);
}
const json = await res.json();
// Consistent envelope: {status, success, message, data}
const { data } = json;
const now = data.current_position?.timestamp_utc;
const lat = data.current_position?.latitude;
const lon = data.current_position?.longitude;
const sog = data.current_position?.speed_knots; // knots
const cog = data.current_position?.course_degrees; // degrees
const dest = data.route?.destination_port || data.current_position?.destination;
const eta = data.route?.eta || data.current_position?.eta;
console.log(`Timestamp (UTC): ${now}`);
console.log(`Position: ${lat}, ${lon} | SOG: ${sog} kn | COG: ${cog}°`);
console.log(`Voyage: → ${dest || "TBD"} | ETA: ${eta || "TBD"}`);
}
trackReefer().catch(console.error);Tips:
- Use include_route=true and include_predicted_eta=true if you need explicit ETA modeling. Default behavior may still yield route context if available.
- Units: positions in decimal degrees (latitude/longitude), distances in nautical miles (nm), speed in knots.
- Timestamps: all ISO 8601 in UTC. Normalize in your UI for local timezones if needed.
Build a reefer fleet dashboard with one POST
When you manage multiple reefers, minimize round trips. /vessels/fleet lets you fetch positions and route summaries for many vessels at once—handy for control towers and alerting pipelines.
cURL (batch positions and routes)
From the response, wire these fields to your UI:
- data.fleet: total_vessels, vessels_at_sea, vessels_in_port for quick KPIs
- data.vessels[n]: imo/mmsi/name, position (lat/lon, speed_knots, timestamp_utc), route (destination_port, eta)
Plan port-side reefer handoffs
Terminal slots and cold storage windows are tight. Combine expected arrivals with recent activity to align trucks, power plugs, and inspection teams.
Expected arrivals
Use data.expected_arrivals[n].eta (UTC), vessel_type, and departure_port to prep for inbound reefer traffic. Pair that with your reefer ship filter from /vessels/search when building port boards focused on refrigerated cargo.
Recent port activity
Consume arrivals[] and departures[] for last-mile orchestration and status feeds to stakeholders. If your reefer hasn’t pinged recently, a confirmed arrival event can help reconcile last-known position vs. actual alongside time.
ESG and supplier reporting for reefers
Many tenders now request carbon intensity data. For reefers—where power demands can be higher—pull a defensible CII rating over a reporting period.
cURL (CII scoring)
The response provides:
- data.estimated_emissions.co2_tons and co2_per_nm
- data.cii.score and rating (A → E) per IMO MEPC.339(76)
Use this to populate supplier scorecards, charter party clauses, and sustainability dashboards alongside your reefer scheduling.
Analytics for reefer performance
For trend analysis on a particular reefer, use /vessels/analytics with type=vessel to summarize distance, speeds, and port calls.
cURL (voyage analytics, 7 days)
Consumption tips:
- statistics.total_distance_nm: combine with cold-chain cycle times
- statistics.avg_speed_knots/max_speed_knots: detect anomalies that could impact reefer box temperatures and arrival windows
- port_calls_count and ports_visited: report on network utilization
Implementation notes that save time
- Authentication: Always send X-API-Key: YOUR_API_KEY. There is no OAuth or per-endpoint variance.
- Base URL: https://vessels-api.com/api/V1. All endpoints are GET except POST /vessels/fleet.
- Polling: For live maps, a 1–5 minute polling interval often balances freshness and efficiency. Cache route and static particulars longer than positions.
- Units: Distances in nautical miles (nm), speeds in knots, coordinates in decimal degrees, times in UTC.
- Error handling: 401 for invalid/missing key, 404 for unknown vessel/port, 422 for out-of-range parameters, 429 for rate limits, 500 for server errors. Inspect the top-level {status, success, message} for diagnostics.
- Pagination: /vessels/search returns pagination metadata; cap per_page at 100. Implement “Load more” UI rather than fetching all at once.
End-to-end example: from search to live track to fleet
Step 1 — find the reefer by fuzzy name
Pick the entry with the correct flag/tonnage and store its IMO/MMSI.
Step 2 — stream its current position and route
Use current_position.timestamp_utc and route.eta to compute “minutes to gate” in your TMS. If predicted_eta is present, compare it to contractual ETA for alerts.
Step 3 — watch your entire reefer lineup
Render fleet KPIs (at sea vs. in port), and pin each reefer with speed_knots and route.destination_port.
Port intelligence for cold-chain timing
Two helpful calls for planning ground operations and plug-in capacity:
- /port/expected-arrivals?port=PORT_ID — inbound vessels with ETA and origin
- /port/activity?port=PORT_ID — recent arrivals/departures for event feeds
For congestion modeling, you can also query /ports/congestion with a UNLOCODE (e.g., ARBUE, SGSIN, NLRTM). The endpoint returns a snapshot and recent wait-time statistics. When building production forecasts, combine congestion stats with /vessels/track route ETAs to buffer arrival windows for temperature-critical cargoes.
Link out to docs, SDK surface, and control-plane tools
FAQ
Which identifier should I prefer for reefers—IMO or MMSI?
Use either; /vessels/track accepts both. IMO is permanent across a vessel’s life, while MMSI can change. If you can, store both and query by what you have available.
How fresh is the AIS data?
Coverage is global with near real-time refresh rates. Treat positions as time-stamped facts in UTC and show the age in your UI. For moving vessels, poll conservatively (e.g., 1–5 minutes) and avoid hammering.
Can I filter searches to only reefer ships?
Yes. Pass ship_type=Reefer to /vessels/search, along with other filters like flag or build year to narrow results.
How do I handle partial or missing fields (e.g., null vessel name)?
Always check for nulls. The envelope is consistent, but some AIS fields (like destination) can be missing or stale. Prefer route.eta over current_position.eta if both exist.
What’s the best way to build fleet KPIs?
Use POST /vessels/fleet with include_positions and include_routes. From the response, compute in-port vs. at-sea counts, top routes, and ETAs per destination_port.
Get started
You can ship a production-grade reefer tracking workflow with a handful of HTTP calls against vessels-api.com. Start with a vessel search, fetch live tracks and ETAs, wire port events, and add CII scoring for ESG stakeholders. When you’re ready, grab an API key and explore the surfaces in the docs and MCP: Register, review the Documentation, and open the MCP to iterate quickly.
