Your ops team needs to know when a reefer ship is near a port, how fast it’s closing, whether berth/anchorage is congested, and when to have plugs and labor ready—without stitching together half a dozen feeds. By the end of this post you’ll be able to query reefers near a port, track a specific vessel’s approach and recent calls, pull expected arrivals, snapshot congestion, and roll it all into a fleet heartbeat using vessels-api.com.
Why reefer-near-port intelligence is its own problem
Reefers move perishable cargo with tight ETAs and strict temperature control. Minutes at anchorage can mean claims or rework. You need:
- Geofenced situational awareness: reefers within a 10–30 NM radius of your port
- Live track + last port calls to validate origin and transit time
- Expected arrivals to stage plugs, surveyors, and drayage windows
- Congestion context to anticipate anchorage wait
- A fleet view for continuous cold-chain monitoring
vessels-api.com gives you this in a consistent REST interface with one API key and a predictable JSON envelope on every response: {status, success, message, data}.
The endpoints we’ll combine
- GET /vessels/nearby — reefers within a radius of your port’s coordinates
- GET /vessels/track — live position, up to 168h history, route, ETA, last port calls
- GET /port/expected-arrivals — plan equipment and labor against ETAs
- POST /vessels/fleet — heartbeat for multiple reefers in one request
- GET /ports/congestion — snapshot of at-berth vs anchorage and recent wait-time stats
All calls use the X-API-Key header and the same base URL (https://vessels-api.com/api/V1). See the Documentation for every parameter and response field.
Step 1: Identify reefers near your port
Start with your port’s coordinates, then query vessels in a radius with an optional ship_type filter. If you don’t have coordinates handy, you can fetch them using GET /ports or GET /ports/data (which includes latitude/longitude along with live counts).
cURL: Reefers within 25 NM of a port center
curl -H "X-API-Key: YOUR_API_KEY" "https://vessels-api.com/api/V1/vessels/track?mmsi=258785000&hours=48"
Key parameters:
- latitude, longitude: port center
- radius: nautical miles (default 50, max 200)
- ship_type: use “Reefer” to narrow to refrigerated cargo vessels
- limit: maximum rows to return (default 50)
Example JSON fields to use
{
"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:23+00:00",
"age_minutes": 5162360,
"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 matters: distance_nm to trigger alerts, speed_knots to infer approach vs loitering, and navigational_status to spot at anchor or moored states.
Python: Query nearby reefers and raise an approach alert
import requests
from math import isfinite
API_KEY = "YOUR_API_KEY"
BASE = "https://vessels-api.com/api/V1"
params = {
"latitude": 1.264, # port center
"longitude": 103.84,
"radius": 25, # NM
"ship_type": "Reefer",
"limit": 50
}
r = requests.get(f"{BASE}/vessels/nearby", headers={"X-API-Key": API_KEY}, params=params, timeout=20)
r.raise_for_status()
envelope = r.json()
vessels = envelope.get("data", {}).get("vessels", [])
alerts = []
for v in vessels:
dist = v.get("distance_nm")
speed = v.get("speed_knots")
if isfinite(dist) and dist <= 12 and isfinite(speed) and speed >= 8:
alerts.append({
"mmsi": v.get("mmsi"),
"imo": v.get("imo"),
"name": v.get("name"),
"distance_nm": dist,
"speed_knots": speed
})
print({"reefer_approach_alerts": alerts})
Step 2: Track a specific reefer’s approach and last port calls
Once a vessel is in-range, switch to GET /vessels/track for live position, up to 168 hours of history, active route, ETA, and last port visits. The response always follows the same JSON envelope.
OFFICIAL SAMPLE — cURL (do not modify)
OFFICIAL SAMPLE — JSON (verbatim)
What to use:
- data.current_position.{latitude, longitude, speed_knots, course_degrees, navigational_status, timestamp_utc}
- data.route.{departure_port, destination_port, avg_speed_knots}
- data.last_port_visits to confirm supply chain provenance and dwell
Set hours up to 168 for a 7-day track; include_route, include_predicted_eta, and include_weather are available if you want those sections enriched in the response.
JavaScript: Track a reefer and compute simple closure logic
async function trackVessel(mmsi) {
const url = new URL("https://vessels-api.com/api/V1/vessels/track");
url.searchParams.set("mmsi", mmsi);
url.searchParams.set("hours", "48");
const res = await fetch(url.toString(), {
headers: {"X-API-Key": "YOUR_API_KEY"}
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const envelope = await res.json();
const d = envelope.data || {};
const pos = d.current_position || {};
const last = (d.last_port_visits || [])[0];
return {
lat: pos.latitude,
lon: pos.longitude,
speed_knots: pos.speed_knots,
course_deg: pos.course_degrees,
last_port: last ? last.port_name : null,
last_arrival_utc: last ? last.arrival_time : null
};
}
trackVessel("258785000").then(console.log).catch(console.error);
Step 3: Expected arrivals — when to stage plugs and labor
Use GET /port/expected-arrivals to pull vessels en route to a port with ETA and their departure port. Filter or prioritize by vessel_type “Reefer” in your application layer.
cURL: Expected arrivals for a port
Python: Plan reefer plugs for the next 36 hours
import requests
from datetime import datetime, timedelta, timezone
API_KEY = "YOUR_API_KEY"
BASE = "https://vessels-api.com/api/V1"
PORT = "ARBUE" # UNLOCODE
r = requests.get(f"{BASE}/port/expected-arrivals",
headers={"X-API-Key": API_KEY},
params={"port": PORT},
timeout=20)
r.raise_for_status()
d = r.json()["data"]
cutoff = datetime.now(timezone.utc) + timedelta(hours=36)
reefer_etAs = []
for v in d.get("expected_arrivals", []):
# sample field names: {mmsi, imo, name, vessel_type, eta, departure_port}
if (v.get("vessel_type") == "Reefer") and v.get("eta"):
try:
eta_dt = datetime.fromisoformat(v["eta"].replace("Z","+00:00"))
except Exception:
continue
if eta_dt <= cutoff:
reefer_etAs.append({
"mmsi": v.get("mmsi"),
"eta_utc": v.get("eta"),
"from": v.get("departure_port"),
"name": v.get("name")
})
print({"reefer_arrivals_next_36h": reefer_etAs})
Use this to create an hourly job that reserves reefer racks and schedules surveyors against inbound ETAs.
Step 4: Build a reefer fleet heartbeat (positions and routes at once)
For dispatch boards and cold-chain control towers, POST /vessels/fleet returns batch positions and optional routes in a single call.
cURL: Two-vessel reefer sample
JavaScript: Render a compact fleet board
async function fleetHeartbeat(vessels) {
const res = await fetch("https://vessels-api.com/api/V1/vessels/fleet", {
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({
vessels,
include_positions: true,
include_routes: true
})
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const env = await res.json();
return (env.data?.vessels || []).map(v => ({
imo: v.imo,
mmsi: v.mmsi,
name: v.name,
lat: v.position?.latitude,
lon: v.position?.longitude,
speed_knots: v.position?.speed_knots,
destination: v.route?.destination_port,
eta: v.route?.eta
}));
}
// Example usage:
fleetHeartbeat([{ imo: "9122556" }, { mmsi: "309374000" }])
.then(console.log)
.catch(console.error);
Step 5: Congestion context for berth planning
Congestion impacts reefer cargo integrity. GET /ports/congestion provides a real-time snapshot and recent wait-time statistics for supported ports using UNLOCODE (e.g., ARBUE, SGSIN, NLRTM). Use this to flag risk when a reefer is approaching a port likely to queue at anchorage.
cURL: Congestion snapshot
Response fields to integrate:
- data.snapshot.{vessels_in_anchorage, vessels_at_berth}
- data.statistics.{avg_wait_time_hours_last_7d, max_wait_time_hours_last_7d, avg_berth_time_hours_last_7d, port_calls_count}
Combine this with /vessels/track for an “ETA x congestion” risk badge on reefer approach cards.
Optional: ESG/compliance for reefer voyages
Cold-chain shippers care about footprint. Use GET /vessels/green for IMO CII emissions context per vessel and period.
cURL: 30-day CII snapshot
Key fields: data.estimated_emissions.co2_tons, co2_per_nm, and cii.rating (A–E). Attach this to booking workflows or carrier scorecards.
Practical implementation notes
- Authentication: every request uses the X-API-Key header; there is no per-endpoint auth difference.
- Envelope: parse {status, success, message, data} and always guard for missing sections.
- Units: distances are nautical miles, speeds are knots, timestamps are ISO 8601 UTC (timestamp_utc or eta fields).
- Pagination: search endpoints return pagination metadata; nearby has a limit parameter. Page over long lists rather than cranking up limit.
- History windows: /vessels/track supports hours up to 168 (7 days). Default is 24 if omitted.
- Filtering: pass ship_type=Reefer to /vessels/nearby or filter on vessel_type client-side for expected arrivals.
- Geofencing: to emulate port boundaries, chain /ports/data for coordinates with /vessels/nearby radius queries and speed/heading filters.
- Caching: for dashboards, consider 30–90 second caches for nearby lists and 2–5 minute caches for congestion snapshots to reduce chatter.
- Errors: handle 400/401/404/422/429/500 as documented; backoff on 429 and display last-good values where possible.
End-to-end example: “Reefer near port” alert pipeline
- Fetch port center with GET /ports/data (port=TARGET) to retrieve latitude/longitude.
- Poll GET /vessels/nearby with ship_type=Reefer and radius=25 NM every 60s.
- Raise an alert when distance_nm ≤ 12 and speed_knots ≥ 8.
- On alert, hydrate card with GET /vessels/track (include last_port_visits and route) to verify provenance and likely terminal.
- Check GET /ports/congestion to flag anchorage risk; increase monitoring frequency if vessels_in_anchorage is non-zero.
- Snapshot /port/expected-arrivals to align plugs and labor for the same window; reconcile ETAs with the tracked vessel’s route.
- Roll all tracked reefers into a POST /vessels/fleet heartbeat for your NOC view.
Security and operability
- Key management: store YOUR_API_KEY in a server-side secret manager; do not expose in client bundles.
- Observability: log the API envelope’s status and message for quick triage; emit latency and success ratios per endpoint.
- Idempotency: reads are GET; the only POST here (/vessels/fleet) is a read-style aggregator with a request body.
- Resilience: if track.predicted_eta is null, fall back to route.eta or derive a simple ETA from distance and speed.
FAQ
Q: How often should I poll for “near port” reefer detection?
A: For approach detection within 25 NM, 30–60 seconds is typical. Cache rows for brief intervals and only re-render when mmsi or distance_nm changes materially.
Q: Can I filter nearby vessels to only reefers?
A: Yes. Pass ship_type=Reefer to GET /vessels/nearby. You can also post-filter by vessel_type in expected arrivals.
Q: What timezone are timestamps in?
A: All timestamps in the responses are UTC (ISO 8601), e.g., 2026-07-30T13:00:10+00:00.
Q: How do I get both positions and routes for several reefers efficiently?
A: Use POST /vessels/fleet with include_positions and include_routes set to true. It returns a compact array for rendering a fleet view.
Q: What if predicted ETA is missing?
A: Check route.eta; if that’s also null, compute a simple ETA using remaining distance (if available) and current speed, and mark it as derived in your UI.
Ship it
With five endpoints—nearby, track, expected arrivals, congestion, and fleet—you can build a reliable “reefer near a port” workflow that alerts at the right moment and prepares the quay team without guesswork. Start building with the Register link, explore parameters in the Documentation, and try server-side tools in the MCP to speed up integration.