Home → Blog

You need a reliable way to look up drought-driven weather disruptions that can impact freight operations at a specific port. By the end of this guide, you’ll be able to authenticate, query, and parse FreightPulse’s Drought Disruptions lookup for a target port, understand the response envelope and timestamps, and build a small integration that is safe to cache and monitor in production.

Scope and data sources for drought disruptions

This guide focuses on weather and natural hazard impacts specifically related to drought. FreightPulse’s Drought Disruptions lookup aggregates weather-related hazards and indicators from natural hazard sources (e.g., GDACS/USGS/NOAA). It does not include labor actions, canal operations, or strikes. Keep your usage and alerting strictly within natural hazard signals when interpreting results.

Illustration: Look Up Drought Disruptions

Congestion context is helpful when assessing downstream effects, but remember that FreightPulse port congestion uses IMF PortWatch and is lagged approximately six to seven days, using a seven-day average versus a 90-day baseline. It is not a live AIS wait-time stream. Treat it as contextual background rather than a real-time queue length.

If you need additional field definitions or endpoint behavior beyond this article, refer to the official Documentation.

Authentication and request limits

Authentication uses an HTTP header:

Guest access (without a key) is capped at 100 requests per day per IP. Add the X-API-Key header as shown below to avoid hitting guest limits and to enable production-grade usage.

Requesting drought disruptions for a port

The disruptions endpoint accepts a port and a type filter identifying the hazard. For drought-specific lookups at the Port of Los Angeles (USLAX):

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

Notes:

Understanding the response envelope and fields

FreightPulse responses use a consistent JSON envelope with a top-level success flag and a data object. The official sample below demonstrates the standard envelope format and key metadata fields you should expect and parse when working with the Drought Disruptions lookup.

{
    "success": true,
    "data": {
        "timestamp": "2026-11-10T00:00:23+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": "d94eff60-a9d9-4291-992f-ee9ce9b73ebe"
    }
}

Fields to pay attention to when building drought-focused workflows:

The envelope shape above is what you will parse in drought disruption lookups as well. Build parsers that validate success, handle timestamps in UTC, record provenance, and gracefully handle nested data.

Copy-pasteable Python example for Drought Disruptions

The snippet below requests the drought disruptions for USLAX, validates the envelope, and shows how to safely read top-level metadata and iterate the nested data payload without assuming a fixed schema.

import os
import json
import time
import datetime
import requests

API_KEY = os.getenv("FREIGHTPULSE_API_KEY", "YOUR_API_KEY")
URL = "https://freightpulsehq.com/api/v1/disruptions"
PARAMS = {
"port": "USLAX",
"type": "drought"
}
HEADERS = {"X-API-Key": API_KEY}

def iso_to_utc(ts):
# Parses ISO 8601 with offset to UTC-aware datetime
return datetime.datetime.fromisoformat(ts.replace("Z", "+00:00"))

def fetch_disruptions():
r = requests.get(URL, params=PARAMS, headers=HEADERS, timeout=30)
r.raise_for_status()
payload = r.json()

if not isinstance(payload, dict) or not payload.get("success"):
raise RuntimeError("Request failed or unexpected envelope")

data = payload.get("data", {})
meta = payload.get("meta", {})

# Core metadata
ts = data.get("timestamp")
source = data.get("source")
currency = data.get("currency")
unit = data.get("unit")
main = data.get("data", {})
historical = data.get("historical", {})

print("Success:", payload.get("success"))
if ts:
print("Timestamp (raw):", ts)
try:
dt = iso_to_utc(ts)
print("Timestamp (UTC parsed):", dt.isoformat())
except Exception:
print("Note: failed to parse timestamp; keep as string")

if source:
print("Source:", source)
if currency:
print("Currency:", currency)
if unit:
print("Unit:", unit)

# Iterate the main payload defensively (schema may vary by hazard)
if isinstance(main, dict):
print("Payload keys:", list(main.keys()))
# Example: peek one level deeper if values are dicts
for k, v in main.items():
if isinstance(v, dict):
subkeys = list(v.keys())
print(f" - {k}: {len(subkeys)} fields")
else:
print(f" - {k}: {type(v).__name__}")

if isinstance(historical, dict) and historical:
print("Historical keys:", list(historical.keys()))

# Trace ID
rid = meta.get("request_id")
if rid:
print("Request ID:", rid)

return payload

if __name__ == "__main__":
out = fetch_disruptions()
# Optional: cache the JSON to disk to avoid re-requesting within your polling interval
with open("uslax_drought.json", "w") as f:
json.dump(out, f, indent=2)
print("Saved to uslax_drought.json")

Implementation notes:

Practical integration details that save time

These points help you operate the Drought Disruptions lookup reliably without guesswork:

Validation workflow for port-level drought checks

Build a short, automated checklist into your job runner to ensure stable ingestion and alerting on drought disruptions:

  1. Connectivity check: Perform a HEAD or a minimal GET with your X-API-Key once per deployment to confirm auth and routing.
  2. Schema guardrails: Validate the presence of success, data, and meta. If missing, back off and alert.
  3. Timestamp sanity: Parse data.timestamp into UTC. Reject or quarantine records with timestamps older than your acceptable window for alerting.
  4. Source verification: Ensure data.source exists. Record it with each alert so downstream users can see provenance.
  5. Payload inspection: Iterate data.data keys and validate expected drought-related fields for your use case without hard-coding a fixed schema. Unknown keys should not fail the pipeline.
  6. Context fusion: If you also show congestion context, label it clearly as lagged IMF PortWatch (7-day avg vs. 90-day baseline), not live queue times.

Error handling, retries, and backoff

Network conditions and transient upstream issues happen. Make your integration robust:

Testing strategy before production

Run a short battery of tests to ensure correct behavior before deploying:

Frequently asked questions

Do I need an API key to query drought disruptions?
You can call the endpoint without a key as a guest, but the limit is 100 requests per day per IP. For production usage, add X-API-Key: YOUR_API_KEY.

Are the timestamps in local port time?
Timestamps are provided in ISO 8601 with explicit timezone information. Treat them as UTC unless your application requires a conversion for display.

Can I use this endpoint for strikes or canal closures?
No. The Drought Disruptions lookup focuses on weather and natural hazards. Do not use it for non-weather events.

Is port congestion data live?
No. FreightPulse port congestion is IMF PortWatch-derived, lagged roughly 6–7 days (7-day average vs. a 90-day baseline). It is not live AIS wait-time data.

How do I handle pagination?
If the response includes more data than you expect, check the Documentation for any pagination fields or recommended paging patterns. Implement cursor-based or page-based loops only if the docs specify them.

Next step

Set up your key, copy the curl, and wire the Python example into your job runner. When you are ready to move past guest limits and operationalize drought monitoring across multiple ports, create your account here: Register.