You need a reliable way to measure port congestion at Los Angeles–Long Beach (USLAX) and compare the current 7-day average against a 90-day baseline to guide routing, scheduling, and cost decisions. By the end of this guide, you’ll be able to query the FreightPulse Port Congestion API for USLAX, read the response correctly (including the “ratio_vs_baseline” metric), and build logic that flags deviations from normal activity.
What this endpoint tells you (and what it does not)
The Port Congestion API returns IMF PortWatch congestion metrics for a requested port, lagged about 6–7 days. Data represents a 7-day average benchmarked against a 90-day baseline; it is not live AIS or real-time queue estimates. Use it for context and trend-aware planning rather than minute-by-minute dispatching.
For Los Angeles–Long Beach (USLAX), the API provides:
- Text congestion label (e.g., “moderate”)
- 7-day average port calls per day (recent)
- 90-day average port calls per day (baseline)
- Ratio of recent to baseline to quantify deviation (e.g., 0.85)
- As-of date so you know the data’s currency
Interpretation: a ratio below 1.0 indicates throughput below the 90-day norm (potential tightness or reduced activity); a ratio above 1.0 indicates above-baseline throughput.
Authentication, access, and request model
Calls use a simple GET to a single endpoint with the target port specified via a query parameter. Authentication is via an X-API-Key header:
- Auth header: X-API-Key: YOUR_API_KEY
- Guests without a key: 100 requests/day per IP
- Response envelope: {"success":true,"data":{...}}
Endpoint:
GET https://freightpulsehq.com/api/v1/port-congestion?port=USLAX
Because data is lagged ~6–7 days, you can safely cache responses for several hours without losing fidelity. There is no pagination for this endpoint; the payload is a single results array scoped to the requested port.
Quickstart: curl and Python examples
curl (copy/paste)
Run this from your terminal to fetch the USLAX record:
curl -H "X-API-Key: YOUR_API_KEY" "https://freightpulsehq.com/api/v1/port-congestion?port=USLAX"Python (requests)
import requests
url = "https://freightpulsehq.com/api/v1/port-congestion"
headers = {"X-API-Key": "YOUR_API_KEY"}
params = {"port": "USLAX"}
resp = requests.get(url, headers=headers, params=params, timeout=10)
resp.raise_for_status()
payload = resp.json()
if not payload.get("success"):
raise RuntimeError("API returned success=false")
results = payload["data"]["results"]
if not results:
raise RuntimeError("No results for USLAX")
r = results[0]
as_of = r["as_of"] # e.g., "2026-08-14" (ISO date, no timezone)
congestion_label = r["congestion"] # e.g., "moderate"
recent = r["metrics"]["recent_avg_portcalls_per_day"] # float, calls/day (7-day avg)
baseline = r["metrics"]["baseline_avg_portcalls_per_day"] # float, calls/day (90-day avg)
ratio = r["metrics"]["ratio_vs_baseline"] # float, dimensionless
print(f"USLAX as of {as_of}: {congestion_label}")
print(f"Recent 7-day avg: {recent} calls/day vs baseline {baseline} calls/day")
print(f"Ratio vs baseline: {ratio}")
Sample JSON response (documented fixture)
The following is the documented fixture for USLAX (as_of 2026-08-14 — not live today):
{"success":true,"data":{"results":[{"port":"Los Angeles-Long Beach","locode":"US LAX","country":"United States","congestion":"moderate","as_of":"2026-08-14","metrics":{"recent_avg_portcalls_per_day":8.7,"baseline_avg_portcalls_per_day":10.2,"ratio_vs_baseline":0.85}}]}}Field usage:
- success: Boolean for request success.
- data.results: Array with one object for the requested port.
- port, locode, country: Identification metadata for the port (USLAX is “Los Angeles–Long Beach”, locode “US LAX”).
- congestion: Label summarizing conditions (e.g., “moderate”).
- as_of: ISO date string indicating the data’s effective date; data is lagged ~6–7 days.
- metrics.recent_avg_portcalls_per_day: 7-day average calls/day (float).
- metrics.baseline_avg_portcalls_per_day: 90-day average calls/day (float).
- metrics.ratio_vs_baseline: recent/baseline (float). Use this for normalized comparisons.
USLAX vs 90-day baseline: applying the ratio for Transportation decisions
In the fixture, the recent 7-day average (8.7 calls/day) is below the 90-day baseline (10.2 calls/day), yielding a ratio of 0.85. That indicates activity below the longer-term norm and supports a “moderate” congestion label in the payload. While this isn’t a live vessel queue, the ratio provides a stable, comparable signal for planning.
How to use it in routing and scheduling:
- Thresholding: Flag USLAX for review when ratio_vs_baseline < 0.9 or > 1.1 to catch meaningful shifts from normal.
- Normalization: Use the ratio to compare USLAX to other ports without worrying about absolute scale differences in calls/day (only compare using fields actually returned by the endpoint you query).
- Time boxing: Because the data is lagged by ~1 week, combine it with internal ETAs to set buffers rather than last-minute diversions.
Developer experience and response shape
The API uses a single, straightforward GET with a required port parameter and a stable response envelope. All key congestion indicators are within data.results[0].metrics, reducing parsing overhead. With an as_of date and an explicit ratio_vs_baseline field, you can avoid re-computing ratios and minimize downstream logic.
Documentation is concise and focused on Transportation congestion data for ports, with a single auth header and a predictable response shape. Because it is IMF PortWatch data, you gain standardized coverage and consistent update cadence, at the cost of not being live AIS.
Coverage and reliability characteristics
Source: IMF PortWatch data. Expect a ~6–7 day lag. This is designed for monitoring and operational planning rather than live dispatch corrections. It avoids volatile spikes common in live AIS while providing a normalized, 90-day baseline to anchor the signal.
Operational tips:
- Caching: Cache responses for several hours to reduce repeated calls; the underlying data won’t change intra-day for prior as_of dates.
- Staleness checks: Use as_of to detect when your cache should be refreshed.
- Error handling: Check success before dereferencing data; if results is empty, retry later or surface a “data unavailable” state.
Choosing the right signal: recent 7-day vs the 90-day baseline
Both metrics are returned together, but they serve different purposes:
- recent_avg_portcalls_per_day: Use this to get an absolute sense of current throughput.
- baseline_avg_portcalls_per_day: Use this to understand the typical level for the port.
- ratio_vs_baseline: Use this normalized indicator to compare conditions over time or across ports, decoupling from their absolute scales.
Pick the ratio when building alerts and dashboards spanning multiple ports; pick the raw recent average when modeling absolute capacity at USLAX specifically.
Implementation patterns that save time
Minimal integration for dashboards
- Fetch USLAX once per day, store the latest payload with as_of, and display congestion, recent average, baseline, and ratio.
- Color-code by ratio thresholds (e.g., <0.9 amber, <0.8 red) to surface deviations from normal conditions.
Triggering operational alerts
- Set hysteresis: require two consecutive days of ratio < 0.9 before alerting to prevent flapping.
- Combine with internal lead times; for example, adjust buffer days when ratio stays below 0.9 for a week.
Data hygiene
- Assume as_of is an ISO date without timezone; treat it as the date label for the metric window, not a live timestamp.
- Units: port calls per day (floats); ratio is dimensionless.
- No currency fields apply; do not infer or quote freight-rate USD fares from this endpoint.
Side-by-side criteria: how the 7-day vs 90-day baseline comparison helps Transportation workflows
- Developer experience: Single endpoint, stable envelope, no pagination, easy parsing of metrics for alerting.
- Documentation: Focused on Transportation congestion data, with required header and a clear example for USLAX.
- Response shape: Envelope with results array; core metrics grouped under metrics for predictable access.
- Coverage: Backed by IMF PortWatch with standardized methodology; suitable for cross-port benchmarking.
- Reliability: Lagged by design (~6–7 days) to favor stability over real-time volatility; not a live AIS substitute.
When to pick ratio_vs_baseline: multi-port dashboards, trend detection, SLA guardrails, and normalized scoring. When to focus on recent_avg_portcalls_per_day: modeling absolute daily throughput and capacity for USLAX-specific decisions.
Troubleshooting and validation
- If success=false, do not parse metrics; log and retry later or prompt for a valid API key.
- If results is empty, confirm the port parameter (USLAX) and try again.
- Validate that ratio_vs_baseline aligns numerically with recent/baseline; it should match within floating-point rounding.
- Keep a local log of as_of dates to ensure you are not processing duplicate snapshots.
Next steps
- Integrate the curl or Python snippet into a scheduled task that updates your internal dashboard once per day.
- Add alert thresholds on ratio_vs_baseline and congestion label to drive notifications.
- Use the Documentation to confirm any advanced usage details and updates.
FAQ
Is this live AIS data?
No. It is IMF PortWatch, lagged about 6–7 days. Use it for trend-aware planning, not minute-by-minute dispatch.
What timezone is as_of in?
as_of is an ISO date (no timezone). Treat it as the effective date for the measurement window rather than a timestamp.
How often should I call the endpoint?
Daily is sufficient for most workflows. Cache results for several hours since backfilled values won’t change intra-day.
Can I compare USLAX to other ports using the ratio?
Yes, ratio_vs_baseline is designed for normalized comparisons. Only use fields actually returned by each port’s response.
Do I need an API key?
You can call as a guest up to 100 requests/day per IP. For sustained use, include X-API-Key: YOUR_API_KEY.
Set up your USLAX congestion monitoring in minutes. Create an account and get an API key to move from manual checks to automated, ratio-driven alerts: Register.