Livestock Carrier Near a Port

You have a time-sensitive question: “Is there a livestock carrier near this port, and when will it berth?” By the end of this post you’ll be able to programmatically detect livestock carriers near any port, pull live AIS tracks and recent routes, check port congestion, and surface ETAs and ESG signals in your own dashboard or workflow—using a single, consistent REST API.

What we’ll build for a livestock carrier near a port

This walkthrough focuses on four data jobs you’ll repeatedly need around livestock carriers and port calls:

• Detect livestock carriers within X nautical miles of a port coordinate.
• Drill into a specific vessel’s live track, route, and port visits to validate the approach and timing.
• Check current port congestion to estimate anchorage and berth dynamics.
• Pull expected arrivals and emissions scoring for operational and ESG overlays.

All examples use the same base URL and header:

• Base URL: https://vessels-api.com/api/V1
• Auth: X-API-Key: YOUR_API_KEY
• Response envelope: {status, success, message, data}

Reference: Documentation • Try tools: MCP • Get an API key: Register

1) Find livestock carriers near a port coordinate

Use GET /vessels/nearby to list all vessels inside a radius from a lat/lon. You can filter by ship_type and control the radius (NM). For a port, pass its centroid coordinates; for example, Singapore or Buenos Aires from your own port database or the /ports catalog.

cURL: detect vessels within 30 NM

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

Response (shape):

{
    "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:26+00:00",
            "age_minutes": 5136380,
            "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 to use: distance_nm to rank proximity, speed_knots and course_degrees to infer approach vectors, navigational_status to separate “under way” vs. “moored/anchored,” and timestamp_utc to age-check positions (UTC ISO-8601).

JavaScript: poll nearby and filter

async function getLivestockCarriersNearPort(lat, lon, radiusNm = 30) {
const url = new URL("https://vessels-api.com/api/V1/vessels/nearby");
url.searchParams.set("latitude", lat);
url.searchParams.set("longitude", lon);
url.searchParams.set("radius", radiusNm);
url.searchParams.set("ship_type", "Livestock Carrier");
url.searchParams.set("limit", "100");

const res = await fetch(url.toString(), {
headers: { "X-API-Key": "YOUR_API_KEY" }
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const json = await res.json();

// Normalize and sort by proximity
const vessels = (json.data?.vessels || [])
.filter(v => typeof v.distance_nm === "number")
.sort((a, b) => a.distance_nm - b.distance_nm);

return vessels.map(v => ({
mmsi: v.mmsi,
name: v.name,
distance_nm: v.distance_nm,
speed_knots: v.speed_knots,
course: v.course_degrees,
last_seen: v.position?.timestamp_utc
}));
}

// Example: Buenos Aires approx. coordinates
getLivestockCarriersNearPort(-34.60, -58.38, 30)
.then(list => console.log(list))
.catch(err => console.error(err));

Tips:

• Use limit to cap results; default is 50.
• Cache results briefly (e.g., 15–30 seconds) if you’re rendering a map; AIS refresh rates are near real-time, but UI churn increases CPU.
• If you need a port’s exact centroid, call GET /ports and match by name/country, or GET /ports/data for a single port by ID.

2) Inspect the vessel’s live track, route, and port visits

Once you identify a candidate MMSI, use GET /vessels/track to retrieve current_position, position_history (up to 168h), route, and recent port calls. This is essential to confirm a true approach versus a drift, circle, or diversion.

Official sample: MMSI 258785000 track

Copy and run the official call below (hours=48). The JSON is shown exactly as provided.

What to use:

• current_position.speed_knots and navigational_status to assess movement vs. alongside/anchored. Status is numeric; treat non-zero speed and steady course as approaching behavior.
• route fields to validate declared voyage legs; when eta is available, display it. predicted_eta may also be present if you request include_predicted_eta.
• last_port_visits to understand live biosecurity or inspection flow relevant to livestock cargo handling.
• All timestamps are UTC ISO-8601. age_minutes can be used for staleness checks.

Python: poll a specific MMSI and extract approach details

import requests
from datetime import datetime, timezone

API = "https://vessels-api.com/api/V1"
HEADERS = {"X-API-Key": "YOUR_API_KEY"}

def track_mmsi(mmsi: str, hours: int = 24):
params = {"mmsi": mmsi, "hours": hours, "include_route": "true", "include_predicted_eta": "true"}
r = requests.get(f"{API}/vessels/track", headers=HEADERS, params=params, timeout=20)
r.raise_for_status()
payload = r.json()["data"]

vessel = payload.get("vessel", {})
pos = payload.get("current_position", {}) or {}
route = payload.get("route", {}) or {}

return {
"mmsi": vessel.get("mmsi"),
"imo": vessel.get("imo"),
"speed_knots": pos.get("speed_knots"),
"course_degrees": pos.get("course_degrees"),
"nav_status": pos.get("navigational_status"),
"last_seen_utc": pos.get("timestamp_utc"),
"declared_destination": pos.get("destination"),
"eta_declared": pos.get("eta"),
"route_destination_port": route.get("destination_port"),
"route_eta": route.get("eta"),
"avg_speed_knots": route.get("avg_speed_knots"),
}

if __name__ == "__main__":
data = track_mmsi("258785000", hours=48)
print(data)

Notes:

• hours parameter defaults to 24; max is 168.
• Check both declared ETA (current_position.eta) and route.eta when present.
• If position_history is empty, you still have the current position and route snapshot.

3) Check port congestion before a livestock carrier call

Use GET /ports/congestion to see near-real-time anchorage and berth snapshots, plus recent wait-time statistics. This helps determine whether a livestock carrier should expect to anchor or can proceed straight to berth.

cURL: congestion for a port (e.g., ARBUE)

What to use:

• snapshot.vessels_in_anchorage and snapshot.vessels_at_berth for the current operational picture.
• statistics.avg_wait_time_hours_last_7d and max_wait_time_hours_last_7d to inform ETA buffers and livestock welfare planning.
• All timestamps and derived stats are scoped to the period parameter you choose (24h, 3d, or 7d).

4) Anticipate livestock carrier ETAs and origins

