Look Up Supply Chain Disruptions

Home → Blog

You need a fast, reliable way to look up supply chain disruptions for a specific port and show your team exactly what is impacting operations. By the end of this guide, you will be able to authenticate with FreightPulse, call the Supply Chain Disruptions lookup for a port like USLAX, handle the response envelope safely, and embed this data in your application without guessing fields or inventing events.

What this lookup covers and what it does not

The FreightPulse Supply Chain Disruptions lookup focuses on natural hazards sourced from GDACS, USGS and NOAA. It does not cover labor actions, strikes, canal transits, or invented events. For port congestion, FreightPulse references IMF PortWatch with a lag of about six to seven days, presented as a seven-day average versus a 90-day baseline. This is not a live AIS wait-time feed.

Illustration: Look Up Supply Chain Disruptions

Do not quote a freight-rates USD fare as today’s price based on this endpoint. The disruptions lookup is for situational awareness, not spot-rate pricing. Keep data use narrow and tied to hazard awareness around a given port.

Authentication and request limits

Send your key in the request header X-API-Key with the literal value YOUR_API_KEY in examples. Guests without a key are allowed up to 100 requests per day per IP. The disruptions endpoint returns a consistent envelope with success and data keys that you should always check before consuming the payload.

Auth: header X-API-Key: YOUR_API_KEY
Guest without key: 100 requests per day per IP
Envelope: {"success": true, "data": {...}}

Quickstart: cURL for Supply Chain Disruptions at USLAX

Copy, paste and run this request. Replace YOUR_API_KEY with your key in your implementation.

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

This call targets the Supply Chain Disruptions lookup and filters by port code USLAX. The response will follow the standard FreightPulse envelope. Always check success before reading the data object.

Official JSON sample: envelope and field-reading pattern

The official response sample below shows the FreightPulse envelope structure you should code against. Field names, casing, and the meta.request_id pattern are representative of the API. Copy the parsing approach, not the domain-specific keys. Always read success, then data, and preserve timestamps and units as returned.

{
    "success": true,
    "data": {
        "timestamp": "2026-11-09T00:00:59+00:00",
        "source": "EIA (U.S. Energy Information Administration)",
        "currency": "USD",
        "unit": "gallon",
        "data": {
            "diesel": {
                "national_average": 6.292,
                "change_week": -0.06,
                "change_percent": -0.94,
                "updated_at": "2026-11-02",
                "regions": {
                    "east_coast": 6.025,
                    "midwest": 6.402,
                    "gulf_coast": 5.912,
                    "rocky_mountain": 6.445,
                    "west_coast": 7.272,
                    "california": 8.076
                }
            },
            "gasoline": {
                "national_average": 4.153,
                "change_week": -0.116,
                "change_percent": -2.72,
                "updated_at": "2026-11-02",
                "grades": {
                    "regular": 4.153,
                    "midgrade": 4.757,
                    "premium": 5.158
                }
            },
            "bunker_fuel": {
                "available": false,
                "note": "No known free source (Rotterdam/Singapore/Houston) — requires a paid provider (e.g. Ship & Bunker, Argus)."
            }
        },
        "historical": {
            "diesel_30d_avg": 6.275,
            "diesel_90d_avg": 6.033,
            "diesel_yoy_change": 67.7,
            "gasoline_30d_avg": 4.259,
            "gasoline_90d_avg": 4.232,
            "gasoline_yoy_change": 37.6
        }
    },
    "meta": {
        "request_id": "ec645f23-7ac4-4abd-afb0-bf6a2f999e05"
    }
}

What you will actually use from the envelope:

success: Boolean gate for downstream processing. Fail fast if false.
data: The payload containing the disruption information for the port you queried. Do not assume specific field names beyond the envelope unless documented in your integration.
timestamps: ISO 8601 with timezone offset. Treat as UTC when offset is +00:00.
meta.request_id: Useful for logging, tracing and support tickets.

JavaScript example: querying and safely parsing disruptions

This Node.js sample calls the disruptions endpoint for USLAX, validates the envelope, and shows a safe pattern to explore the payload without assuming undocumented fields. You can adapt it to your framework or runtime.

import fetch from "node-fetch";

async function getDisruptions(portCode) {
const url = `https://freightpulsehq.com/api/v1/disruptions?port=${encodeURIComponent(portCode)}`;
const res = await fetch(url, {
headers: {
"X-API-Key": "YOUR_API_KEY"
},
// Consider adding a short timeout via AbortController in production
});

if (!res.ok) {
throw new Error(`HTTP ${res.status} while fetching disruptions for ${portCode}`);
}

const json = await res.json();

// Envelope check
if (!json || json.success !== true || typeof json.data === "undefined") {
throw new Error("Unexpected API envelope: missing success or data");
}

const { data, meta } = json;

// Example logging for observability
const requestId = meta && meta.request_id ? meta.request_id : "unknown";
console.log(`request_id=${requestId} port=${portCode}`);

// Because the schema is not enumerated here, show a few robust introspection steps:
// 1) Keep the raw payload for auditing
const raw = JSON.stringify(data);
console.log(`payload_size_bytes=${Buffer.byteLength(raw, "utf8")}`);

// 2) If the payload contains a top-level timestamp or source, preserve them
const timestamp = data.timestamp || data.updated_at || null;
const source = data.source || null;

console.log({ timestamp, source });

// 3) If there is an events or hazards array, iterate defensively
// (Check existence before accessing to avoid runtime errors)
if (Array.isArray(data.events)) {
for (const evt of data.events) {
// Safely read a few likely attributes if present
const type = evt.type || evt.category || "unknown";
const severity = evt.severity || evt.level || "unknown";
const startsAt = evt.start || evt.started_at || null;
const endsAt = evt.end || evt.ended_at || null;
const affected = evt.affected || evt.impact || null;

console.log({ type, severity, startsAt, endsAt, affected });
}
} else {
console.log("No events array found; inspect the payload shape above.");
}

return data;
}

