You need to know, fast, whether a chemical tanker is near a port, where it’s headed, how long it might wait, and whether its emissions profile passes scrutiny. By the end of this walkthrough, you’ll be able to query nearby chemical tankers, drill into one vessel’s live AIS track and last port calls, check expected arrivals for a port, and pull a current IMO CII snapshot — all via a few HTTP calls to vessels-api.com.
Why this matters for chemical tankers near ports
Chemical tanker calls require tight choreography: terminal slotting, draft windows, segregated cargo constraints, and strict safety practices. If a unit is holding just outside the port limit, you want:
- Near real-time proximity: what chemical tankers are within 10–30 NM of the entrance channel?
- Live situational awareness: speed over ground, course, nav status, and recent port visits.
- Port-side planning: expected arrivals and congestion snapshot to anticipate berth readiness.
- Compliance and reporting: a current CII reading to underpin ESG and charter-party checks.
vessels-api.com offers 18 REST endpoints with one API key and a consistent JSON response envelope. For this scenario we’ll use:
- GET
/vessels/nearbyto discover tankers near a port pilot station. - GET
/vessels/trackfor the target vessel’s live AIS position, route, and history. - GET
/port/expected-arrivalsto verify whether the unit is officially inbound. - GET
/vessels/greenfor a CII emissions score snapshot.
All requests use the base URL https://vessels-api.com/api/V1 and a single header: X-API-Key: YOUR_API_KEY. Responses follow a consistent JSON envelope: { status, success, message, data }.
Find chemical tankers near a port anchorage
To detect chemical tankers holding at anchorage or loitering near a port entrance, query by latitude/longitude with an NM radius. You can usually pull the port centroid from GET /ports or GET /ports/data, then fan out with /vessels/nearby.
cURL example: chemical tankers within 20 NM
curl -H "X-API-Key: YOUR_API_KEY" "https://vessels-api.com/api/V1/vessels/track?mmsi=258785000&hours=48"
Response snippet (truncated for clarity):
{
"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:23+00:00",
"age_minutes": 5162360,
"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 read and why:
distance_nmhelps triage which units are practically at the pilot boarding ground.speed_knotsnear zero andnavigational_status5 (typically anchored) imply waiting.timestamp_utcis in UTC; cache results briefly (e.g., 30–90s) if polling.
Python example: filter and rank candidate tankers
import requests
from math import isfinite
API_KEY = "YOUR_API_KEY"
BASE_URL = "https://vessels-api.com/api/V1"
params = {
"latitude": 1.265,
"longitude": 103.84,
"radius": 20, # nautical miles
"ship_type": "Chemical Tanker",
"limit": 50
}
resp = requests.get(f"{BASE_URL}/vessels/nearby", headers={"X-API-Key": API_KEY}, params=params, timeout=20)
resp.raise_for_status()
envelope = resp.json()
if not envelope.get("success"):
raise RuntimeError(f"API error: {envelope.get('message')}")
vessels = envelope["data"]["vessels"]
# Rank anchored/slow targets closest to port
def rank_key(v):
d = v.get("distance_nm", float("inf"))
s = v.get("speed_knots", float("inf"))
status = v.get("navigational_status")
anchored = 1 if status == 5 else 0
return (anchored == 0, d if isfinite(d) else 1e9, s if isfinite(s) else 1e9)
shortlist = sorted(vessels, key=rank_key)[:5]
for v in shortlist:
print(v.get("mmsi"), v.get("name"), v.get("distance_nm"), v.get("speed_knots"), v.get("navigational_status"))
Pro tip: Store the shortlist MMSIs for follow-up detail queries with GET /vessels/track and GET /vessels/green.
Drill into a vessel’s live track, route, and last port calls
Once you have an MMSI of interest, pivot to the vessel’s live AIS and recent calls. The following official sample illustrates the response structure you’ll integrate with (copy-paste runnable):
Official cURL: 48h track window
Official JSON response
Key fields to drive a “near port” flow:
current_position.latitude/longitude,speed_knots,course_degrees: show map pin and motion.navigational_statusand near-zerospeed_knots: anchored vs. underway inference.route.destination_port,route.etaorpredicted_etawhen present: ETAs for planning.last_port_visits: prior call context for compliance and cargo heuristics.
JavaScript example: normalize a track into a dashboard card
async function getTrack(mmsi) {
const url = `https://vessels-api.com/api/V1/vessels/track?mmsi=${encodeURIComponent(mmsi)}&hours=48`;
const resp = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } });
if (!resp.ok) throw new Error("HTTP " + resp.status);
const json = await resp.json();
if (!json.success) throw new Error(json.message);
const d = json.data;
const p = d.current_position || {};
const route = d.route || {};
const last = (d.last_port_visits || [])[0] || {};
return {
mmsi: d.vessel?.mmsi,
imo: d.vessel?.imo,
lat: p.latitude,
lon: p.longitude,
sog: p.speed_knots,
cog: p.course_degrees,
nav: p.navigational_status,
positionTimeUtc: p.timestamp_utc,
destPort: route.destination_port,
eta: route.eta || d.predicted_eta,
lastPort: last.port_name,
lastArrivalUtc: last.arrival_time
};
}
getTrack("258785000")
.then(card => console.log(card))
.catch(err => console.error(err));
Implementation notes:
timestamp_utcis ISO-8601 in UTC; format client-side for local TZ if needed.- Some fields can be null (e.g., name, predicted_eta); handle gracefully in UI.
- For “near a port” gates, compute haversine distance to the port centroid and flag thresholds (e.g., ≤ 3 NM = “approach”).
Confirm the call: expected arrivals for the port
Before you dispatch a launch or start tank cleaning prep, check whether the chemical tanker is on the port’s expected-arrivals list. Use GET /port/expected-arrivals with the port’s identifier (e.g., UNLOCODEs such as ARBUE or others provided by GET /ports).
cURL example: expected arrivals feed
Response snippet (shape):
Cross-link this with your nearby shortlist. If a candidate MMSI appears here with a tight ETA, it’s a strong signal to pre-stage port services or berth resources.
For a full-port view (IDs, coordinates, timezone), see GET /ports and GET /ports/data. The Documentation includes complete response fields for these endpoints.
Snapshot port congestion to anticipate anchorage time
To build an estimated waiting-time model for chemical tankers, start with GET /ports/congestion. It provides a real-time snapshot of vessels at anchorage vs. at berth and wait-time statistics for a given period. Use this as an input to your own rolling averages or per-terminal heuristics.
cURL example: congestion snapshot
Fields to consume:
snapshot.vessels_in_anchorageandsnapshot.vessels_at_berth: current state.statistics.avg_wait_time_hours_last_7d,max_wait_time_hours_last_7d,avg_berth_time_hours_last_7d,port_calls_count: planning signals.
Combine these with your tanker’s navigational_status and radius-to-pilot-ground to estimate practical time to alongside.
CII emissions for ESG checks on arrival
Chemical cargoes often involve tighter vetting. Pull the vessel’s recent CII to feed your pre-arrival checklist and ESG reporting. Ratings follow IMO MEPC.339(76) with A (best) to E (worst).
cURL example: 30-day CII snapshot
Response snippet (shape):
Use the cii.rating and estimated_emissions fields to gate workflows, notify the vetting team, or attach to your port call audit trail.
Putting it together: a minimal “chemical tanker near port” service
Here’s a practical flow you can ship today:
- Resolve the target port centroid with GET
/ports/data(storelatitude,longitude,timezone). - Scan for chemical tankers with GET
/vessels/nearby, radius 20–30 NM. Cache for 30–60 seconds. - For top 3 closest anchored units, call GET
/vessels/track(48h), extractcurrent_position,route,last_port_visits. - Check GET
/port/expected-arrivalsto confirm the unit is inbound and collect ETA. - Fetch GET
/vessels/greenand surfacecii.ratingfor vetting. - Optionally, call GET
/ports/congestionto inform a “likely wait time” banner.
Error handling and operational notes
- HTTP status codes: 400 for invalid params, 401 for missing/invalid key, 404 when the vessel/port is not found, 422 for out-of-range (e.g., radius > 200 NM), 429 rate limit, 500 server error.
- All timestamps are UTC ISO-8601. Normalize to the port’s timezone client-side if needed.
- Pagination: search endpoints provide
page/per_pageandpaginationmetadata; nearby supportslimit. - Ship types: filter
ship_type=Chemical%20Tankerconsistently to avoid clutter from product or crude tankers. - Consistency: every endpoint returns the same envelope:
{ status, success, message, data }. Checksuccessbefore readingdata.
Security and integration tips
- Use the single
X-API-Keyheader; there’s no OAuth or per-endpoint auth variance. - Backoff on 429 with jittered retries; cache “static-enough” fields (e.g., last port visits) for a few minutes.
- For fleets, POST
/vessels/fleetto aggregate positions/routes for multiple tankers in one round trip.
Useful references and tools
- Register for your API key and start the 7-day trial.
- Explore endpoint details in the Documentation.
- Test and prototype with the MCP developer console.
FAQ
How frequently are AIS positions refreshed?
Global AIS coverage updates near real time. Polling every 30–60 seconds for approach phases is typical; add cache and jitter to reduce duplicate requests.
What’s the unit for distances and speeds?
All voyage metrics use nautical miles for distance and knots for speed. Time fields are ISO-8601 in UTC.
Can I request data for multiple chemical tankers at once?
Yes. Use POST /vessels/fleet with a list of MMSIs/IMOs and set include_positions and/or include_routes to true.
How do I detect if a tanker is truly “near the port”?
Compute a geodesic to the port centroid and combine rules: distance ≤ X NM, speed_knots ≤ 1, and navigational_status indicates anchored or moored. Cross-check with expected arrivals when available.
What happens if the vessel has no predicted ETA?
Use the route’s eta when present; otherwise fall back to your own prediction model using last speed/course and distance to destination. When the official predicted_eta is provided, prefer it.
Build your “chemical tanker near a port” workflow now
With four endpoints — /vessels/nearby, /vessels/track, /port/expected-arrivals, and /vessels/green — you can stand up a reliable, developer-friendly flow for chemical tanker monitoring around any port. Start prototyping in minutes: grab an API key, open the docs, and test calls in the MCP console.