Home → Blog

Teams moving cargo through wildfire-prone regions need a simple way to detect weather-driven disruptions around key ports. By the end of this guide, you will be able to query FreightPulse for wildfire disruptions at a specific port, handle guest access limits, parse the response envelope, and integrate the signal into your routing or ETA logic.

What this API delivers for wildfire weather disruptions

FreightPulse exposes a Weather category lookup for natural-hazard disruptions, including wildfires sourced from GDACS/USGS/NOAA. You can query for a target port and filter to wildfire to understand exposure around a terminal before dispatch, booking, or re-routing. This article focuses on the Wildfire Disruptions lookup for a specific port code.

Illustration: API for Wildfire Disruptions

Key facts before you start:

Quickstart: guest access and a working cURL

You can start as a guest for quick evaluation. Without an API key, your IP can perform up to 100 requests per day. For production volume and reliability, register for an API key and pass it via the X-API-Key header.

Copy-paste cURL for the Wildfire Disruptions lookup at Los Angeles (USLAX):

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

Replace YOUR_API_KEY with your key once registered. Guests may omit the header to use the 100 requests/day per IP allowance.

Notes:

Response envelope: how to parse it safely

All FreightPulse responses use the documented envelope: {"success":true,"data":{...}} with optional meta. The specific fields inside data vary by dataset. The official sample below shows the envelope shape and metadata fields you should expect to handle (timestamps, units, and a meta.request_id). Copy this JSON exactly when mocking or writing tests for envelope handling.

{
    "success": true,
    "data": {
        "timestamp": "2026-10-25T00:00:21+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": "0b222d15-4b07-42ca-9d7e-9d69eb38b03b"
    }
}

What to use from this structure in your integration:

Minimal client: query USLAX wildfire disruptions

The snippet below calls the same endpoint shown in the cURL, checks the envelope, and illustrates safe access patterns without assuming undocumented fields. You can adapt this to your queue or server functions.

JavaScript (Node.js or Deno)

import fetch from "node-fetch";

// Query wildfire disruptions for Los Angeles (USLAX)
const url = "https://freightpulsehq.com/api/v1/disruptions?port=USLAX&type=wildfire";

async function getWildfireDisruptions() {
const res = await fetch(url, {
headers: {
"X-API-Key": "YOUR_API_KEY" // Omit this header when testing guest access
}
});

// Basic HTTP guard
if (!res.ok) {
throw new Error(`HTTP ${res.status}: ${await res.text()}`);
}

const body = await res.json();

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

// Common metadata you can rely on
const { timestamp, source } = body.data;
const metaRequestId = body.meta && body.meta.request_id ? body.meta.request_id : null;

// The event payload may vary by dataset; avoid hard-coding fields not in docs
const payload = body.data.data;

console.log("Timestamp:", timestamp);
console.log("Source:", source);
console.log("Meta request_id:", metaRequestId);
console.log("Payload keys:", payload ? Object.keys(payload) : []);

// Example downstream handling:
// - Cache the whole data object indexed by port and type
// - Extract hazard severity/geometry fields per the docs once integrated
}

getWildfireDisruptions().catch(err => {
console.error("Disruptions fetch failed:", err);
});

How to operationalize wildfire signals at port level

When a wildfire is detected near a port like USLAX, the actionable steps are to flag exposure windows and decide on re-routing or timing buffers. Disruptions are sourced from natural hazards only (GDACS/USGS/NOAA), so your logic should not assume labor or canal events in this stream.

Implementation tips:

Scheduling, caching, and data freshness

Use the ISO 8601 timestamp from the response to govern your cache. In practice, schedule wildfire checks on a cadence that matches your lead times to terminal gates and truck dispatch windows.

Error handling and resilience

Build the following guards to keep your job stable and within quotas:

Field selection: what to store and how to compare across days

Even though specific disruption fields vary by dataset, a minimal, durable schema in your application should include:

For comparisons across runs (e.g., daily checks), compare event identifiers if provided, or fallback to stable composites such as location/time windows provided by the dataset. This helps prevent double-alerting and supports resolving “ended” vs “ongoing.”

Testing your integration without burning quota

To avoid hitting guest limits during development:

If you need higher throughput for testing, register for a key and use the header. Keep test and production keys separate to simplify incident attribution.

Security and deployment notes

Reference: the exact cURL and JSON sample you can reuse

These blocks are here verbatim for quick copy-testing of your HTTP client and envelope parsing. The cURL uses the Wildfire Disruptions endpoint; the JSON shows the envelope and metadata layout to validate your parser.

Deployment checklist

FAQ

Can I use the API without registering?
Yes. Guests can make up to 100 requests per day per IP without a key. For higher throughput and reliability, register and send X-API-Key: YOUR_API_KEY.

Are the disruptions live AIS wait times?
No. Disruptions are natural-hazard signals (e.g., wildfire) from GDACS/USGS/NOAA. If you also track port congestion, remember FreightPulse’s congestion metric is lagged ~6–7 days (7-day average vs 90-day baseline) and is not a live AIS wait time.

Which hazards are included?
Natural hazards only. For this article the focus is wildfires. The feed does not include strikes, canal closures, or other non-weather events.

What timezone and units should I expect?
Timestamps use ISO 8601 with an explicit timezone offset in the envelope. Units and any measurement fields are dataset-specific; consult the Documentation for the exact fields exposed in the wildfire disruptions payload.

Can I quote or store freight-rate fares from this API?
Do not quote a freight-rates USD fare as today’s price from this API. This Weather endpoint is for natural hazard disruptions, not rate quoting.

Ready to move from guest testing to production-grade wildfire monitoring at your critical ports? Create your API key in minutes and start integrating: Register.