Bulk Carrier Near a Port

You need to know, in near real time, whether a bulk carrier is near a port—at anchorage, approaching the pilot station, or already alongside—so you can make decisions on berth readiness, laycan, trucking, and demurrage risk. By the end of this guide, you’ll be able to programmatically detect bulk carriers near a port, drill into a target vessel’s live track and route, check port congestion, review expected arrivals, and pull an IMO CII emissions snapshot, all using a single REST API.

What you’ll build for bulk carriers near a port

The goal is a small, reliable service that can:

• Find bulk carriers within X nautical miles of a port’s lat/lon (anchorage detection and approach alerts).
• Inspect a vessel’s current AIS position, recent history, and active route for ETA confidence.
• Check live port congestion and recent wait-time stats before confirming berth windows.
• See expected arrivals to plan lineups and resource allocation.
• Pull an IMO CII emissions rating to support ESG and compliance workflows.

All of this is available behind one base URL and one API key. Vessels API ships 18 REST endpoints covering vessel search, live tracking, fleet operations, port intelligence, IMO CII emissions, and a premium real-time AIS feed. Every response returns the same JSON envelope: {status, success, message, data}. Authentication is a single request header (X-API-Key), and you can test-drive it with a 7‑day free trial. Explore the Documentation and the MCP for tooling and schema references.

Core endpoints for “bulk carrier near a port”

1) Find bulk carriers within X NM of a port: GET /vessels/nearby

Given a latitude/longitude and a search radius in nautical miles, this endpoint returns all vessels in that circle. Filter down to bulk carriers with ship_type. This is ideal for anchorage scans or “approach within 10 NM” alerts.

• Base URL: https://vessels-api.com/api/V1
• Endpoint: GET /vessels/nearby
• Required: latitude, longitude
• Optional: radius (default 50, max 200 NM), ship_type, limit

Example cURL (30 NM scan; ship type filter to Bulk Carrier):

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

Example JSON (truncated to relevant fields):

{
    "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:22+00:00",
            "age_minutes": 5153000,
            "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:

• distance_nm: threshold for “near port” notifications (e.g., < 12 NM for approach).
• speed_knots + navigational_status: determine if anchored, drifting, or inbound under way.
• timestamp_utc: all timestamps are UTC; cache for a minute or two to avoid spamming alerts.

2) Drill into a target vessel: GET /vessels/track

After you detect bulk carriers near a port, fetch the target’s live position, recent positions (up to 168h), active route, and predicted ETA. This is the canonical single-vessel view to power ETB/ETD decisions and progress indicators.

Official sample (copy verbatim):

What to use:

• current_position.speed_knots + course_degrees: combine with port geometry to infer inbound vs. loitering.
• route.destination_port + route.eta (when available): single-source for ETA on dashboards.
• last_port_visits: support cargo context and estimating ballast vs. laden probability.

3) Check live port congestion: GET /ports/congestion

Before confirming a berth, pull a real-time congestion snapshot and recent wait-time statistics for a given port. The endpoint uses UNLOCODE in the port_id parameter (e.g., ARBUE, SGSIN, NLRTM).

• Endpoint: GET /ports/congestion
• Required: port_id
• Optional: period=24h|3d|7d

Example cURL (7-day window for Buenos Aires, ARBUE):

Key fields you’ll read:

• snapshot.vessels_in_anchorage and snapshot.vessels_at_berth: live headcounts useful for anchorage queues and quay utilization.
• statistics.avg_wait_time_hours_last_7d and max_wait_time_hours_last_7d: set expectations with shippers and adjust ETB plans.
• statistics.port_calls_count: trend normalization for busier periods.

4) Validate the lineup: GET /port/expected-arrivals

Pull the vessels expected to arrive at a port, their ETAs, and their known origin ports. Cross-check your target bulk carrier’s name or MMSI to verify lineup inclusion.

• Endpoint: GET /port/expected-arrivals
• Required: port (port identifier; same format used by other port endpoints)

Example cURL:

Example JSON (abbreviated):

What to use:

• eta: schedule ETB estimates downstream; timestamps are UTC.
• departure_port: lane context, use with your cargo forecasts.
• Match on mmsi or imo to avoid fuzzy-name errors in bulk carrier lineups.

5) Pull an IMO CII snapshot: GET /vessels/green

For ESG/compliance teams tracking bulk carrier voyages, this endpoint provides estimated emissions and an IMO CII rating for a selectable period.

• Endpoint: GET /vessels/green
• Required: imo OR mmsi
• Optional: period=24h|7d|30d|1y (default 30d)

Example cURL:

Example JSON:

What to use:

• cii.rating and cii.score: normalize your fleet KPIs by rating class (A→E).
• estimated_emissions.co2_tons: feed month-end disclosures and sustainability dashboards.

End-to-end flow for “bulk carrier near port” alerts

1. Resolve the port’s center point: use GET /ports or GET /ports/data for coordinates.
2. Scan for bulk carriers near the port: GET /vessels/nearby with ship_type=Bulk Carrier and your radius threshold (e.g., 12 NM around anchorage or pilot station).
3. For each candidate, fetch live track: GET /vessels/track to read speed, course, route, and predicted ETA when available.
4. Check congestion trend: GET /ports/congestion to infer waiting time risk before confirming berth windows.
5. Validate arrivals: GET /port/expected-arrivals to ensure the vessel is on the official lineup.
6. Optionally enrich with ESG: GET /vessels/green for the latest CII snapshot.

