LNG Carrier Near a Port

You need to reliably detect when an LNG carrier is near a port, alert ops when it’s approaching anchorage, and feed ETA and congestion context to downstream systems. By the end of this guide, you’ll ship a working integration that uses vessels-api.com to: query LNG carriers near a port, live-track a specific vessel, overlay port activity and congestion, and attach ESG CII scoring—all via a consistent REST API.

Why “near a port” for LNG carriers is a data problem

“Near” is not just a radius around a pin. Ops teams care about zones (anchorage vs berth), timing (how fresh is the AIS position), and context (is the port congested, what’s the likely ETA, how long will the carrier wait?). For LNG, custody transfer windows, boil-off management, and tugs/pilots scheduling make minutes matter.

vessels-api.com consolidates those signals into a consistent JSON surface:

• 18 REST endpoints for vessel intelligence, fleet operations, port intelligence, emissions (IMO CII), and a premium real-time feed
• One API key, one base URL, same envelope: {"status","success","message","data"}
• Global AIS with near real-time refresh rates
• Designed for developers, logistics startups, fleet managers, port operators, and ESG/compliance teams

Links you’ll use once you’re ready to build:

• Register
• Documentation
• MCP

Core endpoints for LNG carrier proximity and port context

We’ll focus on five endpoints you can compose into production workflows:

1. /vessels/nearby — detect “LNG carrier near a port” by geo radius
2. /vessels/track — confirm current position, course, and route/ETA of a specific carrier
3. /port/expected-arrivals — validate if a carrier is already planned for the port
4. /ports/congestion — snapshot congestion risk to forecast anchorage wait times
5. /vessels/green — IMO CII scoring to tag movements with ESG context

Detect “LNG Carrier near a port” with /vessels/nearby

Use /vessels/nearby with the port’s coordinates and a nautical-mile radius. If you need port coordinates, resolve them with /ports or /ports/data. You can filter for ship_type when you only want LNG carriers.

Step 1 — Resolve the port center

Get a port’s coordinates via /ports/data (example port code formats include UNLOCODE identifiers, e.g., ARBUE, SGSIN, NLRTM). Then apply those lat/lon to /vessels/nearby.

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

From the response, extract data.latitude and data.longitude for use as your center point. All timestamps are UTC unless otherwise stated.

Step 2 — Query vessels near the port

Set a radius to match your operational definition of “near.” 5–15 NM often maps to anchorage approaches for large gas carriers; for wide approaches, use up to 30–50 NM.

Response highlights:

• data.vessels[].position.timestamp_utc — when the AIS fix was recorded (UTC)
• data.vessels[].distance_nm — computed distance to your center point
• data.vessels[].ship_type — filter for LNG carriers
• data.vessels[].speed_knots and course_degrees — movement trends for screening

Practical tip: sort by distance_nm ascending; alert when distance drops under an approach threshold (e.g., 8 NM) and speed_knots is reduced (indicating anchorage arrival).

Confirm and follow the carrier with /vessels/track

Once a carrier is detected near the port, fetch precise position, recent track (up to 168 hours), active route, predicted ETA, and last port calls via /vessels/track. This is also where you’ll verify heading, speed changes, and destination fields.

Official sample — copy/paste this exactly in your terminal to test your pipeline structure:

{
    "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:54+00:00",
            "age_minutes": 5150180,
            "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
    }
}

Field notes you’ll actually use:

• data.current_position.latitude/longitude — latest fix; timestamp_utc is ISO 8601 UTC
• data.current_position.navigational_status — integer AIS status (e.g., 5 may indicate moored/anchored depending on mapping in your UI)
• data.route.destination_port and data.route.eta — current voyage intent and ETA, if available
• data.last_port_visits[] — helps distinguish arrivals vs passing traffic
• Optional parameters include include_route, include_predicted_eta, include_weather; hours ranges up to 168

Python example: trigger a “near port” alert flow

This script resolves a port center, finds nearby LNG carriers, and for each candidate, calls /vessels/track to confirm approach and extract ETA/route context. It uses the same documented MMSI and hours for the track call so you can run it as-is.

import requests
from typing import List, Dict

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