Use GET /port/expected-arrivals to list vessels inbound to a port with ETA and their last departure port. This is useful to cross-check a livestock carrier’s declared destination and timing.

cURL: inbound list for a port

Response (shape):

What to use:

• eta to fuel your arrival board and gating logic for cold-chain or animal welfare teams.
• departure_port to surface voyage provenance and plan inspections or biosecurity.

5) Add ESG context with IMO CII scoring

For sustainability reporting or charterer policies, GET /vessels/green provides a period-scoped IMO CII estimate with rating A–E. You can read it per livestock carrier and display distance-normalized emissions for transparency.

cURL: 30-day CII snapshot

Response (shape):

What to use: cii.rating for quick categorization, co2_per_nm for comparable intensity across voyages, and period to ensure your dashboards align with reporting windows (24h, 7d, 30d, 1y).

Optional: search and fleet roll-ups

If you don’t have MMSIs on hand, start with GET /vessels/search using ship_type=Livestock Carrier or a fuzzy name/IMO/MMSI query. For operational control rooms, POST /vessels/fleet lets you retrieve positions and routes for many MMSIs/IMOs in one call.

cURL: search by type and flag

Response (shape):

cURL: batch track a fleet subset

Use cases:

• Build a “livestock near port” widget that calls /vessels/nearby every 30–60 seconds, then hydrates a detail pane via /vessels/track on selection.
• Overlay port congestion to shade the map by anchorage pressure.
• Attach CII ratings in your carrier roster to support selection and chartering guardrails.

Implementation details that save time

• Authentication: all endpoints accept the same X-API-Key header. There’s no OAuth flow or per-endpoint differences.
• Response shape: every route returns the same {status, success, message, data} envelope—safe to build a single client wrapper.
• Units and time: distances in nautical miles (nm), speeds in knots, timestamps in UTC ISO-8601.
• Pagination: for search endpoints, use page and per_page (up to 100). Read pagination.last_page to know when to stop.
• Error handling: 400 for missing/invalid parameters, 401 for auth, 404 not found, 422 range issues, 429 for rate limits, 500 server errors. Treat non-200 as retryable only when appropriate.
• Data scope: /vessels/track hours parameter caps historical lookback to 168 hours; request what you need to keep payloads light.

Putting it together: livestock-carrier-near-port workflow

1. Resolve target port coordinates via GET /ports or GET /ports/data.
2. GET /vessels/nearby with ship_type=Livestock Carrier and a radius that matches your ops window (e.g., 30–50 NM).
3. For each candidate, GET /vessels/track to confirm declared destination, live speed/course, and last port visits.
4. GET /ports/congestion to factor in anchorage/berth pressure; widen ETA buffers if wait times are elevated.
5. Optionally GET /port/expected-arrivals to cross-verify ETAs and recent legs, and GET /vessels/green to embed CII context.

FAQ

Q: How fresh is the AIS position in /vessels/nearby and /vessels/track?
A: Each position includes timestamp_utc (UTC ISO-8601). Use it or age_minutes (on /vessels/track) to verify staleness before acting.

Q: Can I limit results to livestock carriers only?
A: Yes. Pass ship_type=Livestock Carrier to /vessels/nearby or /vessels/search. Keep spelling consistent with your UI labels.

Q: How do I get expected arrivals for a port?
A: Call GET /port/expected-arrivals with port=PORT_ID. You’ll get mmsi/imo/name, vessel_type, eta, and departure_port for inbound vessels.

Q: Do I need different auth for ports vs. vessels?
A: No. All endpoints use the same X-API-Key header against the same base URL.

Q: What does the CII rating represent in /vessels/green?
A: It’s an IMO CII A–E categorical rating with a numeric score and period scoping, aligned with IMO MEPC.339(76). Use it for ESG overlays and policy gates.

Build a “livestock carrier near a port” feature that your ops and compliance teams can trust, without juggling multiple data sources or auth flows. Start with the examples above, then dive deeper into filters, routes, and analytics in the official docs. Get your key here: Register, read the Documentation, and test queries live in the MCP.