API to Track a Livestock Carrier

You need to track a livestock carrier end-to-end: confirm identity, follow live AIS positions, anticipate port calls, and keep ESG/IMO reporting up to date. By the end of this guide you’ll be able to build a production-grade workflow that searches for a livestock carrier, monitors its live track and voyage, checks nearby traffic around key approaches, and retrieves IMO CII emissions metrics — all using one REST API key and one base URL.

What makes livestock carrier tracking operationally different

Unlike typical bulkers or containers, livestock carriers often face tighter biosecurity, welfare, and berth coordination constraints. You usually care about:

• Identity certainty: cross-check IMO/MMSI and vessel particulars when your partner sends only a name.
• Live positions with reliable refresh and history windows for voyage audits.
• Port intelligence: expected arrivals and recent activity to plan berth windows and veterinary inspection resources.
• ESG and compliance: IMO CII scoring with a consistent calculation envelope for internal and external reporting.

The endpoints below map directly to these jobs, using a consistent response format: {status, success, message, data}.

Core endpoints for a livestock carrier workflow

1) Identify the vessel: GET /vessels/search

When operations share only a partial or misspelled name, use fuzzy search and optional filters to lock onto the target livestock carrier. You can also match on IMO or MMSI directly.

• Endpoint: GET /vessels/search
• Filters: ship_type, flag, year_built_from/to, DWT/TEU ranges, pagination
• Response shape: vessels array plus pagination metadata

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

Tip: store the returned IMO and MMSI; all downstream calls accept either identifier. Use pagination (per_page up to 100) to handle common name families.

2) Live positions, voyage, and history: GET /vessels/track

This is the centerpiece for a livestock carrier tracker. It returns the current AIS fix, up to 168 hours of history, the active voyage (departure/destination, ETA), and optional weather. You can also request predicted ETA when available.

• Endpoint: GET /vessels/track
• Required: imo OR mmsi
• Optional: hours (default 24, max 168), include_route, include_predicted_eta, include_weather

Official sample (copy-paste exactly to verify connectivity and parse the schema):

{
"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:24+00:00",
"age_minutes": 5116160,
"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 you’ll actually use day-to-day:

• data.current_position: latitude/longitude, speed_knots, course_degrees, and timestamp_utc (ISO8601, UTC).
• data.route: departure_port, destination_port, eta — critical for berth planning; distance_nm and avg_speed_knots help sanity-check ETAs.
• data.last_port_visits: useful for compliance audits and voyage recaps.
• data.predicted_eta and data.weather when requested for higher-fidelity ETA and safety routing.

Python example retrieving the same endpoint and normalizing a fleet dashboard record:

import os
import requests
from datetime import datetime, timezone

API_KEY = os.getenv("VESSELS_API_KEY", "YOUR_API_KEY")
BASE = "https://vessels-api.com/api/V1"

def track_vessel_by_mmsi(mmsi: str, hours: int = 48) -> dict:
url = f"{BASE}/vessels/track"
params = {"mmsi": mmsi, "hours": hours}
r = requests.get(url, headers={"X-API-Key": API_KEY}, params=params, timeout=15)
r.raise_for_status()
payload = r.json()
assert payload.get("success") is True, payload
d = payload["data"]
cp = d.get("current_position") or {}

# Normalize a minimal record for UI/alerts
ts = cp.get("timestamp_utc")
ts_dt = datetime.fromisoformat(ts.replace("Z", "+00:00")) if ts else None
return {
"mmsi": d["vessel"].get("mmsi"),
"imo": d["vessel"].get("imo"),
"lat": cp.get("latitude"),
"lon": cp.get("longitude"),
"speed_kn": cp.get("speed_knots"),
"course_deg": cp.get("course_degrees"),
"nav_status": cp.get("navigational_status"),
"fix_time_utc": ts_dt.astimezone(timezone.utc).isoformat() if ts_dt else None,
"dest_port": (d.get("route") or {}).get("destination_port"),
"eta_utc": (d.get("route") or {}).get("eta"),
"last_ports": d.get("last_port_visits") or []
}

if __name__ == "__main__":
rec = track_vessel_by_mmsi("258785000", hours=48)
print(rec)

3) See what’s around your approach lanes: GET /vessels/nearby

Livestock discharge often has narrow time windows. Checking nearby traffic before pilot boarding or anchorage approach helps coordinate tugs and pier readiness.

• Endpoint: GET /vessels/nearby
• Required: latitude, longitude
• Optional: radius (NM, default 50, max 200), ship_type filter, limit

Use the returned vessels[].distance_nm and position.timestamp_utc to sort by nearest and freshest targets. Cache these calls briefly (e.g., 1–2 minutes) for operational maps to avoid rate bursts.

4) Plan port-side resources: GET /port/expected-arrivals and GET /port/activity

To stage vets, feed, and berth windows, you need to know who’s coming and who just left.

