How to Track a Oil Tanker

How to Track a Oil Tanker

You need to track an oil tanker reliably—know where it is right now, where it’s heading, when it will reach a port, and whether it’s compliant with emissions ratings. By the end of this guide, you’ll be able to use vessels-api.com to search for a tanker, stream its live AIS position with up to 168 hours of history, monitor congestion at destination ports, batch-track fleets, and pull IMO CII emissions ratings—all with a single API key and consistent JSON responses.

What makes tracking an oil tanker different?

Oil tankers come with unique tracking needs: large draft and maneuvering constraints near congested ports, voyage legs that cross multiple reporting regions, and regulatory visibility for ESG and compliance teams. The Vessels API consolidates these data points so engineering teams can build:

Illustration: How to Track a Oil Tanker
  • Real-time fleet maps for VLCC/Suezmax/Aframax tankers
  • ETA-driven logistics handoffs for loading windows and STS ops
  • Port congestion overlays and expected arrivals for berth planning
  • ESG dashboards using IMO CII emissions scoring

Every endpoint returns the same envelope: {status, success, message, data}, and all requests authenticate with an X-API-Key header. Base URL: https://vessels-api.com/api/V1.

Core endpoints for oil tanker tracking

For most tanker operations, you’ll combine these endpoints:

  • GET /vessels/search — Find the correct tanker by name, IMO, or MMSI
  • GET /vessels/track — Live AIS with history, route, ETA, and last port calls
  • GET /ports/congestion — Congestion snapshot and wait-time statistics
  • POST /vessels/fleet — Batch positions and routes for multiple tankers
  • GET /vessels/green — IMO CII emissions scoring for ESG

We’ll focus on these five to cover search, tracking, port ops, fleet scale, and compliance. You can explore all capabilities in the Documentation and open the interactive tools in the MCP.

Step 1: Identify your oil tanker with /vessels/search

Before you can track a tanker, you need its MMSI or IMO. The /vessels/search endpoint supports fuzzy name lookups and structured filters like ship_type, flag, and tonnage ranges—useful for narrowing down large fleets of similarly named tankers.

cURL

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

Key parameters you can use when searching oil tankers:

  • query: name, IMO, or MMSI (fuzzy for name)
  • ship_type: set to Oil Tanker to filter
  • min_dwt/max_dwt: target size class (e.g., VLCC at 200,000+ DWT)
  • year_built_from/year_built_to: restrict to newer hulls
  • page, per_page: pagination (per_page up to 100)

JavaScript (Node.js)

import fetch from "node-fetch";

const API_KEY = process.env.VESSELS_API_KEY;

async function findTanker() {
const url = "https://vessels-api.com/api/V1/vessels/search" +
"?query=frontier&ship_type=Oil%20Tanker&per_page=5";
const res = await fetch(url, {
headers: { "X-API-Key": API_KEY }
});
if (!res.ok) {
throw new Error(`Search failed: ${res.status}`);
}
const json = await res.json();
const vessels = json?.data?.vessels ?? [];
// Choose the best match (e.g., by gross_tonnage or flag)
return vessels[0]; // { imo, mmsi, name, flag, vessel_type, ... }
}

findTanker().then(console.log).catch(console.error);

Once you have the MMSI or IMO, you’re ready to stream live positions.

Step 2: Stream live AIS for your tanker with /vessels/track

/vessels/track returns the current AIS position, an optional history window (up to 168 hours), current route and last port calls, plus optional weather and predicted ETA. It’s the backbone for control-center maps and exception monitoring.

Official cURL sample (use this as-is)

Official JSON sample (do not alter values)

