Reefer Ship Search API

You’re shipping temperature-sensitive cargo and need to put a reefer vessel on a screen: find it by name or IMO/MMSI, confirm it’s really a reefer, check its live AIS track, predict when it will hit the pilot station, and alert ops if congestion will delay berth windows. By the end of this guide, you’ll search for reefer ships, track them in near real time, assemble a reefer fleet dashboard, and plug in ESG scoring — all using a consistent REST interface at vessels-api.com.

Why a dedicated Reefer Ship Search and Tracking workflow matters

Reefer vessels run on tight cold-chain SLAs. Slippage at origin, slow steam, or queueing at congested ports can compromise cargo quality. Developers building logistics, ops, or visibility apps need reliable, low-friction AIS data that’s structured the same way across endpoints and scales from a single voyage tracker to an enterprise reefer fleet view.

vessels-api.com provides:

18 REST endpoints for vessel search, live tracking, fleet ops, port intelligence, emissions (IMO CII), and a premium real-time AIS feed
One API key, one base URL; send X-API-Key and ship; no OAuth, no 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 (see docs for details)

Target users include developers, logistics startups, fleet managers, port operators, and ESG/compliance teams.

Endpoints you’ll use for a Reefer Ship Search API

For reefer-centric workflows, the following endpoints cover the core jobs to be done:

GET /vessels/search — find reefers by name, IMO, MMSI, or filter by ship_type
GET /vessels/track — live position, up to 168h history, route, and predicted ETA
POST /vessels/fleet — batch positions/routes/stats for reefer fleets
GET /port/expected-arrivals — inbound reefer ETAs to a specific port
GET /vessels/green — IMO CII emissions scoring for ESG reporting

All endpoints share the same base URL and authentication:

Base URL: https://vessels-api.com/api/V1
Auth: X-API-Key: YOUR_API_KEY

See the full API reference here: Documentation

Search for reefer vessels

Use GET /vessels/search with a query string and optional filters. For reefers, the most useful filter is ship_type. You can also constrain by flag, DWT/TEU, and build year. Pagination is available via page and per_page (max 100).

cURL example: find reefers with a fuzzy name search

curl -H "X-API-Key: YOUR_API_KEY" "https://vessels-api.com/api/V1/vessels/track?mmsi=258785000&hours=48"

Sample response fields you’ll use:

{
"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:35+00:00",
"age_minutes": 5101700,
"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
}
}

Notes:

query supports fuzzy matching for names, and direct lookups by IMO or MMSI strings.
ship_type accepts values like Reefer to filter down to refrigerated cargo vessels.
All timestamps across the API are UTC. Distances are in nautical miles, speeds in knots.

Python example: search, verify reefer type, and store IDs

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://vessels-api.com/api/V1"

def search_reefer(query, per_page=50):
url = f"{BASE}/vessels/search"
params = {"query": query, "ship_type": "Reefer", "per_page": per_page}
r = requests.get(url, headers={"X-API-Key": API_KEY}, params=params, timeout=20)
r.raise_for_status()
payload = r.json()
if not payload.get("success"):
raise RuntimeError(payload.get("message", "API error"))
vessels = payload["data"]["vessels"]
# Map to a simple structure your app can use
return [
{
"imo": v.get("imo"),
"mmsi": v.get("mmsi"),
"name": v.get("name"),
"flag": v.get("flag"),
"length_m": v.get("length_m"),
"width_m": v.get("width_m"),
}
for v in vessels
]

reefer_hits = search_reefer("star")
for v in reefer_hits:
print(v["imo"], v["mmsi"], v["name"])

Track a reefer in near real time

Once you have IMO or MMSI from the search step, call GET /vessels/track. You can request up to 168 hours of position history and optionally include predicted ETA and route metadata.

Official cURL: documented track for MMSI 258785000 (48h)

Official JSON response (copy/paste from docs):

What to use from this payload:

data.current_position: latitude/longitude, speed_knots, course_degrees, timestamp_utc
data.route: departure_port, destination_port, eta, avg_speed_knots
data.last_port_visits: event trail for analytics, dwell calculations, or exception detection
Optional include_predicted_eta and include_route parameters can return route and ETA fields as needed

Python example: draw a live marker and compute late vs ETA

import requests
from datetime import datetime, timezone

API_KEY = "YOUR_API_KEY"
BASE = "https://vessels-api.com/api/V1"

def track_vessel(mmsi, hours=24):
url = f"{BASE}/vessels/track"
params = {"mmsi": mmsi, "hours": hours}
r = requests.get(url, headers={"X-API-Key": API_KEY}, params=params, timeout=20)
r.raise_for_status()
payload = r.json()
if not payload.get("success"):
raise RuntimeError(payload.get("message", "API error"))
return payload["data"]

t = track_vessel("258785000", hours=48)
pos = t["current_position"]
lat, lon = pos["latitude"], pos["longitude"]
ts = pos["timestamp_utc"] # ISO 8601 UTC
route = t.get("route") or {}
eta_iso = route.get("eta")
now = datetime.now(timezone.utc)

print(f"Marker at {lat},{lon} (knots={pos['speed_knots']}, course={pos['course_degrees']})")
if eta_iso:
eta = datetime.fromisoformat(eta_iso.replace("Z", "+00:00"))
late_minutes = int((now - eta).total_seconds() / 60)
status = "late" if late_minutes > 0 else "early/on-time"
print(f"Predicted ETA {eta_iso} → {status} by {abs(late_minutes)} minutes")

