Your ops team needs a dependable Weather/Natural-Hazard API to detect earthquake-related port disruptions before bookings and drayage plans are locked. By the end of this guide, you’ll be able to query FreightPulse’s Earthquake Disruptions endpoint for a specific port, understand the data envelope and units, run guest lookups (100 requests/day per IP without an API key), and wire up a minimal integration that is safe for production caching and alerting.
What this Weather/Hazard integration covers (and what it doesn’t)
This article is limited to natural hazards affecting freight logistics, specifically earthquakes. FreightPulse’s Earthquake Disruptions lookup uses authoritative Weather/Hazard sources (GDACS/USGS/NOAA) for event discovery and tracking. It does not cover labor strikes, canal transits, or other non-weather operational issues.
For port congestion context that is often paired with hazard events, FreightPulse references IMF PortWatch with a ~6–7 day lag, exposing a 7-day average versus a 90-day baseline (not live AIS wait times). Keep this lag in mind when correlating a recent earthquake to congestion trends.
Auth, access, and the data envelope
FreightPulse supports both guest and key-based access:
- Guest access: 100 requests/day per IP, no key required.
- API key header: X-API-Key: YOUR_API_KEY (when available, use it to avoid guest quotas).
Every response uses a consistent top-level envelope so you can fail fast and cache reliably:
- Envelope: {"success": true, "data": {...}}
- On success, read fields strictly from the data object. Treat missing keys as “not provided” rather than errors.
Endpoint and parameters for Earthquake Disruptions
Use the Disruptions endpoint filtered to earthquakes for the port you monitor:
- HTTP method: GET
- Path: /api/v1/disruptions
- Query parameters:
- port: a port code such as USLAX
- type: earthquake
Example port: USLAX (Los Angeles). Replace the port with the specific terminal of interest in your network. Do not add undocumented parameters.
Official curl example
The following sample is the official, copy-pasteable curl. It uses the Disruptions endpoint with type=earthquake and the documented header. You can omit the header entirely for guest mode if you want to stay within 100 requests/day per IP.
curl -H "X-API-Key: YOUR_API_KEY" "https://freightpulsehq.com/api/v1/disruptions?port=USLAX&type=earthquake"Official JSON response example and how to read it
Below is the official JSON block you should treat as the canonical example for envelope shape, timestamps, units, and nested structures. Copy it exactly for tests and contract validation.
{
"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"
}
}How to use this example structure in your integration:
- success: Boolean gate for downstream processing. If false, short-circuit and surface the error.
- data.timestamp: ISO 8601 with timezone offset (+00:00 indicates UTC). Use it to anchor your cache and idempotency keys.
- data.source: Provenance. For Weather/Hazard workflows, align your alert severity with the source’s reliability window.
- data.currency and data.unit: Always read units and currency from the payload instead of hardcoding. Use these for any normalized reporting you compute around hazard impacts.
- meta.request_id: Log this for traceability when debugging alerting or suppression logic.
JavaScript example: querying earthquakes and handling the envelope
The example below shows a minimal fetch against the same endpoint used in the curl. It demonstrates reading the envelope, timestamp, and key fields you will typically log for Weather/Hazard monitoring. Replace the header value with YOUR_API_KEY when you have one, or remove the header for guest mode.
async function getEarthquakeDisruptionsUSLAX() {
const url = "https://freightpulsehq.com/api/v1/disruptions?port=USLAX&type=earthquake";
const res = await fetch(url, {
headers: {
"X-API-Key": "YOUR_API_KEY"
}
});
if (!res.ok) {
throw new Error("HTTP " + res.status + " from FreightPulse Disruptions");
}
const body = await res.json();
if (!body || body.success !== true || !body.data) {
throw new Error("Invalid envelope or no data");
}
// Read common operational fields for logging and caching
const ts = body.data.timestamp; // ISO 8601 with timezone
const src = body.data.source; // provenance string
const unit = body.data.unit; // unit string if provided
const currency = body.data.currency; // currency if provided
// Your app: store a cache entry keyed by (port,type) and timestamp
return {
timestamp: ts,
source: src,
unit,
currency,
raw: body.data
};
}
getEarthquakeDisruptionsUSLAX()
.then(data => {
console.log("Disruptions fetched at:", data.timestamp, "source=", data.source);
})
.catch(err => {
console.error("Fetch failed:", err);
});How to run safely in production (Weather/Hazard specifics)
To keep your Weather/Hazard alerts accurate without spamming teams or customers, implement the following:
- Caching and staleness: Use data.timestamp as the freshness anchor. A 15–60 minute cache is typical for hazard polling pipelines; adjust to your on-call sensitivity.
- Event windowing: Earthquakes can generate aftershocks and updated magnitudes. Deduplicate notifications by correlating events within a rolling time window keyed to port and hazard type.
- Rate limits: If you operate without an API key, guest access allows 100 requests/day per IP. Batch ports into a single polling interval and reuse results where feasible.
- Time zones: Treat all comparisons in UTC to avoid alert jitter around local DST changes. The API timestamp includes its offset; normalize to UTC internally.
- Congestion context: If you overlay earthquake events with congestion, remember that IMF PortWatch is lagged by ~6–7 days and represents a 7-day average vs a 90-day baseline. Don’t present it as live AIS wait times.
Operational guardrails: avoiding false precision
Do not present a freight-rates USD fare as “today’s price” when reacting to Weather/Hazard events. Earthquakes impact risk and routing, but quoting a current fare when it isn’t part of the disruptions payload leads to confusion and rework. If you must display cost implications, clearly separate modeled impacts from observed hazard data, and never imply the disruptions endpoint contains live AIS or spot pricing.
Minimal integration plan
Step 1 — Choose the polling scope
List the critical ports your network depends on (e.g., USLAX, USOAK, USSEA). Create a small registry mapping port codes to your internal lanes and customers so you can suppress noise for irrelevant ports.
Step 2 — Implement a single poller
Create a lightweight job that queries the Disruptions endpoint with type=earthquake per port. Start in guest mode if you’re exploring (100 requests/day per IP). Add the X-API-Key: YOUR_API_KEY header when moving to a shared or higher-volume environment.
Step 3 — Normalize and persist
Store the envelope, timestamp, and source with the raw data. Use the timestamp as your deduplication key. Do not infer missing fields; nullable handling is part of a robust hazard integration.
Step 4 — Alerting and suppression
Trigger alerts when new or materially updated earthquake events appear for a monitored port. Suppress repeats within a set window (for example, one hour) unless magnitude or severity has changed. Keep the messaging strictly about hazards, not prices.
Step 5 — Overlay with lagged congestion
When providing context to ops teams, include the IMF PortWatch 7-day average versus the 90-day baseline, with a note that it is lagged ~6–7 days. Label it clearly so users don’t mistake it for live vessel queues or AIS-derived dwell times.
Python alternative: same endpoint, same envelope
If you prefer Python for Weather/Hazard jobs, this snippet mirrors the JavaScript logic and focuses on the envelope fields your app should log and trust. As with JavaScript, remove the X-API-Key header for guest mode.
import requests
def get_earthquake_disruptions_uslax():
url = "https://freightpulsehq.com/api/v1/disruptions?port=USLAX&type=earthquake"
headers = {
"X-API-Key": "YOUR_API_KEY"
}
resp = requests.get(url, headers=headers, timeout=20)
resp.raise_for_status()
body = resp.json()
if not body or body.get("success") is not True or "data" not in body:
raise ValueError("Invalid envelope or missing data")
data = body["data"]
return {
"timestamp": data.get("timestamp"), # ISO 8601
"source": data.get("source"),
"unit": data.get("unit"),
"currency": data.get("currency"),
"raw": data
}
if __name__ == "__main__":
result = get_earthquake_disruptions_uslax()
print("Fetched disruptions at", result["timestamp"], "source=", result["source"])Testing and reliability checklist
- Envelope contract: Unit test that success, data, and meta.request_id exist, and data.timestamp is parseable as UTC time.
- Header toggling: Verify both with and without the X-API-Key header. Ensure guest usage stays under 100 requests/day per IP.
- Timeouts and retries: Use short timeouts (10–20s) with 1–2 idempotent retries on network errors. Do not retry on 4xx.
- Clock drift: Sync your service clock via NTP and always convert timestamps to UTC before comparison.
- No invented fields: Only read documented fields; treat unknown fields as future-compatible extensions.
Developer FAQ
Q1: Can I query without an API key while prototyping?
Yes. Guest access allows 100 requests/day per IP without a key. Remove the X-API-Key header entirely to use guest mode.
Q2: Is port congestion live?
No. FreightPulse references IMF PortWatch with a ~6–7 day lag and reports a 7-day average versus a 90-day baseline. Do not present it as live AIS wait times.
Q3: Can I include spot freight rates in my hazard alerts?
No. Do not quote a freight-rates USD fare as today’s price in this workflow. Keep alerts focused on the Weather/Hazard disruption itself.
Q4: What data sources are used for earthquakes?
Natural hazards only from GDACS/USGS/NOAA. The disruptions lookup does not include strikes, canal incidents, or other non-weather categories.
Q5: What is the response format I should code against?
Use the envelope {"success": true, "data": {...}}. Always parse data.timestamp (ISO 8601 with timezone), respect units and currency when present, and log meta.request_id for traceability.
Ready to build your Weather/Hazard monitor for earthquakes at key ports? Get an API key and production-ready limits by signing up: Register. For full reference details, see the Documentation.