Home → Blog

Flooding can cripple port operations without much warning, and your stakeholders still expect ETAs, diversion plans, and risk flags. By the end of this post you will be able to query a Weather-focused Flood Disruptions API for a specific port, understand response envelopes, handle guest access limits, and wire the results into your own alerting and planning pipelines—without guessing at live freight rates or AIS wait times.

What you can build: reliable flood disruption lookups with guest access

The FreightPulse Flood Disruptions lookup is designed for Weather-driven natural hazards. You can start immediately as a guest—no key required—at 100 requests per day per IP, then switch to authenticated traffic using the documented header to scale. The response is always returned in a consistent envelope you can validate quickly, and any congestion context is based on IMF PortWatch (lagged ~6–7 days), not live AIS.

Illustration: API for Flood Disruptions

If you decide to move beyond guest mode, create an account at Register. Reference fields and usage patterns at the official Documentation.

Endpoint and method

The Weather-focused lookup for Flood Disruptions is a simple HTTP GET with an optional authentication header. The port is provided as a standard code, and the disruption type is flood.

Guest requests are allowed up to 100 per day per IP, which is sufficient for development and basic monitoring. Add your key when you need predictable throughput or to consolidate usage across services.

Copy-paste cURL (guest or with key)

This is the officially provided cURL sample. You can run it as-is to start testing flood disruption lookups for the Los Angeles port (USLAX). Leave the header in place with YOUR_API_KEY if you have one; if you are using guest mode, your request still works without a key but remains subject to the 100/day/IP limit.

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

Understand the response envelope and timestamps

All Weather endpoints, including Flood Disruptions, follow a consistent top-level structure: {"success": true, "data": {...}} and may include "meta". Timestamps are ISO 8601 and UTC (offset included), which makes caching and deduplication straightforward.

Below is the official JSON sample block. Use it to confirm envelope parsing (success, data, meta) and timestamp handling; domain-specific fields in "data" will differ for flood disruption lookups.

{
    "success": true,
    "data": {
        "timestamp": "2026-10-24T00:00:14+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": "5ebea297-1cdd-40f7-bd28-4ac04788c6b6"
    }
}

Fields you will actually use across Weather endpoints:

Do not treat any freight rate, fare, or price-like number as a live “today’s price” in Weather workflows. Flood disruptions are event-driven and should be handled independently from fares and live AIS wait time proxies.

Python example: calling the Flood Disruptions endpoint and parsing the envelope

This minimal script makes the same GET request and focuses on envelope validation, UTC timestamp parsing, and safe handling when the service is in guest mode vs authenticated mode. It does not assume any domain-specific event fields beyond the documented envelope.

import os
import sys
import json
import time
from urllib.parse import urlencode

import requests
from datetime import datetime

BASE_URL = "https://freightpulsehq.com/api/v1/disruptions"

def iso_to_utc(dt_str):
# Robust ISO 8601 parse without extra dependencies; fallback to raw on error
try:
return datetime.fromisoformat(dt_str.replace("Z", "+00:00"))
except Exception:
return None

def fetch_flood_disruptions(port_code="USLAX", api_key=None):
params = {"port": port_code, "type": "flood"}
url = f"{BASE_URL}?{urlencode(params)}"
headers = {}
if api_key:
headers["X-API-Key"] = api_key

resp = requests.get(url, headers=headers, timeout=20)
resp.raise_for_status()
payload = resp.json()

if not isinstance(payload, dict) or "success" not in payload:
raise ValueError("Unexpected envelope: missing 'success'")

if not payload.get("success", False):
# Prefer a controlled failure path; upstream may include error info in 'meta' or elsewhere
raise RuntimeError(f"Request not successful. Meta: {payload.get('meta')}")

data = payload.get("data", {})
# Timestamp handling (if present)
ts_raw = data.get("timestamp")
ts = iso_to_utc(ts_raw) if ts_raw else None

# For Weather Flood Disruptions, all domain-specific fields are read from 'data'
# Avoid guessing field names; use them conditionally if present.
result = {
"timestamp_raw": ts_raw,
"timestamp_parsed_utc": ts.isoformat() if ts else None,
"source": data.get("source"),
# Keep data opaque unless you have explicit field docs:
"raw_data_keys": list(data.keys())
}

return {
"result": result,
"meta_request_id": (payload.get("meta") or {}).get("request_id")
}

if __name__ == "__main__":
port = os.environ.get("FP_PORT", "USLAX")
api_key = os.environ.get("FP_API_KEY") # optional; guest mode if absent

try:
out = fetch_flood_disruptions(port_code=port, api_key=api_key)
print(json.dumps(out, indent=2, sort_keys=True, default=str))
except requests.HTTPError as e:
# Handle quota (guest: 100/day/IP) and other HTTP failures
sys.stderr.write(f"HTTP error: {e.response.status_code} {e.response.text}\n")
sys.exit(1)
except Exception as e:
sys.stderr.write(f"Error: {e}\n")
sys.exit(1)

Notes on the example:

Event filtering and Weather-only scope

Flood disruptions are part of Weather-driven natural hazards. The API aggregates hazard intelligence from GDACS, USGS, and NOAA. It does not cover labor strikes, canal blockages, or other non-weather operational issues. If you need to align port operational status with Flood Disruptions, use the congestion context notes below rather than live AIS wait times.

Caching and rate-limit strategy

With guest access limited to 100 requests/day per IP, plan a cache layer at your edge or within your service mesh. Because the API provides ISO 8601 timestamps and a stable envelope, you can key caches on (port, type) with a TTL based on your operational needs and the observed timestamp.

Validating and normalizing port inputs

Use the exact port codes supported by your operations team; the example uses USLAX. Normalize inputs to uppercase and strip whitespace before building the query string. Keep your mapping of common names (e.g., Los Angeles) to codes in a local dictionary and validate before calling the API to avoid wasted calls against guest quotas.

Interpreting disruptions alongside lagged congestion context

When correlating a flood alert with operational risk, always remember that FreightPulse’s congestion context is derived from IMF PortWatch and lagged ~6–7 days. Use it to establish baseline deviation rather than a live nowcast. Do not present the result as a live AIS wait time or imply minute-by-minute queue estimates.

Error handling and edge conditions

When the envelope contains success=false, check the meta block for a request_id and any diagnostic notes. On 429, you have likely reached the guest 100/day/IP limit; back off and add an API key header. On malformed input (e.g., unknown port code), fail fast client-side by validating before you call the API.

Production hardening checklist

Frequently asked questions

Can I use the Flood Disruptions endpoint without an API key?

Yes. Guest requests are allowed at 100 requests per day per IP. For higher or pooled limits, add the X-API-Key: YOUR_API_KEY header.

What sources are used for flood events?

Natural hazards only, aggregated from GDACS/USGS/NOAA. The endpoint does not include strikes, canal incidents, or other non-weather events.

Is port congestion live?

No. Any congestion context is derived from IMF PortWatch as a 7-day average versus a 90-day baseline and is lagged ~6–7 days. It is not live AIS wait times.

What does the response look like?

All responses follow the documented envelope: {"success": true, "data": {...}} and may include "meta". Use data.timestamp (ISO 8601, UTC offset) when present for caching and deduplication. Domain-specific fields for Flood Disruptions will be inside data.

Can I quote today’s price for freight or fuel from this endpoint?

No. Do not quote a freight-rates USD fare as today’s price in Weather disruption workflows. This endpoint is for hazard intelligence, not live pricing.

Ready to move beyond the 100/day/IP guest limit and wire Flood Disruptions into production? Create your account at Register, then review endpoint details and envelope semantics in the Documentation.