Home → Blog

Ports and inland terminals need a fast, repeatable way to check whether flooding is disrupting cargo flows. By the end of this guide, you will be able to authenticate, call the FreightPulse Flood Disruptions lookup for a specific port, and safely parse the response to drive weather-aware routing, ETAs, and exception workflows.

What you will implement

This post is an auth-first guide to querying Flood Disruptions from FreightPulse. You will:

Illustration: Look Up Flood Disruptions

All examples remain within Weather and natural hazards scope (floods from GDACS, USGS, NOAA). We do not cover strikes, canals, or labor actions.

Authentication, quotas, and envelope

Authentication is sent as a header: X-API-Key: YOUR_API_KEY. Guests without a key may call the API with an implicit limit of 100 requests per day per IP. For production, register and use an API key to avoid rate surprises.

Every response is wrapped in a stable envelope like: {"success":true,"data":{...}}. Your parser should first verify success is true before reading fields from data. When present, meta often contains request tracing such as request_id, which is useful for logging and support tickets.

If you do not have a key yet, create one here: Register. Reference behavior and field descriptions in the official Documentation.

Flood Disruptions: endpoint and filters

Flood disruptions are looked up via the disruptions endpoint with a weather hazard filter. Keep your requests specific:

Hazard sources are natural hazards only (GDACS, USGS, NOAA). Do not expect labor actions or canal backlogs here.

Make your first call

The following request targets flood disruptions at USLAX using header-based auth. Paste this into your terminal and replace the API key value if you have one. If you do not, you can still test within the guest quota.

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

Understand the response envelope

Responses use a consistent envelope across FreightPulse. Below is an official JSON sample of the envelope structure you will encounter. Copy it to test your parser. Note: always check success, then read data. When present, meta.request_id is useful for logs.

{
    "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 your parser should rely on:

Units and currency fields are provided when the payload includes quantitative measures. Handle them explicitly to avoid mixing metrics from different unit systems.

JavaScript example: fetch flood disruptions for USLAX

The snippet below calls the same endpoint you tested with curl, verifies the envelope, and sketches a safe pattern for consuming fields without assuming schema beyond the documented envelope.

async function getFloodDisruptions(portCode = "USLAX") {
const url = `https://freightpulsehq.com/api/v1/disruptions?port=${encodeURIComponent(portCode)}&type=flood`;
const resp = await fetch(url, {
headers: {
"X-API-Key": "YOUR_API_KEY"
}
});

if (!resp.ok) {
throw new Error(`HTTP ${resp.status}`);
}

const body = await resp.json();

// Envelope checks
if (!body || body.success !== true) {
throw new Error("Unsuccessful response envelope");
}

// Always safe fields
const meta = body.meta || {};
const requestId = meta.request_id;
const data = body.data || {};

// Common cross-payload fields you can rely on when present
const timestamp = data.timestamp; // ISO8601
const source = data.source; // Provenance
const unit = data.unit; // If quantitative data present
const currency = data.currency; // If monetary values present

// Your downstream logic goes here:
// - Map flood hazard alerts to operational actions
// - Use timestamp and source in audit logs
// - Never treat lagged congestion as live wait times

return {
requestId,
timestamp,
source,
unit,
currency,
raw: body
};
}

// Example invocation
getFloodDisruptions("USLAX")
.then(res => {
console.log("Request ID:", res.requestId);
console.log("Timestamp:", res.timestamp);
console.log("Source:", res.source);
})
.catch(err => {
console.error("Error fetching flood disruptions:", err);
});

Operational behavior you should account for

Error handling and resiliency

Building a clean internal interface

Wrap calls to the disruptions endpoint with a small adapter that normalizes must-have outputs for your team, for example:

Persist the full raw payload alongside your normalized fields. This helps incident review and avoids lossy transformations.

Testing: dry runs and guardrails

Production notes for dispatch and TMS integration

Security and key management

Going deeper

As you expand beyond a single port, build a scheduler that iterates a list of UN/LOCODEs and caches results keyed by port and hazard type. If you later correlate with lagged congestion signals, display both clearly labeled in your UI with their distinct cadences. For deeper field-level descriptions and any optional parameters, refer to the official Documentation.

FAQ

Is an API key required?
Recommended. Guests can make up to 100 requests per day per IP without a key, but production services should send X-API-Key: YOUR_API_KEY to avoid throttling.

Is the port congestion metric live?
No. FreightPulse congestion uses IMF PortWatch with a 7-day average vs a 90-day baseline and is lagged about 6–7 days. It is not live AIS wait time.

What hazard sources are included for floods?
Natural hazard feeds only: GDACS, USGS, and NOAA. Labor actions and canal restrictions are out of scope for this lookup.

What timezone are timestamps in?
Timestamps are ISO 8601 with an explicit offset. Treat +00:00 as UTC.

Can I quote a freight rate based on this API?
No. Do not quote a freight-rates USD fare as today’s price from this data.

Next step

Create your API key and build your first flood disruptions lookup today. Start here: Register. Keep the documentation tab open while you code: Documentation.