Build a reefer fleet dashboard with one request

POST /vessels/fleet batches multiple vessels into a single response. Include IMO or MMSI for each item; toggle include_positions and include_routes for what your UI actually needs.

cURL example: two reefer hulls, positions and routes

Sample response snippet (focus on fields your dashboard needs):

Tips:

Use fleet.vessels_at_sea to color-code cards or filter for active reefers.
If your UI doesn’t show routes, set include_routes to false to reduce payload size.
Batching cuts round-trips vs. hammering /vessels/track per vessel and keeps rate limits comfortable.

Port arrivals for cold-chain slotting

GET /port/expected-arrivals lists vessels headed to a port with ETA and origin. Use this to pre-allocate plugs, cranes, or drayage for inbound reefers. Combine with a /vessels/search reefer filter on your end to spotlight reefer hulls if needed.

cURL example: expected arrivals to ARBUE

Sample response structure:

Implementation notes:

All timestamps are UTC. Consider rendering local time using the port’s timezone from GET /ports.
To build a live arrivals board, poll this endpoint on an interval suited to your UI latency budget.

ESG: IMO CII for reefer fleets

Reefer vessels consume additional power for refrigerated cargo, so IMO CII monitoring matters. GET /vessels/green returns an estimated emissions profile and the CII score/rating per period. Ratings are A (best) to E (worst), based on IMO MEPC.339(76).

cURL example: 30-day CII for a reefer MMSI

Sample response fields:

What to do with it:

Flag outliers at the voyage or fleet level (e.g., D/E ratings) for operational improvement.
Export to compliance dashboards alongside port calls and voyage segments.

Optional: Nearby reefers for last-mile cold-chain pivoting

Need a backup reefer within 50 NM to pick up a delayed load? GET /vessels/nearby searches around a lat/lon with an optional ship_type filter.

cURL example: 30 NM around Buenos Aires

Sample response structure:

Use cases:

Identify alternates for time-sensitive cargo swaps.
Geofence-based notifications when a reefer enters a service area.

End-to-end reefer visibility flow

Search and confirm vessel type: GET /vessels/search with ship_type=Reefer
Track the active voyage: GET /vessels/track with include_route and (optionally) include_predicted_eta
Contextualize port-side ops: GET /port/expected-arrivals for ETAs to your terminal
Roll up the fleet: POST /vessels/fleet with include_positions=true for your board
Attach ESG metadata: GET /vessels/green, store CII score/rating per period

Implementation details that save time

Authentication: Every endpoint uses X-API-Key: YOUR_API_KEY. No per-endpoint differences.
Units: Distances are nautical miles (nm). Speeds are knots. Timestamps are ISO 8601 UTC.
Pagination: /vessels/search returns pagination with current_page, per_page (max 100), total, last_page.
Error handling: 400 for invalid parameters; 401 for missing/invalid API key; 404 when a vessel/port isn’t found; 422 for out-of-range parameters; 429 for rate limits; 500 for server errors. Always check the top-level {status, success, message} before consuming data.
Polling strategy: For live maps, a 1–5 minute interval is typical. Fleet views can batch at 2–10 minutes depending on UI SLAs.
History depth: /vessels/track supports up to 168 hours via hours=; request only as much as your chart needs.
Consistency: Every response is wrapped in {status, success, message, data}. Code against this envelope to avoid special cases.

Minimal JS snippet for a reefer search form

<script>
async function searchReefers(q) {
const url = new URL("https://vessels-api.com/api/V1/vessels/search");
url.searchParams.set("query", q);
url.searchParams.set("ship_type", "Reefer");
url.searchParams.set("per_page", "25");

const res = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } });
const json = await res.json();
if (!json.success) throw new Error(json.message || "API error");
return json.data.vessels.map(v => ({
id: v.imo || v.mmsi,
name: v.name,
type: v.vessel_type,
dims: `${v.length_m}m × ${v.width_m}m`
}));
}

searchReefers("star").then(console.log).catch(console.error);
</script>

Frequently asked questions

How do I ensure I’m only listing reefer vessels in search results?
Pass ship_type=Reefer to GET /vessels/search. In your UI, also check vessel_type on each result to display type badges or to filter again client-side.

What’s the difference between ETA in current_position and route.eta?
current_position may include eta when broadcast by AIS. route.eta is part of the computed route object when include_route is available; you can also request include_predicted_eta to surface prediction fields where supported. Both are UTC.

How often should I poll for live reefer positions?
For map tiles or markers, 1–5 minutes is common. For management dashboards, 2–10 minutes is usually sufficient. If you’re using /vessels/fleet, batch multiple IDs to reduce request overhead.

Can I get emissions scoring for a specific reporting window?
Yes. GET /vessels/green supports period=24h|7d|30d|1y (default 30d). The response includes cii.score and cii.rating (A–E) plus the regulation reference.

How do I handle “vessel not found” when tracking?
Check for 404 and fall back to a last-known position endpoint (e.g., legacy /vessel/mmsi-position) if that suits your UX, or prompt the user to verify IMO/MMSI. Always validate success before reading data.

Get started

Spin up a reefer search-and-track prototype in an afternoon using the consistent JSON envelope and a single API key. Register your key, open the docs, and explore the MCP tools:

Use GET /vessels/search with ship_type=Reefer to build your index, wire up GET /vessels/track for live AIS, and add POST /vessels/fleet for a clean dashboard view. When you’re ready, layer in /port/expected-arrivals and /vessels/green for cold-chain scheduling and ESG reporting.