API to Track a Oil Tanker

You need to track an oil tanker in real time, compute reliable ETAs, and feed port ops and ESG dashboards—all from a single API. By the end of this guide you’ll be able to search for a specific oil tanker, stream its live AIS position (with route and recent port calls), aggregate voyage analytics, and pull IMO CII emissions scoring using vessels-api.com.

What you’ll build with vessels-api.com

Vessels API is a transportation-focused REST API that exposes global AIS-powered vessel data through a consistent, developer-friendly surface:

• 18 REST endpoints for vessel search, live tracking, fleet operations, port intelligence, and IMO CII emissions.
• One API key, one base URL, no OAuth: X-API-Key in the header.
• Consistent JSON envelope on every response: {status, success, message, data}.
• Near real-time AIS refresh rates across global coverage.

We’ll focus on the endpoints that matter most for oil tankers:

• /vessels/search — find the tanker you need to track.
• /vessels/track — live position, route, ETA, and 168h history.
• /vessels/analytics — voyage stats for a single tanker or mini-fleet.
• /vessels/fleet — batch retrieval for multiple tankers.
• /vessels/green — IMO CII scoring for compliance and ESG.

API basics you’ll use repeatedly

• Base URL: https://vessels-api.com/api/V1
• Authentication: add the header X-API-Key: YOUR_API_KEY
• HTTP methods: all GET except POST /vessels/fleet
• Timezones: AIS timestamps are UTC (timestamp_utc)
• Speed/Distance units: knots (speed_knots), nautical miles (distance_nm)
• Pagination: search endpoints return a pagination block; use per_page up to 100
• Error handling: 400 (invalid params), 401 (missing/invalid key), 404 (not found), 422 (out of range), 429 (rate limit), 500 (server)

Step 1 — Find the oil tanker to track

Use /vessels/search to locate a specific tanker by IMO, MMSI, or fuzzy name. You can filter by attributes like ship_type=Oil Tanker, flag, year built, or DWT to narrow results. The response includes core particulars and a pagination block so you can iterate through result sets predictably.

Endpoint

GET /vessels/search — Optional filters: ship_type, flag, min_dwt/max_dwt, year_built_from/year_built_to, page, per_page (max 100)

cURL example

This example shows a fuzzy text search with a flag filter. To filter specifically for oil tankers, add &ship_type=Oil%20Tanker to this request.

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

Key fields you’ll use:

• vessels[].imo, vessels[].mmsi — stable identifiers for all downstream requests
• vessels[].vessel_type — verify the candidate is an “Oil Tanker”
• vessels[].deadweight_tonnage — useful for operational filtering and ESG context

Tip: Always store both IMO and MMSI; most vessel endpoints accept either, and MMSI can change across reflagging, while IMO is persistent.

Step 2 — Live-track the tanker with route and ETA

/vessels/track provides the tanker’s current position, optional 24–168 hour history, active route, predicted ETA, and recent port visits. This is the core feed for dashboards and alerting.

Official cURL (Oil Tanker track)

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:27+00:00",
"age_minutes": 5103140,
"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 read from this payload

• data.vessel.imo/mmsi — identifiers to persist for future calls.
• current_position.latitude/longitude — plot on a chart; note UTC timestamp in timestamp_utc.
• current_position.speed_knots, course_degrees — drive track vectors; speed is in knots.
• route.departure_port, destination_port, eta — power ETAs and leg visibility; eta is UTC.
• last_port_visits[] — list recent port calls for logistics event timelines.
• predicted_eta, weather — include when requested via flags; use to refine downstream ETAs or safety checks.

Notes for production:

• hours defaults to 24 and maxes at 168. For oil tanker voyage analysis, 48–96 hours typically balances context with payload size.
• Position ages vary by reception and coverage; timestamp_utc and age_minutes tell you data freshness, so you can flag stale AIS.
• Destination and ETA fields depend on AIS inputs; combine with route.eta for a resilient ETA UI.

Python example: track the tanker and compute a simple ETA notice

import requests
from datetime import datetime, timezone

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

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

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

# Extract essentials
lat = pos.get("latitude")
lon = pos.get("longitude")
speed_kn = pos.get("speed_knots")
ts = pos.get("timestamp_utc")
dest_port = route.get("destination_port")
eta_utc = route.get("eta") # string in UTC

# Format a human notice
ts_str = ts or "unknown"
if eta_utc:
eta_dt = datetime.fromisoformat(eta_utc.replace("Z", "+00:00")).astimezone(timezone.utc)
eta_note = f"ETA {eta_dt.isoformat()}"
else:
eta_note = "ETA unavailable"

return {
"imo": vessel.get("imo"),
"mmsi": vessel.get("mmsi"),
"position": {"lat": lat, "lon": lon, "speed_kn": speed_kn, "timestamp_utc": ts_str},
"route": {"destination_port": dest_port, "eta_utc": eta_utc},
"notice": f"Tanker MMSI {vessel.get('mmsi')} at {lat},{lon} {speed_kn} kn → {dest_port or '—'} | {eta_note}"
}

if __name__ == "__main__":
info = track_tanker("258785000", hours=48)
print(info["notice"])

Step 3 — Batch multiple oil tankers with one request

If you operate or monitor a pool of oil tankers, POST /vessels/fleet returns positions and routes in one payload. This is the right fit for dashboards and scheduled jobs where you want a single, consistent envelope per polling cycle.

Endpoint

POST /vessels/fleet — Body: {"vessels":[{"imo","mmsi"}, ...], include_positions, include_routes}

cURL example

Use cases for oil tankers:

• Control tower views showing which tankers are at sea vs in port.
• Alerts for significant course or speed changes during laden voyages.
• Batch ETAs to downstream terminals for schedule alignment.

Step 4 — Voyage analytics for operations and planning