def get_port_center(port_id: str) -> Dict[str, float]:
r = requests.get(f"{BASE}/ports/data", params={"port": port_id}, headers=HEADERS, timeout=15)
r.raise_for_status()
payload = r.json()["data"]
return {"lat": payload["latitude"], "lon": payload["longitude"], "name": payload["name"]}

def find_nearby_lng(lat: float, lon: float, radius_nm: int = 25, limit: int = 50) -> List[Dict]:
params = {"latitude": lat, "longitude": lon, "radius": radius_nm, "ship_type": "LNG", "limit": limit}
r = requests.get(f"{BASE}/vessels/nearby", params=params, headers=HEADERS, timeout=20)
r.raise_for_status()
return r.json()["data"]["vessels"]

def track_mmsi(mmsi: str) -> Dict:
# Using the official sample parameters to keep parity with docs and ensure field names match
params = {"mmsi": mmsi, "hours": 48}
r = requests.get(f"{BASE}/vessels/track", params=params, headers=HEADERS, timeout=20)
r.raise_for_status()
return r.json()["data"]

def main():
port_id = "SGSIN" # replace with your target port
center = get_port_center(port_id)
print(f"Port {center['name']} center: {center['lat']}, {center['lon']}")
nearby = find_nearby_lng(center["lat"], center["lon"], radius_nm=25)

# Screen: closer than 12 NM and speed < 5 kts considered approach/anchorage
candidates = [v for v in nearby if v.get("distance_nm", 999) < 12 and (v.get("speed_knots") or 0) < 5]

for v in candidates:
mmsi = v.get("mmsi")
if not mmsi:
continue
t = track_mmsi(mmsi)
cp = t.get("current_position", {}) or {}
route = t.get("route", {}) or {}
print(f"MMSI {mmsi} @ {cp.get('latitude')},{cp.get('longitude')} kts={cp.get('speed_knots')} ts={cp.get('timestamp_utc')}")
print(f"Route: {route.get('departure_port')} → {route.get('destination_port')} ETA={route.get('eta')} avg_speed={route.get('avg_speed_knots')}")

if __name__ == "__main__":
main()

Operational tip: data.current_position.age_minutes helps you grade data freshness and decide alerting thresholds or backoff until the next fix.

Validate plans with /port/expected-arrivals

Not every LNG carrier near a port is calling there. Cross-check expected arrivals to reduce false-positive alerts and align with terminal scheduling.

Response highlights:

• data.expected_arrivals[].mmsi/imo/name — identify the carrier
• data.expected_arrivals[].eta — planned ETA (UTC)
• data.expected_arrivals[].departure_port — recent origin context for routing logic

Combine this with /vessels/nearby by joining on MMSI: if the carrier is near your radius and listed in expected_arrivals, it’s high-confidence for ops escalation.

Measure congestion risk with /ports/congestion

Anchorage and berth congestion can vary dramatically. Use /ports/congestion to snapshot current conditions and recent wait-time statistics. Valid port_id values include UNLOCODEs such as ARBUE, SGSIN, and NLRTM. You can request period windows like 24h, 3d, or 7d.

Response highlights for planning:

• data.snapshot.vessels_in_anchorage and vessels_at_berth — real-time congestion snapshot
• data.statistics.avg_wait_time_hours_last_7d and max_wait_time_hours_last_7d — planning and risk buffers
• data.statistics.port_calls_count — traffic cadence

Practical use: if a carrier is detected within 10–15 NM but anchorage is saturated, notify stakeholders that berth windows might slip; adjust truck/rail/pipeline readiness downstream.

Attach ESG context with /vessels/green (IMO CII)

For LNG lifecycles, ESG and regulatory reporting increasingly require voyage-level emissions context. The /vessels/green endpoint gives a period-scoped CII rating per the IMO framework, plus estimated emissions fields you can surface in ops dashboards.

Response highlights:

• data.cii.rating — A (best) → E (worst)
• data.estimated_emissions.co2_tons and co2_per_nm — rollups for the requested period
• period supports 24h, 7d, 30d, 1y windows

Suggestion: attach the CII rating to your “near port” alerts so ESG/compliance teams can consume the same event feed with context.

Putting it together: design patterns and payload handling

Event flow for “LNG Carrier Near Port”

