Home → Blog

Ports that depend on clear weather can grind to a halt when a volcano ejects ash into air corridors or deposits debris on key approaches. By the end of this post, you’ll be able to call the FreightPulse Volcano Disruptions Weather API for a target port, parse the envelope, respect guest-access limits, and wire the response into a workflow that flags natural-hazard disruptions without guessing prices, fares, or live wait times.

What you can build with the Volcano Disruptions Weather API

This API helps operations teams and analysts detect natural-hazard disruptions related to volcanic activity that may affect maritime and intermodal logistics. The focus is on hazard signals from sources like GDACS/USGS/NOAA, not labor actions, strikes, or canal transits. You can:

Illustration: API for Volcano Disruptions

Access model and request envelope

The Weather category endpoint for volcano disruptions follows a consistent structure and authentication approach. Keep the following facts in mind when you integrate:

If you need an API key, you can get one at Register. For full reference material, see the Documentation.

Endpoint, parameters, and a working curl

The disruptions endpoint accepts a port and a type constrained to volcano for this workflow. Example for Los Angeles (USLAX):

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

Notes:

Official JSON response example and how to read it

The following official sample demonstrates the standard success/meta envelope returned by FreightPulse. Copy it exactly for testing your parser. The inner data section is illustrative of the envelope format; treat the envelope fields (success, data, meta) as canonical for your client.

{
    "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": "a21d7505-6ff3-4230-b93e-c9dd1d17e0a3"
    }
}

How to use this structure in your client:

In production, you will parse the same envelope fields from the Volcano Disruptions Weather API and then read the relevant disruption payload fields you need for your alerts. If a field is not documented, don’t assume it exists; consult the Documentation.

A minimal Python client for volcano disruptions

The snippet below performs a GET against the same endpoint, handles guest or key auth, enforces the envelope checks, and demonstrates basic cache behavior keyed by the timestamp. Replace the example port with your target port when you deploy.

import os
import time
import requests

API_URL = "https://freightpulsehq.com/api/v1/disruptions"
PORT = "USLAX" # Los Angeles
TYPE = "volcano" # Weather hazard filter
API_KEY = os.getenv("FREIGHTPULSE_API_KEY", "") # leave empty to use guest access

# naive in-memory cache keyed by (port, type)
CACHE = {}

def get_volcano_disruptions(port: str, hazard_type: str = "volcano"):
params = {"port": port, "type": hazard_type}
headers = {}
if API_KEY:
headers["X-API-Key"] = API_KEY

# simple cache check: if we saw this timestamp recently, return cached data
cache_key = (port, hazard_type)
cached = CACHE.get(cache_key)
if cached:
# TTL based on your operational tolerance; here we use 15 minutes
if time.time() - cached["fetched_at"] < 900:
return cached["payload"]

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

# Envelope validation
if not isinstance(payload, dict) or "success" not in payload:
raise ValueError("Unexpected response structure")
if not payload.get("success"):
# Prefer structured error handling if the API returns error details
raise RuntimeError("API reported unsuccessful status")

# Timestamp is useful for cache-control and display
data = payload.get("data", {})
timestamp = data.get("timestamp")

# Cache and return
CACHE[cache_key] = {
"payload": payload,
"timestamp": timestamp,
"fetched_at": time.time(),
}
return payload

if __name__ == "__main__":
result = get_volcano_disruptions(PORT, TYPE)
# Log essentials for observability
meta = result.get("meta", {})
print("success:", result.get("success"))
print("timestamp:", result.get("data", {}).get("timestamp"))
print("request_id:", meta.get("request_id"))
# Your application would now inspect disruption details inside result["data"]

Interpreting volcano disruptions without inventing live wait times

When a volcano releases ash, authorities may close parts of airspace and routing corridors; maritime operations can be indirectly impacted through safety protocols, port closures, or intermodal disruptions. This Weather endpoint focuses on natural hazards — it does not include strikes or canal movements. When presenting results:

Caching, rate limits, and resilient polling

Design your client for stability:

Validation and rollout checklist

Before shipping to production:

Putting it together with an alerting workflow

Here’s a straightforward approach to operationalize volcano disruptions for a single port like USLAX:

  1. Scheduler: Run a small job every 15 minutes that calls the disruptions endpoint with type=volcano and your target port.
  2. Parse envelope: If success is true, read data.timestamp and disruption details. Persist the response for audit.
  3. Deduplicate: Key new alerts by a combination of port, hazard type, and the hazard’s unique identifiers or timestamps as documented, to avoid duplicate notifications.
  4. Notify: Send notifications only when a new or materially changed event is detected. Include timestamp and source. Avoid adding speculative metrics (fares, live wait times).
  5. Dashboard: Surface a card with the latest disruption timestamp and any qualitative flags. Optionally, include a labeled, lagged congestion context panel for the same port, clearly indicating it is a 7‑day average vs 90‑day baseline and lags ~6–7 days.

Common pitfalls and how to avoid them

Testing with curl and verifying your parser

Use the provided curl to confirm network access, header handling, and parameter pass-through. Next, point your JSON parser at the official sample to ensure it correctly checks success and reads data.timestamp and meta.request_id. This shrinks the time from first call to a robust client:

Once your parser is passing the envelope checks on the official sample, switch to your live port/hazard queries and start layering in alert logic. Keep your logging consistent so you can trace any prod issue with request_id.

Operational notes that save time

FAQ

Q: Can I use the Volcano Disruptions API without an API key?
A: Yes. Guest access allows 100 requests/day per IP without a key. Add X-API-Key: YOUR_API_KEY when you’re ready for authenticated usage.

Q: Does the API provide live AIS wait times for ports affected by ash clouds?
A: No. FreightPulse congestion figures are lagged ~6–7 days and reported as a 7‑day average vs a 90‑day baseline. They are not live AIS wait times.

Q: Which events are included in Volcano Disruptions?
A: Natural hazards from documented sources (e.g., GDACS/USGS/NOAA). It does not include labor strikes, canal transits, or other non-weather categories.

Q: Can I quote a freight-rates USD fare in my app based on this data?
A: No. Do not quote a freight-rates USD fare as today’s price using this endpoint. Keep it for hazard detection and operations planning.

Q: What fields should I always log for troubleshooting?
A: Log success, data.timestamp, and meta.request_id, along with HTTP status. These will help correlate client logs with server-side diagnostics.

Ready to build a reliable Weather hazard pipeline for volcano disruptions? Start with guest calls, then switch to an API key when you need more throughput. Create your account at Register, and keep the Documentation handy as you integrate.