Operational notes:

• Units: distances are nautical miles; speeds are in knots; timestamps are UTC.
• Caching: cache nearby scans for 60–120 seconds and track responses for 30–60 seconds to balance freshness with rate efficiency.
• Pagination: endpoints that list collections (e.g., search) provide pagination data; nearby supports limit for caps.
• Error handling: expect 401 for missing/invalid X-API-Key, 404 when a vessel/port is not found, 422 for parameter ranges, 429 when rate-limited.

Copy-paste examples you can ship

Python: scan for bulk carriers within 15 NM and print approach candidates

import os
import requests
from math import isfinite

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

# Example: port center (replace with /ports/data to resolve precisely at runtime)
LAT, LON = -34.60, -58.38 # Buenos Aires area
RADIUS_NM = 15

params = {
"latitude": LAT,
"longitude": LON,
"radius": RADIUS_NM,
"ship_type": "Bulk Carrier",
"limit": 100
}

resp = requests.get(f"{BASE_URL}/vessels/nearby", headers={"X-API-Key": API_KEY}, params=params, timeout=20)
resp.raise_for_status()
payload = resp.json()
vessels = payload.get("data", {}).get("vessels", [])

def is_probably_inbound(v):
spd = v.get("speed_knots")
crs = v.get("course_degrees")
return (isfinite(spd) and spd > 2) and (crs is not None)

for v in vessels:
name = v.get("name") or "UNKNOWN"
dist = v.get("distance_nm")
spd = v.get("speed_knots")
status = v.get("navigational_status")
if is_probably_inbound(v) and dist is not None and dist <= 12:
print(f"[Approach] {name} MMSI={v.get('mmsi')} at {dist:.1f} NM, {spd} kn, status={status}")
else:
print(f"[Nearby] {name} MMSI={v.get('mmsi')} at {dist:.1f} NM, {spd} kn, status={status}")

JavaScript (Node.js): fetch the official track sample and read key fields

import fetch from "node-fetch";

const API_KEY = process.env.VESSELS_API_KEY || "YOUR_API_KEY";
const url = "https://vessels-api.com/api/V1/vessels/track?mmsi=258785000&hours=48";

const res = await fetch(url, { headers: { "X-API-Key": API_KEY }});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const json = await res.json();

const cp = json.data.current_position;
const route = json.data.route;

console.log({
mmsi: json.data.vessel.mmsi,
speed_knots: cp.speed_knots,
course_degrees: cp.course_degrees,
timestamp_utc: cp.timestamp_utc,
destination_port: route?.destination_port,
eta: route?.eta
});

Ports: expected arrivals validation for lineups

Use this to cross-check a bulk carrier detected via /vessels/nearby against the official expected-arrivals list before allocating tugs, pilots, and berth windows.

Why teams standardize on Vessels API for this workflow

• One API key and one base URL for vessel tracking, port intelligence, fleet analytics, and CII—no per-endpoint auth differences.
• 18 endpoints that cover the end-to-end loop from detection to compliance reporting.
• Consistent response envelope across endpoints for clean error handling and logging.
• Global AIS coverage with near real-time refresh rates designed for operations teams.

If you need to combine multiple vessels (e.g., a bulk carrier lineup) into one call, use POST /vessels/fleet to fetch positions and routes in batch and render a single dashboard update cycle.

Implementation checklist for production

• Normalize everything to UTC and knots/NM in your database; convert at the UI boundary.
• Apply a small debounce (30–60 seconds) on alerting logic to avoid flip-flops when vessels drift near thresholds.
• Use include_route and include_predicted_eta on /vessels/track when you need richer voyage context; default hours is 24 and max is 168.
• Guard for nulls: destination/ETA and predicted_eta can be null; fall back to port expected arrivals and speed/course heuristics.
• Track failures by status code and retry with exponential backoff on 429 and 500.

FAQ

Q: How do I filter “bulk carriers only” in the nearby scan?
A: Pass ship_type=Bulk Carrier to GET /vessels/nearby. You can also use /vessels/search with ship_type to prebuild a watchlist, but nearby already supports the type filter.

Q: Are timestamps local to the port?
A: All timestamps are UTC. Use the port’s timezone from GET /ports or GET /ports/data when rendering local times.

Q: Can I get historical positions for a 7‑day drift analysis outside the anchorage?
A: Yes. GET /vessels/track with hours=168 returns up to 168 hours of position_history, subject to data availability.

Q: How do I compute approach alerts without spam?
A: Combine GET /vessels/nearby (distance_nm threshold) with speed_knots and course_degrees; debounce alerts by 60 seconds and suppress repeats within a 10–15 minute window unless the state changes.

Q: What does the CII rating mean for a single vessel over 30 days?
A: The endpoint returns an indicative score and rating (A–E) aligned to IMO MEPC.339(76) for the selected period. Use it as an operational signal; your formal annual report should align with your compliance methodology.

Ready to ship a “bulk carrier near a port” monitor that your ops team will trust? Start with the free trial, wire up the endpoints shown here, and expand into fleets and ESG when you’re ready. Register, read the Documentation, and explore utilities in the MCP to move from prototype to production.