Home → Blog

You need a reliable way to programmatically fetch weather-driven drought disruptions that could affect port operations and downstream logistics planning. By the end of this guide, you will be able to authenticate, query, and parse the FreightPulse Weather disruptions lookup for drought at a specific port using PHP, verify the envelope, and wire up a simple JavaScript check for monitoring.

What you can and cannot get from the Drought Disruptions lookup

The FreightPulse Weather disruptions lookup focuses strictly on natural hazards. For drought, that means event signals sourced from GDACS/USGS/NOAA. Do not use this endpoint for labor actions, strikes, or canal scheduling; those are out of scope.

Illustration: How to Get Drought Disruptions

Use the Documentation for broader context, parameter semantics, and field-level contracts as they evolve.

Authenticate and call the Weather disruptions endpoint

The Weather disruptions query for drought at a port is performed via GET with an API key sent in the X-API-Key header. The request returns a JSON envelope with a top-level success boolean and a data object. The official sample below shows the exact curl and JSON block you should use for wiring and testing the envelope and header, copied verbatim.

curl: drought disruptions at USLAX

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

Official JSON sample (for envelope and field parsing)

{
"success": true,
"data": {
"timestamp": "2026-10-11T00:00:19+00:00",
"source": "EIA (U.S. Energy Information Administration)",
"currency": "USD",
"unit": "gallon",
"data": {
"diesel": {
"national_average": 6.199,
"change_week": -0.183,
"change_percent": -2.87,
"updated_at": "2026-10-05",
"regions": {
"east_coast": 5.951,
"midwest": 6.286,
"gulf_coast": 5.819,
"rocky_mountain": 6.267,
"west_coast": 7.229,
"california": 8.082
}
},
"gasoline": {
"national_average": 4.354,
"change_week": -0.111,
"change_percent": -2.49,
"updated_at": "2026-10-05",
"grades": {
"regular": 4.354,
"midgrade": 4.99,
"premium": 5.4
}
},
"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.349,
"diesel_90d_avg": 5.686,
"diesel_yoy_change": 67,
"gasoline_30d_avg": 4.404,
"gasoline_90d_avg": 4.155,
"gasoline_yoy_change": 39.4
}
},
"meta": {
"request_id": "82f8dc19-b0a6-4249-aea0-584078406a33"
}
}

Fields you will actually use for envelope handling and downstream logic:

Note: This official sample demonstrates the response envelope, timestamp format, and common metadata. In your production drought-disruptions calls, use the same header and envelope parsing. Only consume fields documented for the Weather disruptions category; do not extrapolate or invent fields.

PHP: build a robust Weather drought disruptions client

The goal is to send the correct X-API-Key header, request drought disruptions for a port, verify the {"success":true,"data":{...}} envelope, and safely read timestamp and other documented fields for weather context. The example below uses cURL and includes defensive checks that you can drop into a Symfony/Laravel service or a plain PHP script.

PHP example

<?php
$endpoint = "https://freightpulsehq.com/api/v1/disruptions?port=USLAX&type=drought";
$ch = curl_init($endpoint);

$headers = [
"X-API-Key: YOUR_API_KEY",
"Accept: application/json"
];

curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => $headers,
CURLOPT_CONNECTTIMEOUT => 10,
CURLOPT_TIMEOUT => 20
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$curlErrNo = curl_errno($ch);
$curlErr = curl_error($ch);
curl_close($ch);

if ($curlErrNo !== 0) {
// Network or TLS issue
error_log("curl error ($curlErrNo): $curlErr");
http_response_code(502);
echo json_encode(["error" => "Upstream connection issue"]);
exit;
}

if ($httpCode < 200 || $httpCode >= 300) {
// Non-2xx: still try to parse body for diagnostics
error_log("HTTP $httpCode body: $response");
http_response_code(502);
echo json_encode(["error" => "Upstream returned HTTP $httpCode"]);
exit;
}

$payload = json_decode($response, true);
if (!is_array($payload)) {
http_response_code(502);
echo json_encode(["error" => "Invalid JSON"]);
exit;
}

// Envelope: {"success": true, "data": {...}, "meta": {...}}
if (!array_key_exists("success", $payload) || $payload["success"] !== true) {
http_response_code(502);
echo json_encode(["error" => "Upstream indicated failure", "body" => $payload]);
exit;
}

$data = $payload["data"] ?? null;
$meta = $payload["meta"] ?? [];
if (!is_array($data)) {
http_response_code(502);
echo json_encode(["error" => "Missing data object"]);
exit;
}

// Practical fields to read without assuming a specific schema:
$timestamp = $data["timestamp"] ?? null; // ISO-8601 UTC
$source = $data["source"] ?? null; // Upstream source label

// For dashboards: expose minimal normalized summary.
// Do not invent freight-rate prices or live AIS waits.
$out = [
"ok" => true,
"port" => "USLAX",
"type" => "drought",
"timestamp" => $timestamp,
"source" => $source,
"request_id" => $meta["request_id"] ?? null
];

header("Content-Type: application/json");
echo json_encode($out);

Implementation notes:

JavaScript quick check (same Weather endpoint)

Use this script to validate connectivity and the envelope from a Node.js service or a CI probe. Keep the same URL and header. Do not change params or field names.

import fetch from "node-fetch";

const url = "https://freightpulsehq.com/api/v1/disruptions?port=USLAX&type=drought";

async function checkDroughtDisruptions() {
const res = await fetch(url, {
headers: {
"X-API-Key": "YOUR_API_KEY",
"Accept": "application/json"
},
// Timeouts: use an AbortController in production
});

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

const body = await res.json();

if (body?.success !== true || typeof body?.data !== "object") {
throw new Error("Bad envelope");
}

const timestamp = body.data.timestamp ?? null;
const source = body.data.source ?? null;

return {
ok: true,
port: "USLAX",
type: "drought",
timestamp,
source,
request_id: body.meta?.request_id ?? null
};
}

checkDroughtDisruptions()
.then((r) => console.log(JSON.stringify(r, null, 2)))
.catch((e) => {
console.error(e.message);
process.exitCode = 1;
});

Interpreting drought disruptions for Weather operations

Scope your dashboards and alerts to weather hazards only. For drought, you will typically map event presence, severity classes, and confidence flags from Weather sources such as GDACS/USGS/NOAA as documented. Do not include labor actions, port strikes, or canal scheduling under this endpoint.

Production notes: caching, quotas, and safety rails

Step-by-step PHP integration checklist

1) Configure environment

2) Implement the request

3) Parse the envelope

4) Normalize and store

5) Display with correct caveats

FAQ

Q: Can I call the endpoint without an API key?
A: Yes, as a guest you can call it at up to 100 requests/day per IP. For production workloads, set X-API-Key: YOUR_API_KEY.

Q: Are these drought signals live?
A: Weather disruptions are sourced from natural-hazard providers (GDACS/USGS/NOAA). Port congestion data you may correlate with is IMF PortWatch and is lagged ~6–7 days; do not treat it as live AIS waits.

Q: What timezone are timestamps in?
A: ISO-8601 with offset; treat them as UTC and store as such.

Q: Can I use this data to quote current freight rates?
A: No. Do not quote a freight-rates USD fare as today’s price from this endpoint.

Q: Does the endpoint include non-weather events like strikes or canal transits?
A: No. It is for natural hazards only. Do not include strikes or canal scheduling.

Ready to integrate drought disruptions into your Weather operations pipeline? Get an API key and start building with the live endpoint today: Register. For field-level contracts and updates, keep the Documentation handy.