1. Resolve port center with /ports/data to get latitude and longitude.
2. Poll /vessels/nearby with ship_type=LNG every 2–5 minutes (tune to your refresh needs and plan limits) for a radius that maps to anchorage approach.
3. On candidate hits within your distance and speed thresholds, call /vessels/track to fetch precise position, heading, and route/ETA.
4. Cross-check with /port/expected-arrivals to filter false positives and enrich with scheduled ETA.
5. Query /ports/congestion to add operational risk indicators and communicate potential anchorage delays.
6. Query /vessels/green and store CII rating alongside the event for ESG consumption.

Data envelope and reliability

• Every endpoint returns the same envelope: {"status","success","message","data"}.
• Timestamps are UTC ISO 8601 (e.g., 2026-04-27T21:35:36+00:00). Use strict parsing and display in local TZ only at the presentation layer.
• Pagination appears where noted (e.g., /vessels/search with data.pagination). For nearby/track, expect collections with bounded sizes.
• Error codes: 400 (invalid parameter), 401 (missing/invalid key), 404 (not found), 422 (out of range), 429 (rate limit), 500 (server error). Implement retries with jitter for 429/500 and validate inputs to avoid 400/422.

Choosing radii and thresholds

• /vessels/nearby radius is in nautical miles. Max is 200 NM. For LNG anchorage detection, 8–15 NM is a good start; widen to 25–30 NM for approach monitoring.
• Use speed_knots thresholds to detect slowing into anchorage (e.g., < 5 kts) vs port passage (> 10–12 kts).
• Leverage course_degrees consistency across polls to determine if the carrier is loitering or executing an approach turn.

Production tips that save time

• Cache /ports and /ports/data by port_id; update weekly or when a user explicitly changes port selections.
• Use idempotent alert keys: hash of {mmsi, port_id, radius_bucket} to avoid duplicate notifications when a carrier hovers near the threshold.
• Persist the last known data.current_position.age_minutes to monitor AIS silence. Back off alerts if age_minutes exceeds your freshness SLA.
• Batch tracking: if your LNG program monitors multiple carriers, consider /vessels/fleet (POST) to reduce request overhead for positions/routes in one call.

Optional: discover LNG carriers with /vessels/search

If you don’t already manage a watchlist, you can build one with /vessels/search. Filter by name patterns, flag, and tonnage specs; you can also bound by build years to focus on modern LNG tonnage.

Response includes data.vessels[] with identifiers and dimensions; store IMO/MMSI for downstream tracking and analytics.

Security and integration checklist

• Authentication: X-API-Key header (no OAuth flows). Do not embed keys in client code; proxy via your backend where possible.
• Timeouts: 15–20 seconds are appropriate for HTTP clients; implement exponential backoff for transient errors (429/500).
• Schema stability: the envelope and key fields are stable; consult the Documentation for optional flags like include_predicted_eta on /vessels/track.
• Monitoring: alert on elevated 429s to tune poll cadence; log status and message for incident triage.

End-to-end cURL checklist

Use these cURLs to validate your pipeline shape before coding your orchestration:

• Port data center
• Nearby LNG carriers
• Live track (official sample)
• Expected arrivals
• Port congestion
• ESG CII score

FAQ

How fresh is the AIS data for near-port detection?
The API surfaces near real-time AIS with a consistent envelope. Use data.current_position.age_minutes and position.timestamp_utc to enforce your freshness SLA per alert.

What if I have the IMO but not the MMSI?
/vessels/track accepts either imo or mmsi. For discovery, /vessels/search can return both identifiers so you can standardize on one.

What radius should I use for “near a port” for LNG carriers?
Start with 10–15 NM for anchorage detection, expand to 25–30 NM for approach. Calibrate per port geography and traffic separation schemes.

Can I get batch positions for many LNG carriers?
Yes. Use /vessels/fleet (POST) with a list of IMO/MMSI to retrieve positions and routes in one call, reducing request overhead for dashboards.

How do I handle rate limiting?
If you receive 429, back off and retry with jitter. Consider staggering /vessels/nearby polls by port and batching /vessels/track with /vessels/fleet when monitoring many carriers.

Next step

Ship your “LNG Carrier Near a Port” integration with a consistent REST surface and global AIS coverage. Start building with your key, explore full endpoint details in the Documentation, and wire automations via the MCP. When you’re ready, Register and put it in production.