Home → Blog

You are trying to understand and operationalize congestion at Los Angeles-Long Beach (USLAX) without mixing it up with live AIS wait-time feeds. By the end of this guide, you will query the FreightPulse Port Congestion API for USLAX, read the lagged IMF PortWatch metrics, and wire them into your monitoring or planning workflow.

What the USLAX congestion endpoint actually returns

The port-congestion data for Los Angeles-Long Beach (USLAX) comes from IMF PortWatch and is intentionally lagged by roughly 6–7 days. The core metrics are a 7-day moving average of port calls per day compared with a 90-day baseline. The API returns a simple envelope and a results array containing the port, the UN/LOCODE, a qualitative congestion label, an as_of date, and the metrics you can plot or alert on.

Illustration: Los Angeles-Long Beach (USLAX) Congestion

This is not a live AIS queue length or anchorage wait-time feed. Treat it as a smoothed, near-real-time indicator backed by an authoritative, lagged data source.

Authentication and request shape

The endpoint accepts a port parameter set to the string USLAX for Los Angeles-Long Beach. Authenticate using an HTTP header X-API-Key with your key. If you are evaluating without a key, you can make up to 100 requests per day per IP as a guest.

Refer to the API reference for general behavior and field semantics: Documentation.

Quickstart: curl for Los Angeles-Long Beach

Run this request to retrieve the latest congestion snapshot for USLAX.

curl -H "X-API-Key: YOUR_API_KEY" "https://freightpulsehq.com/api/v1/port-congestion?port=USLAX"

This request returns a JSON envelope with a results array. For a single port query, you should expect a single element in results.

Official JSON example and how to read it

Below is the documented fixture for USLAX (as_of 2026-08-14). This is not live today; use it to validate your parsing and UI.

{
    "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
                }
            }
        ]
    }
}

What you will typically use:

Units and cadence:

Python example: fetch and interpret USLAX congestion

The following script calls the same endpoint, validates the envelope, and extracts the fields you need for alerts or dashboards.

import os
import requests

API_KEY = os.getenv("FREIGHTPULSE_API_KEY", "YOUR_API_KEY")
URL = "https://freightpulsehq.com/api/v1/port-congestion"
PARAMS = {"port": "USLAX"}
HEADERS = {"X-API-Key": API_KEY}

def fetch_uslax_congestion():
resp = requests.get(URL, params=PARAMS, headers=HEADERS, timeout=15)
resp.raise_for_status()
data = resp.json()
if not data.get("success"):
raise RuntimeError("API returned success=false")
results = data.get("data", {}).get("results", [])
if not results:
raise RuntimeError("No results for USLAX")
record = results[0]

port = record.get("port")
locode = record.get("locode")
as_of = record.get("as_of")
congestion_label = record.get("congestion")
metrics = record.get("metrics", {})

recent = metrics.get("recent_avg_portcalls_per_day")
baseline = metrics.get("baseline_avg_portcalls_per_day")
ratio = metrics.get("ratio_vs_baseline")

# Example usage: simple thresholding on ratio
status = "worsening" if ratio is not None and ratio < 1.0 else "improving_or_above_baseline"

return {
"port": port,
"locode": locode,
"as_of": as_of,
"congestion": congestion_label,
"recent_avg": recent,
"baseline_avg": baseline,
"ratio": ratio,
"status": status
}

if __name__ == "__main__":
result = fetch_uslax_congestion()
print(f"[{result['as_of']}] {result['port']} ({result['locode']}): {result['congestion']}")
print(f"Recent avg: {result['recent_avg']} calls/day vs baseline {result['baseline_avg']} (ratio {result['ratio']})")
print(f"Interpretation: {result['status']} relative to 90-day baseline")

Field semantics and integration notes

Congestion labels are a readable summary you can display directly in a UI. For automated logic, prefer ratio_vs_baseline, which compresses the signal into a single number where 1.0 indicates parity with the 90-day baseline, values below 1.0 indicate below-baseline activity, and values above 1.0 indicate above-baseline activity.

The as_of field is a date without a time component. Because the underlying series is lagged by ~6–7 days, you can safely cache responses for many hours without losing fidelity. A practical approach is to refresh once per day after your ETL cutoff.

Error handling, caching, and scheduling

Using the metrics in dashboards and alerts

Dashboards: Show the congestion label alongside the ratio, recent_avg_portcalls_per_day, and baseline_avg_portcalls_per_day to provide both a qualitative and quantitative view. The ratio is the most compact metric for color-coding (e.g., thresholds around 0.9 and 1.1) without having to expose raw call counts.

Alerts: Trigger a notification when ratio_vs_baseline crosses a threshold for several consecutive days to avoid noise inherent to rolling averages. Because the data is lagged, alerts are best used for planning adjustments rather than hour-by-hour operations.

Data hygiene and validation

Compliance and usage constraints

Troubleshooting common implementation issues

FAQ

Is this data live?

No. It is based on IMF PortWatch and is typically 6–7 days behind. It represents a 7-day moving average vs a 90-day baseline, not real-time AIS wait times.

How often should I poll the endpoint?

Daily is sufficient for most workflows, given the lag and smoothing. Many teams cache results for 12–24 hours.

Do I need an API key?

An API key is recommended for reliability. Guests without a key have a limit of 100 requests per day per IP.

What does ratio_vs_baseline represent?

It is the recent 7-day average divided by the 90-day baseline average. Values below 1.0 indicate recent port-call activity is below baseline.

Does the endpoint paginate?

The response shows a results array. For a single-port query like USLAX, you should expect a single element. No pagination parameters are shown for this request.

Set up reliable congestion monitoring for Los Angeles-Long Beach in minutes. Create an account to get your API key and start integrating: Register. If you need implementation details, field definitions, or additional examples, see the Documentation.