// Example usage
getDisruptions("USLAX").catch(err => {
console.error(err);
process.exit(1);
});

Notes:

Header: X-API-Key with YOUR_API_KEY.
Timestamps: expect ISO 8601 strings, parse as needed.
Always check success before reading data.
Log meta.request_id for traceability.

Python example: minimal client with envelope checks

This Python snippet demonstrates the same pattern using requests. It is copy-pasteable into a CLI script or service worker.

import os
import sys
import json
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://freightpulsehq.com/api/v1/disruptions"

def get_disruptions(port):
url = f"{BASE_URL}?port={port}"
headers = {"X-API-Key": API_KEY}
r = requests.get(url, headers=headers, timeout=20)
r.raise_for_status()

payload = r.json()

# Validate envelope
if not isinstance(payload, dict) or payload.get("success") is not True:
raise RuntimeError("API call unsuccessful or unexpected envelope")

data = payload.get("data")
if data is None:
raise RuntimeError("Missing data field in response")

meta = payload.get("meta", {})
request_id = meta.get("request_id")
if request_id:
print(f"request_id={request_id}")

# Defensive parsing
ts = data.get("timestamp") or data.get("updated_at")
if ts:
print(f"timestamp={ts}")

# If events exist, iterate defensively without assuming a fixed schema
events = data.get("events")
if isinstance(events, list):
for i, evt in enumerate(events, start=1):
etype = evt.get("type") or evt.get("category") or "unknown"
severity = evt.get("severity") or evt.get("level") or "unknown"
print(f"event_{i}: type={etype} severity={severity}")
else:
print("No events array in payload; inspect keys:", list(data.keys()))

return data

if __name__ == "__main__":
port = sys.argv[1] if len(sys.argv) > 1 else "USLAX"
data = get_disruptions(port)
# Persist raw for auditing or caching
print(json.dumps(data)[:1000])

Implementation tips:

Use a timeout to avoid hung sockets.
Retry on 5xx with exponential backoff.
Cache responses briefly if your UI can tolerate slightly stale data, especially given that port congestion is lagged by design.

Query parameters and port focus

Stay focused on the port in your title or screen. For this guide, the example port is USLAX. The disruptions endpoint as shown accepts port codes via the port query parameter. Only request ports your workflow actually needs, to stay within limits and reduce noise.

Endpoint: https://freightpulsehq.com/api/v1/disruptions
Filter: port=USLAX
Method: GET
Scope: natural hazards only from GDACS, USGS and NOAA

Time, units and currency considerations

Disruptions data emphasizes event timing and impact narratives rather than prices. When timestamps are included, they are ISO 8601 with a timezone offset. Treat +00:00 as UTC and convert once, at the edge of your system. If you join disruptions to other FreightPulse resources that mention currency or units, do not assume those apply to hazard data; only display what is explicitly returned by the disruptions endpoint.

For congestion indicators derived from IMF PortWatch, remember the six to seven day lag and that the reported values are seven-day averages compared to a 90-day baseline. These are not live AIS queues or minute-by-minute operational feeds.

Error handling, quotas and observability

Build envelope validation into your client and surface meaningful errors. Record meta.request_id on every call for reproducibility and faster support. Guests without a key are limited to 100 requests per day per IP. If you expect higher volume or need reliability guarantees, add your API key and consolidate your polling intervals with a small cache window on your side.

Validate success is true before using data.
Log meta.request_id and relevant query params.
Backoff on 429 or 5xx and avoid retry storms.
Cache with a short TTL when surfacing lagged congestion statistics.

End-to-end integration checklist

Acquire an API key and store it securely. Header name: X-API-Key.
Make a GET request to /api/v1/disruptions with port=USLAX to validate connectivity.
Check success and the presence of data before reading fields.
Preserve timestamps as ISO 8601 and convert at render time if needed.
Handle absent or unexpected keys defensively since hazard payloads can vary by event.
Never quote a freight-rates USD fare as today’s price from this endpoint.
Document your use of natural hazards only; exclude strikes and canals from your UI.

Troubleshooting common issues

If you see HTTP 401 or 403, confirm you are sending X-API-Key with YOUR_API_KEY or switch from guest usage if you have exceeded the 100 requests per day per IP allowance. If the payload shape varies between calls, ensure your parser is field-tolerant and gates on success and data. For congestion values that appear stale, remember IMF PortWatch is lagged by about one week and represents a seven-day average versus a 90-day baseline.

FAQ

Q: Can I fetch live vessel wait times for USLAX?
A: No. FreightPulse port congestion is lagged by about six to seven days from IMF PortWatch and reported as seven-day averages versus a 90-day baseline. It is not a live AIS wait-time feed.

Q: Do I need an API key to start?
A: You can call the endpoint without a key as a guest with up to 100 requests per day per IP. For higher throughput and stability, use X-API-Key with YOUR_API_KEY.

Q: What hazards are included?
A: Natural hazards only, sourced from GDACS, USGS and NOAA. The lookup does not cover strikes, canal issues or non-natural disruptions.

Q: Can I quote a USD freight rate based on this lookup?
A: No. Do not quote a freight-rates USD fare as today’s price from disruptions data. Use it strictly for hazard awareness and operational context.

Q: How should I cache the results?
A: Use a short client-side TTL aligned to your UI needs. Since congestion metrics are lagged by design, aggressive polling offers limited benefit; prefer modest intervals and envelope validation on every read.

Get your key and start integrating the Supply Chain Disruptions lookup now. Create your account on the FreightPulse portal: Register. For parameter details and additional endpoints, see the Documentation.