{
    "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:28+00:00",
            "age_minutes": 5163800,
            "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:

  • data.current_position.latitude/longitude: plot the tanker’s exact location (degrees)
  • speed_knots, course_degrees, navigational_status: motion state and intent
  • timestamp_utc: ISO 8601 in UTC for timeline alignment
  • route.departure_port/destination_port and avg_speed_knots: voyage context
  • last_port_visits: recent port calls you can reconcile in a port-call ledger

Parameters that matter for oil operations:

  • hours: default 24, max 168 (7 days) for position_history
  • include_route=true: if you only need the track, skip it to save payload
  • include_predicted_eta=true: enable predicted ETA when planning lineups
  • include_weather=true: get weather near the vessel for routing overlays

Python example: reading position and route

import os
import requests

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

def track_tanker(mmsi: str, hours: int = 48):
url = f"{BASE}/vessels/track"
params = {
"mmsi": mmsi,
"hours": str(hours),
"include_route": "true",
"include_predicted_eta": "true"
}
r = requests.get(url, headers={"X-API-Key": API_KEY}, params=params, timeout=20)
r.raise_for_status()
payload = r.json()
data = payload.get("data", {})
vessel = data.get("vessel", {})
current = data.get("current_position", {})
route = data.get("route", {})
return {
"imo": vessel.get("imo"),
"mmsi": vessel.get("mmsi"),
"lat": current.get("latitude"),
"lon": current.get("longitude"),
"speed_knots": current.get("speed_knots"),
"course_degrees": current.get("course_degrees"),
"timestamp_utc": current.get("timestamp_utc"),
"departure_port": route.get("departure_port"),
"destination_port": route.get("destination_port"),
"avg_speed_knots": route.get("avg_speed_knots")
}

if __name__ == "__main__":
print(track_tanker("258785000", 48))

Step 3: Anticipate pier-side delays with /ports/congestion

Once you have the destination port from /vessels/track, query /ports/congestion to understand anchorage vs. berth load and wait-time statistics for planning bunker, pilotage, and berth windows. Use official UN/LOCODEs passed as port_id (e.g., ARBUE for Buenos Aires).

cURL

Response fields include:

  • data.snapshot.vessels_in_anchorage and vessels_at_berth: real-time snapshot
  • data.statistics: average and maximum wait times, berth time, and port calls for the selected period
  • period: 24h, 3d, or 7d

Combine this with your tanker’s predicted ETA to estimate total time to line and adjust schedules. For a directory of supported ports (with coordinates and timezones), call GET /ports.

Step 4: Track multiple oil tankers at once with /vessels/fleet

Operations teams often watch 5–500 tankers. Instead of querying each vessel individually, use /vessels/fleet to fetch positions and routes in one POST. This reduces latency and simplifies alerting.

cURL

What you get back:

  • data.fleet: rollup counts (total_vessels, vessels_at_sea, vessels_in_port)
  • data.vessels[]: per-tanker objects with imo, mmsi, name, position, route

Tip: Store your target vessel list in a config store and refresh it weekly using /vessels/search filters (e.g., ship_type=Oil Tanker, flag filters, or DWT ranges). Then use /vessels/fleet for runtime tracking.

Step 5: Stay compliant with IMO CII via /vessels/green

ESG teams can programmatically retrieve CII scoring for tankers with /vessels/green. Ratings follow IMO MEPC.339(76), returning A (best) through E (worst). Pair this with voyage distance for normalized emissions per nautical mile.

cURL

Key fields:

  • data.estimated_emissions.co2_tons and co2_per_nm: intensity and totals
  • data.cii.score and rating with the regulation_reference for audits
  • period: 24h, 7d, 30d, or 1y (default 30d)

Practical workflow: after /vessels/fleet, run /vessels/green for any tanker breaching thresholds and notify ops before charter renegotiations or sustainability reporting deadlines.

Building a tanker tracking dashboard end-to-end

Data flow

  1. Resolve identities: GET /vessels/search (find IMO/MMSI by name, verify ship_type=Oil Tanker)
  2. Map and timeline: GET /vessels/track with hours up to 168 for trails
  3. Port readiness: GET /ports/congestion for destination port
  4. Fleet scale: POST /vessels/fleet to unify N tankers’ states
  5. ESG: GET /vessels/green for CII scorecards

Frontend and backend tips

  • Units: distances are nautical miles (nm), speed in knots, headings in degrees
  • Timestamps: all ISO 8601 strings are UTC; convert once at the UI boundary
  • Caching: cache /vessels/search results for days; /vessels/track should be refreshed based on your UI needs and API rate policy
  • Pagination: honor pagination for /vessels/search (per_page up to 100)
  • Error handling: handle 401 (invalid key) and 404 (vessel/port not found). Retry 429 (rate limit exceeded) with backoff; check message for guidance.

Add nearby safety and situational awareness

Oil tankers operating near TSS, SPMs, or pilot stations benefit from proximity alerts. Use /vessels/nearby to find all vessels within a radius (nautical miles) of a lat/lon, filtered by ship_type if needed.

cURL

Use data.vessels[].distance_nm, speed_knots, and navigational_status to triage close contacts and apply COLREGs risk rules in your app.

Voyage analytics for post-mortems and planning

For an oil tanker’s last 7 days, /vessels/analytics type=vessel summarizes distance, speed distribution, and port-calls—ideal for demurrage analysis or post-voyage KPIs.

cURL

Look at statistics.total_distance_nm, avg_speed_knots, max_speed_knots, and port_calls_count to benchmark performance across your tanker fleet.

Error handling and response envelope

All responses follow the same structure:

Expected error codes:

  • 400: Missing/invalid parameter (e.g., no MMSI/IMO sent to /vessels/track)
  • 401: Invalid or missing X-API-Key
  • 404: Vessel/port not found
  • 422: Parameter out of range (e.g., hours > 168)
  • 429: Rate limit exceeded
  • 500: Server error

End-to-end JavaScript example: from search to live track

import fetch from "node-fetch";

const API_KEY = process.env.VESSELS_API_KEY;
const BASE = "https://vessels-api.com/api/V1";

async function searchOilTankerByName(name) {
const url = `${BASE}/vessels/search?query=${encodeURIComponent(name)}&ship_type=Oil%20Tanker&per_page=1`;
const res = await fetch(url, { headers: { "X-API-Key": API_KEY }});
if (!res.ok) throw new Error(`Search failed: ${res.status}`);
const body = await res.json();
const vessel = body?.data?.vessels?.[0];
if (!vessel) throw new Error("No tanker match");
return vessel; // { imo, mmsi, name, ... }
}

async function trackByMMSI(mmsi, hours = 48) {
const url = `${BASE}/vessels/track?mmsi=${encodeURIComponent(mmsi)}&hours=${hours}&include_route=true&include_predicted_eta=true`;
const res = await fetch(url, { headers: { "X-API-Key": API_KEY }});
if (!res.ok) throw new Error(`Track failed: ${res.status}`);
const body = await res.json();
const d = body.data || {};
return {
at: d.current_position?.timestamp_utc,
lat: d.current_position?.latitude,
lon: d.current_position?.longitude,
sog: d.current_position?.speed_knots,
cog: d.current_position?.course_degrees,
route: d.route
};
}

(async () => {
// 1) Resolve by name (ensure it's an oil tanker)
const tanker = await searchOilTankerByName("Frontier");
// 2) Track live
const track = await trackByMMSI(tanker.mmsi);
console.log({ tanker, track });
})().catch(err => {
console.error(err);
process.exit(1);
});

Operational patterns that work well

  • Map updates: poll /vessels/track every 1–5 minutes for UI maps; use event-driven alerts for status changes (e.g., navigational_status shift away from “at anchor”)
  • Berth planning: use /vessels/track for ETA context and /ports/congestion for wait-time ranges to refine staff schedules
  • Fleet KPIs: run /vessels/analytics daily for distance and port calls; roll up to a weekly dashboard
  • ESG guardrails: nightly /vessels/green scans; flag D/E ratings to operations and chartering
  • Nearby deconfliction: on approach legs, query /vessels/nearby within 10–25 nm of the SPM or pilot station

Quick reference for developers

  • Base URL: https://vessels-api.com/api/V1
  • Auth: X-API-Key: YOUR_API_KEY
  • Methods: GET for all endpoints except POST /vessels/fleet
  • Common fields: latitude/longitude (degrees), speed_knots (kn), distance_nm (nautical miles), timestamps in UTC
  • History windows: /vessels/track hours up to 168
  • Consistency: uniform response envelope across endpoints

FAQ

Q: What identifiers should I store for each oil tanker?
A: Keep both IMO and MMSI when available. IMO is stable across the vessel lifecycle; MMSI can change with flag/state but is required for AIS tracking in many cases.

Q: How do I reduce latency when tracking 100+ tankers?
A: Use POST /vessels/fleet to retrieve multiple vessels in a single call and cache static data (names, dimensions) from /vessels/search. Only refresh route/position at your operational cadence.

Q: Can I get predicted ETAs and weather with the track?
A: Yes. Pass include_predicted_eta=true and include_weather=true on /vessels/track to enrich your display and planning logic.

Q: How often are positions refreshed?
A: The API provides global AIS coverage with near real-time refresh rates. Use timestamps in the payload to assess freshness and apply your own throttling per UI needs.

Q: What’s the best way to detect arrival or departure automatically?
A: Use last_port_visits from /vessels/track and compare against current_position and route. For port-wide event streams, GET /port/activity provides recent arrivals/departures by port.

Get started

Spin up your tanker tracker in minutes. Create an API key, open the docs, and test live endpoints in the MCP console:

With one API key and a consistent JSON model, you can search, track, and operate oil tankers globally—then scale from a single voyage to a full fleet dashboard without re-architecting your code.

Ready to get started?

Get your API key and start tracking vessels in minutes.

Get API Key