Home → Blog

Operations teams need a reliable way to detect and react to severe weather that can disrupt freight flows around key ports. By the end of this guide, you will be able to query the FreightPulse Severe Weather Disruptions endpoint for a given port, integrate it with your alerting pipeline, and deploy a basic workflow that respects guest access limits without a key (100 requests/day per IP).

What you can query and what you should not expect

The FreightPulse Severe Weather Disruptions lookup focuses strictly on natural hazard signals (GDACS/USGS/NOAA) that can affect maritime and intermodal operations at or near ports. Use it to detect severe weather patterns that may coincide with congestion and schedule risk. Do not use it for labor actions, strikes, or canal-related events; those are explicitly out of scope here.

Illustration: API for Severe Weather Disruptions

Port congestion context in FreightPulse aligns with IMF PortWatch and is lagged by about 6–7 days as a 7‑day average versus a 90‑day baseline. It is not live AIS wait times. Keep that in mind when correlating weather disruptions with congestion: the congestion reference you retrieve from FreightPulse is a lagged statistical view, useful for trend assessment rather than minute-by-minute operations.

Authentication is straightforward. You can call the endpoint with an API key in a header (X‑API‑Key) or proceed as a guest with limits. Guest access allows 100 requests per day per IP without a key, which is enough for prototyping, light cron-based tracking for a few ports, or integration tests.

API shape, envelope, and access patterns

Every response follows a simple envelope pattern that makes basic parsing dependable across endpoints: {"success":true,"data":{...}}. The key to robust integration is to always check success first, then inspect data. Meta information may be present and is useful for internal correlation and logging.

When you are ready to move beyond guest mode, register for an API key and attach it as X-API-Key on each request. Consult the Documentation for endpoint coverage and any schema specifics not shown here.

Quickstart: guest access curl for a port’s severe weather

The following is a copy‑pasteable request targeting the Los Angeles port (USLAX) and filtering for severe weather. This works in guest mode (100 requests/day per IP) or with a key if you add the header as shown.

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

Notes that save time:

Parsing a real response safely (sample envelope)

Below is an official JSON block that demonstrates the envelope format and top-level fields. Copy it into your test harness to confirm JSON parsing. Do not treat the inner values as disruptions content; they simply show that the envelope has success, data, and meta, with timestamps in ISO 8601.

{
    "success": true,
    "data": {
        "timestamp": "2026-10-26T00:00:34+00:00",
        "source": "EIA (U.S. Energy Information Administration)",
        "currency": "USD",
        "unit": "gallon",
        "data": {
            "diesel": {
                "national_average": 6.276,
                "change_week": 0.097,
                "change_percent": 1.57,
                "updated_at": "2026-10-19",
                "regions": {
                    "east_coast": 5.984,
                    "midwest": 6.352,
                    "gulf_coast": 5.903,
                    "rocky_mountain": 6.422,
                    "west_coast": 7.394,
                    "california": 8.242
                }
            },
            "gasoline": {
                "national_average": 4.284,
                "change_week": -0.047,
                "change_percent": -1.09,
                "updated_at": "2026-10-19",
                "grades": {
                    "regular": 4.284,
                    "midgrade": 4.915,
                    "premium": 5.314
                }
            },
            "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.259,
            "diesel_90d_avg": 5.88,
            "diesel_yoy_change": 73.4,
            "gasoline_30d_avg": 4.359,
            "gasoline_90d_avg": 4.213,
            "gasoline_yoy_change": 41.9
        }
    },
    "meta": {
        "request_id": "09f9f622-e991-40f1-8026-aa91ec7923dc"
    }
}

What to use from this structure in your disruptions integration:

Do not extract or quote any of the example inner “data” values as they are not disruptions payloads. For the Severe Weather Disruptions lookup, rely on the envelope pattern and check the Documentation for the specific fields you will receive for natural hazards.

How to build a resilient disruptions poller

Polling cadence: with guest limits (100/day/IP), a practical schedule is per port every 15–30 minutes if you watch a handful of ports, or hourly across a broader list. Ensure your total daily volume fits the quota. Exceeding the quota will lead to denials until the daily reset.

Caching and staleness: use data.timestamp to detect new information. If the timestamp has not advanced since your last poll, skip downstream processing. This reduces compute and avoids duplicate alerts.

Backoff: implement exponential backoff on non-2xx responses and timeouts. Respect Retry-After headers if present. Always guard the failure path so a temporary outage does not page your on-call repeatedly.

Correlation: when you compare disruptions with congestion, remember congestion is IMF PortWatch, lagged ~6–7 days. Severe weather can signal forward risk, while congestion reflects trailing conditions. Use both carefully to avoid misinterpreting “live” status.

Data scope: the Severe Weather Disruptions lookup is limited to natural hazard signals (GDACS/USGS/NOAA). Do not attempt to infer labor actions, policy closures, or canal constraints from this feed.

Turning port signals into operational actions

Port codes: the sample demonstrates USLAX. Keep your request list to a canonical set of port codes you actively serve. Consolidate them in a configuration file and drive your polling loop from that list to avoid accidental scope creep that burns through the guest quota.

Alert routing: tie hazards to responders by domain. For example, severe weather near a terminal should alert berth planning and drayage scheduling. Maintain a rules file that maps hazard categories to teams and on-call rotations.

SLOs: define clear expectations with stakeholders. For guest mode, set a “data freshness” SLO aligned with your polling cadence and cache TTL. When you scale up with an API key, you can refine SLOs or widen your monitored port set.