• Expected arrivals: GET /port/expected-arrivals?port=PORT_ID
• Recent movements: GET /port/activity?port=PORT_ID

Fields you’ll rely on include expected_arrivals[].eta and departure_port for inbound leg context, and arrivals[]/departures[] timestamps to quantify port rhythm.

5) ESG and compliance for livestock voyages: GET /vessels/green

Livestock carriers are often in scope for ESG dashboards. Use the CII endpoint to fetch period-bound emission estimates and the resulting rating for reporting and internal goals.

• Endpoint: GET /vessels/green
• Required: imo OR mmsi
• Optional: period=24h|7d|30d|1y (default 30d)
• Output: estimated_emissions.co2_tons, cii.rating (A–E), cii.score, regulation_reference

Persist the period and rating alongside voyage legs in your database so monthly reports remain auditable against the original calculation window.

End-to-end flow to track a livestock carrier

Here’s a robust pattern you can implement with minimal glue code:

1. Resolve identity via GET /vessels/search (by name) → store IMO and MMSI.
2. Start a polling job for GET /vessels/track every N minutes:
   • N can be tighter near port approaches and relaxed on ocean legs.
   • Use hours=48 or hours=168 when reconstructing a voyage for audit.
3. For approach coordination, call GET /vessels/nearby on port approaches or pilot boarding areas to see traffic density in a 10–30 NM radius.
4. For berth planning, read GET /port/expected-arrivals for the destination port once per hour and GET /port/activity every 30–60 minutes during busy windows.
5. For ESG, run GET /vessels/green nightly with period=30d for rolling CII. Store changes to score and rating.

All endpoints return a consistent JSON envelope with status and success flags — check those first for fast error triage.

Data model and response envelope

Every response follows {status, success, message, data}. This allows you to centralize error handling and logging. For example:

• 200 OK with success=true → process data
• 400/422 → your parameters need correction (e.g., missing mmsi or radius out of range)
• 401 → check your X-API-Key header
• 404 → vessel/port not found (verify identifiers)
• 429 → back off; employ jittered retries
• 500 → transient; capture request ID if returned in headers and retry with exponential backoff

Timestamps are ISO8601 UTC (e.g., 2026-04-30T09:00:00+00:00). Distance units are nautical miles (nm). Speeds are in knots. Angles are degrees. The nearby radius is also in nautical miles.

Practical implementation details that save time

• Authentication: send X-API-Key: YOUR_API_KEY on every request. No OAuth, no per-endpoint differences.
• Polling cadence: use adaptive intervals — e.g., 2–5 minutes within 50 NM of destination, 10–20 minutes on ocean passages.
• Caching: cache /vessels/nearby and /port/* responses for 60–180 seconds to smooth UI maps without missing changes.
• Pagination: for /vessels/search, respect pagination metadata; per_page supports up to 100.
• History depth: /vessels/track can return up to 168 hours of history. Use this to run after-action reviews of sensitive livestock voyages.
• Single source: keep both identifiers (IMO and MMSI) in your vessel record; MMSI can change, IMO does not.
• Alerts: trigger alerts on changes to route.destination_port or route.eta, and on nav status transitions (e.g., from underway to at anchor).

When to combine endpoints for livestock ops

• Berth ETAs with crowding: merge /vessels/track.route.eta with a /vessels/nearby scan of the pilot boarding ground to estimate congestion risk.
• Compliance snapshots: pair /vessels/track (to capture the current voyage) with /vessels/green over the same period window for a narrative that joins movements and emissions.
• Port staffing: query /port/expected-arrivals to forecast dockside veterinary checks, and back-check completions via /port/activity departures.

Reference links

• Register
• Documentation
• MCP

FAQ

How often can I refresh live AIS positions?
The API supports near real-time updates. Choose a polling interval that fits your operations and watch for 429 responses, which indicate you should back off temporarily.

Should I use IMO or MMSI to track a livestock carrier?
Both are supported. Prefer IMO for stable identity across refits and registry changes. Use MMSI when you’re keyed to AIS radio identity and radio change events are in your workflow.

Can I get predicted ETA and weather in the same call?
Yes. Use GET /vessels/track with include_predicted_eta=true and include_weather=true to return those sections alongside the current_position, route, and history.

What time zone are timestamps in?
All timestamps are returned in UTC (ISO8601). Convert on the client only for display; keep UTC in your database for consistent analytics.

How do I monitor multiple livestock carriers at once?
Use POST /vessels/fleet with a list of {imo, mmsi} to fetch positions and routes in one batch request. This reduces request overhead for fleet dashboards.

Build your livestock carrier tracker now

Use the official sample call above to validate your integration, then wire up search, track, nearby, port arrivals, and CII into a single dashboard. One API key, one base URL, consistent JSON — it’s enough to ship a reliable workflow for time-critical livestock operations. When you’re ready to implement, read the endpoint details in the Documentation, explore server capabilities with the MCP, and Register to start your 7-day trial and deploy your tracker.