Port operations — congestion monitoring and throughput forecasting
How port authorities, terminal operators, and freight forwarders use NTHMAP to monitor vessel queues and forecast throughput.
Port congestion is one of the single largest friction points in global trade. A bulker waiting 5 extra days at anchor can cost $50,000+ in demurrage. NTHMAP gives port operators, terminal operators, and cargo owners live visibility into exactly how bad the congestion is at any given port on any given day.
The core signal: vessels near the port
NTHMAP tracks ~3,500 major ports as infrastructure. Each has a representative point (lat/lng) and metadata (operator, throughput capacity). Combine that with the vessels API:
# Get all vessels within ~20km of Port of Singapore
nthmap vessels list --bbox 103.6,1.1,104.0,1.4 --format json | jq length
Split that into "at anchor" (nav_status=1 or speed≈0) vs "underway" (nav_status=0) for a queue vs transit picture:
# At anchor / idle near Singapore
nthmap vessels list \
--bbox 103.6,1.1,104.0,1.4 \
--max-speed 1 \
--format json | jq '[.[] | {mmsi, name, vessel_type_str, nav_status}]'
Los Angeles / Long Beach congestion dashboard
During the 2021-2022 supply-chain crisis, containers piled up at San Pedro Bay. A NTHMAP query that would have surfaced this before it hit headlines:
nthmap vessels list \
--bbox -118.4,33.6,-118.0,33.8 \
--types "Container Ship" \
--max-speed 1 \
--format json | jq length
When that number exceeds 30, you're looking at serious congestion. When it crosses 60, it's a crisis.
Building a multi-port dashboard
import nthmap
client = nthmap.Client(api_key="ntm_live_...")
PORTS = {
"Singapore": [103.6, 1.1, 104.0, 1.4],
"Rotterdam": [3.9, 51.8, 4.3, 52.0],
"Shanghai": [121.5, 31.2, 122.0, 31.5],
"Los Angeles": [-118.4, 33.6, -118.0, 33.8],
"Long Beach": [-118.3, 33.7, -118.0, 33.8],
"Houston": [-95.4, 29.5, -95.0, 29.8],
"Antwerp": [4.2, 51.2, 4.5, 51.4],
"Hamburg": [9.8, 53.4, 10.1, 53.6],
}
for name, bbox in PORTS.items():
vessels = client.vessels(bbox=bbox)
at_anchor = [v for v in vessels if (v["speed_knots"] or 0) < 1]
containers = [v for v in at_anchor if v["vessel_type_str"] == "Container Ship"]
bulkers = [v for v in at_anchor if v["vessel_type_str"] == "Bulk Carrier"]
print(f"{name:20} | Total: {len(vessels):3} | Anchor: {len(at_anchor):3} | Containers: {len(containers):3} | Bulkers: {len(bulkers):3}")
Run every 10 minutes, render as a Grafana dashboard, and you have an always-on view of the 8 busiest ports in the world.
Storm impact on loadings
Port operators care about inbound weather. NTHMAP events surface active hurricanes and tropical storms:
# Active storms near Gulf Coast ports
nthmap events list --bbox -95,24,-85,30 --types hurricane
If a tropical storm is within 500km of Houston with a 350km impact radius, NTHMAP will show it on the map and via API. Cross-reference with your vessel count to predict the "pause window" when loadings stop:
storms = client.events(bbox=[-95,24,-85,30], types=["hurricane"])
if storms and storms[0]["severity"] in ("Severe", "Extreme"):
# Count vessels likely to delay
vessels = client.vessels(bbox=[-95,28,-94,30]) # narrow to port approaches
print(f"{len(vessels)} vessels likely impacted by {storms[0]['name']}")
Throughput forecasting
For terminal operators, 3-7 day throughput forecasts are critical for labor planning, yard allocation, and equipment deployment. NTHMAP gives you the inbound pipeline directly:
# Containers inbound to Rotterdam in the next 5 days
nthmap vessels list \
--bbox -50,35,5,60 \
--types "Container Ship" \
--min-speed 8 \
--format json | \
jq '[.[] | select(.destination == "NLRTM") | {mmsi, name, eta}] | length'
Not perfect (destination fields are captain-entered), but combined with past arrival patterns it gives you a solid forecast baseline.
For freight forwarders
If you book cargo through specific ports, you want to know which ports are currently flowing smoothly. A simple CLI alias:
alias port-check='nthmap vessels list --max-speed 1 --format json | jq length'
port-check --bbox 103.6,1.1,104.0,1.4 # Singapore
port-check --bbox -118.4,33.6,-118.0,33.8 # LA
port-check --bbox 3.9,51.8,4.3,52.0 # Rotterdam
You have a one-line congestion check you can run before committing to a routing.
Learn more
- CLI docs for more automation patterns
- Concepts for how NTHMAP models vessels and ports
- Related: Agricultural trading for commodity-specific port watching