Python example: fetch and validate a severe weather lookup

This sample calls the same endpoint shown in the curl above. It demonstrates how to attach the header, check the envelope, and safely inspect the inner data without assuming a specific schema for hazards. You can replace the print statements with your alerting or storage logic.

import os
import sys
import time
import json
import requests

API_URL = "https://freightpulsehq.com/api/v1/disruptions"
PORT_CODE = "USLAX" # Los Angeles
TYPE = "severe_weather"

def fetch_disruptions(api_key=None, port=PORT_CODE, hazard_type=TYPE, timeout=20):
headers = {}
if api_key:
headers["X-API-Key"] = api_key
params = {
"port": port,
"type": hazard_type
}
resp = requests.get(API_URL, headers=headers, params=params, timeout=timeout)
resp.raise_for_status()
payload = resp.json()
if not isinstance(payload, dict) or "success" not in payload:
raise ValueError("Unexpected response envelope")
if not payload.get("success", False):
# You may see error details in payload.get("error") or similar per docs
raise RuntimeError("API indicated non-success")
return payload

def main():
api_key = os.environ.get("FREIGHTPULSE_API_KEY") # optional for guest
try:
data = fetch_disruptions(api_key)
except Exception as exc:
print(f"[error] request failed: {exc}", file=sys.stderr)
sys.exit(1)

# Minimal, schema-agnostic handling
ts = None
meta_request_id = None
if isinstance(data.get("data"), dict):
ts = data["data"].get("timestamp")
if isinstance(data.get("meta"), dict):
meta_request_id = data["meta"].get("request_id")

print(f"success={data.get('success')} timestamp={ts} request_id={meta_request_id}")

# Inspect hazard content conservatively without assuming field names
inner = data.get("data")
if isinstance(inner, dict):
# Remove keys we already handled to focus on hazard-related content
candidate_keys = [k for k in inner.keys() if k not in ("timestamp",)]
print(f"top-level data keys: {candidate_keys}")
# If the API returns a list of events under a known key, you can iterate
# For example:
# for event in inner.get("events", []):
# process_event(event)
# Avoid inventing fields; consult docs for exact schema.
else:
print("data payload is not a dict; inspect raw JSON below")

print(json.dumps(data, indent=2))

if __name__ == "__main__":
main()

Operational reminders for this sample:

Units, timestamps, and currency notes

The disruptions lookup itself concerns natural hazards and should not be conflated with live freight rates or quoted fares. Do not quote a freight-rates USD fare as today’s price when discussing weather disruptions. Timestamps are ISO 8601 with timezone (for example, 2026‑10‑26T00:00:34+00:00). Treat all date-time parsing as timezone-aware in UTC to avoid scheduling drift in cron or Airflow DAGs.

If you later correlate disruptions with cost models, maintain a strict separation between disruption detection and pricing logic, and ensure any pricing data you use comes from an appropriate source rather than assuming the disruptions endpoint carries price authority.

Scaling considerations and quotas

Guest mode: 100 requests/day per IP. This is enough to track a small set of critical ports at modest polling intervals. Build an internal “budget” by dividing your daily allowance across ports and schedule windows, then reuse caches so repeaters do not waste calls.

API key mode: put X-API-Key: YOUR_API_KEY in the header as shown in the curl sample. Use connection pooling and keep-alives in your HTTP client to reduce TLS overhead. Log meta.request_id where available to speed up support triage.

Caching layer: key your cache by the full request URL and header context (guest vs keyed), and expire on either timestamp change or a conservative TTL aligned with your polling cadence. Do not cache across port codes or hazard types.

Testing and monitoring

Pre-prod tests: create a smoke test that runs the same request you will use in production and validates only the envelope and timestamp freshness. Avoid hardcoding any inner fields so schema evolutions do not break your tests unnecessarily.

Alert hygiene: alert on transport errors, persistent non‑success envelopes, and stale timestamps beyond your acceptable window. Suppress single‑shot failures with a short backoff window to reduce noise.

Runbooks: include a step for verifying your current daily request count relative to the 100/day/IP guest limit. If you approach the ceiling, either slow your pollers or switch to a key-backed deployment.

FAQ

Q: Can I call the Severe Weather Disruptions lookup without an API key?
Yes. Guest access allows 100 requests per day per IP without a key. For higher volumes or production SLAs, add the X-API-Key: YOUR_API_KEY header.

Q: Is port congestion data live?
No. FreightPulse port congestion references IMF PortWatch and is lagged by ~6–7 days as a 7‑day average versus a 90‑day baseline. It is not live AIS wait times.

Q: What hazards are included?
Natural hazards only, sourced from GDACS/USGS/NOAA. The lookup is for severe weather disruptions and excludes strikes, labor actions, and canal-related closures.

Q: How should I parse the response schema?
Always start with the envelope: check success, read data, and log meta if present. The example JSON demonstrates the envelope and timestamp fields. Consult the Documentation for the exact fields returned for severe weather events, and avoid assuming field names you have not seen.

Q: Can I use these results to quote prices or fares?
No. Do not quote a freight-rates USD fare as today’s price from this lookup. The Severe Weather Disruptions endpoint is for natural hazard signals, not pricing.

Ready to productionize your severe weather watcher for critical ports? Get an API key and move beyond the 100/day/IP guest limit with a few clicks: Register.