/vessels/analytics aggregates voyage statistics like total distance, average speed, and port calls—useful for ops KPIs and trend dashboards across tanker voyages.

Endpoint

GET /vessels/analytics — Required: type=vessel|port|fleet. For a single tanker: type=vessel plus imo or mmsi. Optional period=24h|7d|30d|90d.

cURL example

Key fields:

• statistics.total_distance_nm — voyage miles sailed in period for fuel and schedule planning.
• statistics.avg_speed_knots, max_speed_knots — performance baselines; corroborate ETAs.
• port_calls_count, total_time_in_port_hours — terminal coordination and dwell analytics.

Step 5 — IMO CII emissions scoring for ESG

Most oil tanker operators must track CII. /vessels/green returns estimated emissions and a CII rating (A through E) consistent with IMO MEPC.339(76). Use it to feed compliance dashboards and portfolio-wide ESG reporting.

Endpoint

GET /vessels/green — Required: imo or mmsi. Optional period=24h|7d|30d|1y (default 30d).

cURL example

Key fields:

• estimated_emissions.co2_tons and co2_per_nm — use directly for reporting footprints.
• cii.score and cii.rating — meaningful letter grade for compliance thresholds.

Optional — Port congestion for arrival planning

When routing an oil tanker to discharge or load, congestion at the destination port affects berthing and turnaround. /ports/congestion gives a near-term snapshot and recent wait-time statistics for supported ports.

Endpoint

GET /ports/congestion — Required: port_id (UNLOCODE in parentheses from listing, e.g., ARBUE, SGSIN, NLRTM). Optional: period=24h|3d|7d.

cURL example

Operational tip: Combine route.eta from /vessels/track with congestion statistics to produce a confidence range and advise terminal teams of potential slippage.

Architecture and integration notes for transportation use cases

Data flow pattern

1. Resolve target tanker identifiers via /vessels/search (store imo and mmsi).
2. Poll /vessels/track for each monitored tanker every N minutes; retain last payload to compute deltas (track points, speed changes).
3. For dashboards, use /vessels/fleet to reduce API calls and ensure atomic snapshots per refresh.
4. Call /vessels/analytics daily/weekly for ops KPIs and trend charts.
5. Schedule /vessels/green monthly (or 30d rolling) for ESG reporting.

Caching and state

• Cache static particulars like vessel dimensions from legacy GET /vessel/info?imo=IMO; refresh infrequently.
• Respect timestamp_utc when deduplicating AIS points; use it as the primary time key, not ingestion time.
• Fallbacks: if current_position.destination is null, check route.destination_port; if both are missing, display Unknown while still plotting track.

UI/UX for operations teams

• Show speed_knots with one decimal; color-code navigational_status where helpful.
• Render last_port_visits for context; terminal teams care about durations and last discharge/load.
• Surface age_minutes prominently to indicate stale or delayed AIS receptions.

Error handling and reliability

• 401 Invalid or missing X-API-Key: ensure header propagation across proxies and serverless layers.
• 422 Parameter out of range: hours must be between 1 and 168 for /vessels/track; validate client-side.
• 429 Rate limit exceeded: back off with jitter; cache last good payload and degrade gracefully in UI.
• 404 Vessel not found: check identifier type (IMO vs MMSI); prefer IMO for persistence.

Putting it together: minimal end-to-end workflow

1) Identify the tanker

Use /vessels/search with a fuzzy name and optional ship_type=Oil Tanker to disambiguate. Persist the vessel’s IMO and MMSI.

2) Track live position and route

Call /vessels/track with mmsi=258785000 and hours=48 (see official cURL above). Show current_position and route. If predicted_eta is null, rely on route.eta.

3) Batch for fleet views

Gather your tanker list and POST /vessels/fleet with include_positions=true. Render status badges “At Sea / In Port” from the fleet.vessels_at_sea and vessels_in_port counters alongside each vessel position.

4) Compute ops KPIs

Pull /vessels/analytics weekly for each tanker (type=vessel). Show total_distance_nm and total_time_in_port_hours for schedule planning and SLAs.

5) ESG

Call /vessels/green monthly to capture rolling 30-day CII ratings and CO₂ estimation in tons and per nautical mile.

Additional endpoints you may find useful

• GET /vessels/nearby — find tankers around pilot stations or STS locations. Requires latitude and longitude; optional radius up to 200 NM.
• GET /ports — retrieve the port catalog (248 ports) to power selection UIs with coordinates and timezones.
• GET /ports/data — detailed info and live vessel counts for a single port; useful for arrival boards.

Security and deployment checklists

• Store X-API-Key as a secret in your CI/CD or serverless platform; never commit it to source control.
• Set per-environment base URLs and timeouts; track retry metrics for observability.
• Log the response envelope’s status and message for quick triage of error cases.

FAQ

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

Q: How fresh is the AIS data?
A: The platform updates in near real-time. Use current_position.timestamp_utc and age_minutes to make freshness visible in your UI and alerting.

Q: What’s the best identifier to track a tanker?
A: Prefer IMO as the stable key for storage. Many endpoints also accept MMSI; store both and use whichever is most convenient per call.

Q: How do I narrow search results to oil tankers?
A: Add ship_type=Oil%20Tanker to /vessels/search along with your query, flag, DWT, or year filters.

Q: Can I fetch multiple tankers in one request?
A: Yes. Use POST /vessels/fleet with an array of IMO/MMSI objects and set include_positions and/or include_routes as needed.

Build your oil tanker tracker now

Spin up a prototype with the official /vessels/track sample above, then expand to fleet snapshots, analytics, and CII scoring as your needs grow. The consistent JSON envelope, single-key auth, and AIS-first design let you wire up dashboards, alerts, and ESG reporting quickly.

Register · Documentation · MCP