Home → Blog

Port Congestion API: IMF PortWatch Activity Index

March 16, 2026 · 8 min read · By FreightPulse Engineering

Port congestion costs the global shipping industry an estimated $30 billion annually in delays, demurrage charges, and rerouting expenses. Most logistics teams still check port authority websites, newsletters, or carrier word-of-mouth.

FreightPulse exposes one endpoint for this: GET /api/v1/port-congestion. It is not vessel wait time, dwell, or berth utilization. It is an activity index from IMF PortWatch: recent daily port-calls versus a 90-day baseline for the same port. Data lags about 6–7 days. Each query returns at most 25 ports.

Why Port Activity Still Matters

Even a proxy is useful if you treat it as a signal, not a stopwatch:

• Unusual call volume often coincides with backlog, weather recovery, or blank sailings
• Rate pressure on a lane often shows up after activity at the gateway port spikes or collapses
• Inventory buffers can be reviewed when a destination port stays high for several snapshots

Do not use this field to rewrite a carrier ETA by “36 hours of wait.” That number is not in the payload.

What the Endpoint Returns

You must pass port, country, or region. Without one of those filters the API returns 422. Use UN/LOCODE for a single port (for example USLAX). Send Accept: application/json and authenticate with X-API-Key.

curl "https://freightpulsehq.com/api/v1/port-congestion?port=USLAX" \
  -H "X-API-Key: your_api_key" \
  -H "Accept: application/json"

Shape of a successful response (values change with PortWatch):

{
  "success": true,
  "data": {
        "results": [
      {
        "port": "Los Angeles",
        "locode": "USLAX",
        "country": "United States",
        "congestion": "moderate",
        "as_of": "2026-08-13",
        "metrics": {
          "recent_avg_portcalls_per_day": 12.4,
          "baseline_avg_portcalls_per_day": 11.1,
          "ratio_vs_baseline": 1.12
        }
      }
    ],
    "meta": {
      "source": "IMF PortWatch (portwatch.imf.org) - UN Global Platform AIS data",
      "data_lag_days": "~6-7 (daily updates, not real-time)",
      "methodology": "congestion level is an approximation: last 7 days' avg port calls vs 90-day baseline for the same port. Does not measure vessel wait/anchorage time."
    }
  }
}

How to Read the Fields

congestion: low, moderate, high

Derived from ratio_vs_baseline: ≥1.2 is high, ≤0.8 is low, otherwise moderate. It is a volume-vs-normal label, not a 0–100 index.

metrics.ratio_vs_baseline

Recent average daily port-calls divided by the 90-day average. Use this if you want a numeric threshold (for example alert when ratio ≥ 1.2) instead of the string label.

as_of

The latest PortWatch observation date in the series — typically several days behind “today.” Show it in the UI so users do not treat the feed as live AIS.

Filters That Exist (and Ones That Do Not)

• port=USLAX — one LOCODE
• country=United States — up to 25 matching ports (country queries can take tens of seconds)
• region= — PortWatch region name
• congestion=high — filter the result set after lookup

There is no /port-congestion/global, no /history, no port_code alias, and no webhook. Poll on a schedule that respects the lag (daily is enough).

Useful Patterns

1. Compare two gateways

Call twice — port=USLAX and port=USOAK — and compare ratio_vs_baseline. If Los Angeles is high and Oakland is low, that is a planning hint, not a guaranteed faster berth.

2. Country snapshot

Use country= when you need a short list, then cache it. Do not fire this on every page view; the upstream query is slow.

3. Combine with other live endpoints

Pair congestion with US FTL quotes (/freight-rates?mode=trucking) or EIA fuel (/fuel-prices) when you are modeling inland cost after the box clears. /disruptions now returns real natural-hazard events (GDACS, USGS, NOAA/NWS) — but not geopolitical events, strikes, or port closures.

Getting Started

The endpoint is on every plan, including the free tier (100 calls/month). Always send Accept: application/json.

See the API documentation for parameters, error envelopes, and quota headers.