Home → Blog

Freight forwarders and logistics operators live in a world where minutes matter. A cyclone in the Philippine Sea, a sudden spike in diesel, or a carrier’s safety status change can ripple into missed sails, blown delivery windows, and unhappy shippers. The lack of a unified, real-time operational picture—fuel, rates, port congestion, carrier status, and hazard alerts—forces teams to juggle disconnected feeds and ad‑hoc spreadsheets that are slow, brittle, and impossible to automate reliably at scale.

This post shows how to build real-time geo-fenced alerts and automated incident playbooks on top of FreightPulse, a single REST API that consolidates modern logistics intelligence into one developer-friendly surface. We will walk through practical patterns to detect hazards near a port, trigger playbooks that verify carriers, estimate alternate truckload rates, and adjust fuel surcharges—all with consistent JSON responses and clean error semantics. You will learn concrete implementation details, performance tips, and failure-handling strategies that take you from prototype to production with confidence.

The outcome: fewer manual checks, faster resolutions, and proactive customer communication when disruptions strike. Whether you are building a freight-forwarding control tower, a TMS add‑on, or a supply chain risk dashboard, consolidating these data streams behind FreightPulse is the fastest path to real-world impact.

Introduction

In the last few years, resilient supply chains have become an executive priority. But resilience depends on timely, contextual signals. Without a unified source for fuel prices, live truckload quotes, port congestion context, carrier safety verification, and natural-disruption alerts, developers are left to stitch together public datasets, costly maritime feeds, and dozens of web scrapers. The result is operational fragility: a tangle of integrations that break during peak seasons when you need them most.

The problem compounds during incidents. Imagine a typhoon approaching Japan while your containers are queuing for transshipment. You need to know: Does this hazard threaten my port of discharge? If I pivot to a West Coast entry point, what does congestion look like today vs its baseline? Can I stage a transload and linehaul? If so, what’s a ballpark FTL rate to my consignee’s ZIP? Will my carrier pass a safety check? How should I adjust my FSC on the fly? Every minute spent context-switching between portals is a minute not spent executing the plan.

This article demonstrates how to centralize those answers and automate playbooks—detection, decisioning, and action—using one API and a consistent JSON model. We will emphasize practical integration strategies: filter disruptions by port radius, validate carriers, query alternate truckload lanes, and tie outcomes to FSC adjustments guided by up-to-date fuel data and congestion history.

Why FreightPulse

FreightPulse unifies five high-value data domains behind a single REST API. For developers and operators, this consolidation eliminates the toil of reconciling schemas, rate limits, and inconsistent timestamps across heterogeneous sources. Below are the differentiators that matter in production:

Together, these design choices help your engineering team move faster with fewer moving parts, while your operations team gets actionable context without navigating multiple portals. With FreightPulse, you can implement detection-to-action loops in one place and scale them confidently.

Quick Start

Base URL: 

https://freightpulsehq.com/api/v1

Authentication is provided via the X-API-Key header. All endpoints return a shared response envelope containing success, data, and error fields.

First request: Retrieve current national and regional fuel prices. This is often the first building block for a fuel-surcharge calculator or a cost-sensitivity widget in your TMS. 

curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/fuel-prices"

Example JSON response: 

{
"success": true,
"data": {
"timestamp": "2026-07-30T12:00:00Z",
"source": "EIA (U.S. Energy Information Administration)",
"currency": "USD",
"unit": "gallon",
"data": {
"diesel": {
"national_average": 3.847,
"change_week": -0.023,
"change_percent": -0.6,
"regions": {
"east_coast": 3.912,
"midwest": 3.756,
"gulf_coast": 3.623,
"rocky_mountain": 3.891,
"west_coast": 4.456,
"california": 4.892
},
"historical": {
"30d_avg": 3.82,
"90d_avg": 3.75,
"yoy_change_percent": -8.2
}
},
"gasoline": {
"national_average": 3.156,
"historical": {
"30d_avg": 3.1,
"90d_avg": 3.05,
"yoy_change_percent": 1.1
}
}
}
}
}

Key fields:

Core Endpoints

1) Natural-Disruption Alerts: GET /disruptions

Use this endpoint to detect active natural hazards—cyclones, earthquakes, severe weather, and more—and filter them by port radius to eliminate noise. This is the cornerstone of geo-fenced alerting and automated incident playbooks.

Endpoint: 

GET /disruptions

Key parameters:

Example cURL: 

curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/disruptions?port=USLAX&severity=high"

Example JSON response: 

{
"success": true,
"data": {
"results": [
{
"id": "gdacs:TC:1001305",
"type": "cyclone",
"severity": "moderate",
"title": "Tropical Cyclone SAUDEL-26",
"country": "Japan",
"starts_at": "2026-08-18T12:00:00+00:00",
"source": "GDACS"
}
]
}
}

Field explanations and usage:

Implementation tips:

2) Port Congestion Context: GET /port-congestion

Use this endpoint to understand whether a port is running below or above its baseline activity. While this is not a live AIS feed, it yields a reliable trend indicator for capacity and throughput. Integrate it into your decision logic when rerouting or setting customer expectations.

Endpoint: 

GET /port-congestion

Key parameters:

Example cURL: 

curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/port-congestion?port=USLAX"

Example JSON response: 

{
"success": true,
"data": {
"results": [
{
"port": "Los Angeles-Long Beach",
"locode": "US LAX",
"country": "United States",
"congestion": "moderate",
"as_of": "2026-08-14",
"metrics": {
"recent_avg_portcalls_per_day": 8.7,
"baseline_avg_portcalls_per_day": 10.2,
"ratio_vs_baseline": 0.85
}
}
]
}
}

Field explanations and usage:

Best practices:

3) Live Freight Rate Quotes: GET /freight-rates

This endpoint provides live FTL quotes for US lanes, enabling automated “Plan B” costing when a disruption forces mode or route changes. Ocean and air modes are supported for certain corridors; US FTL is the central use case for rapid re-planning after a port or weather incident.

Endpoint: 

GET /freight-rates

Key parameters (trucking):

Example cURL (FTL US lane): 

curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=10001&destination_zip=90210"

Example JSON response: 

{
"success": true,
"data": {
"mode": "trucking",
"service": "FTL (53' dry van)",
"source": "Warp",
"price_usd": 7207.92,
"transit_days": 4,
"pickup_date": "2026-08-24",
"delivery_date": "2026-08-28"
}
}

Field explanations and usage:

Error behavior note:

4) Carrier Verification: GET /carriers

Automation should never skip due diligence. Before you auto-tender or spin up a backup carrier, verify status and safety using the carriers endpoint. This tightens your compliance loop while keeping human review to exceptions only.

Endpoint: 

GET /carriers

Key parameters:

Example cURL (trucking DOT search): 

curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/carriers?q=54283"

Example JSON response: 

{
"success": true,
"data": {
"type": "trucking",
"query": "54283",
"results": [
{
"dot_number": 54283,
"legal_name": "SWIFT TRANSPORTATION COMPANY OF ARIZONA LLC",
"status": "active",
"safety_rating": "S",
"drivers": 12883,
"address": {
"city": "Phoenix",
"state": "AZ",
"country": "US"
}
}
]
}
}

Field explanations and usage:

Error handling:

5) Fuel Prices and Historical Series: GET /fuel-prices and GET /historical

Your playbooks should translate disruption into cost insight. Use current fuel pricing to recalibrate surcharges and historical series to contextualize variance.

Endpoints: 

GET /fuel-prices
GET /historical

Key parameters (historical):

Example cURL (diesel time series): 

curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/historical?metric=fuel_price_diesel_national&period=30d"

Example JSON response: 

{
"success": true,
"data": {
"metric": "fuel_price_diesel_national",
"period": "30d",
"series": [
{ "date": "2026-07-27", "value": 5.257 },
{ "date": "2026-08-03", "value": 5.343 }
]
}
}

Usage:

Putting It Together: Real-Time Geo-Fenced Alerts and Automated Playbooks

This section illustrates a concrete incident automation flow that connects the dots across disruptions, port congestion, carrier verification, freight rates, and fuel signals. The goal is to convert raw detection into operational action within minutes, not hours.

  1. Detect and filter hazards near a port:
    • Poll /disruptions with ?port=USLAX&severity=moderate|high every few minutes.
    • For each new ID, enrich with impacted shipments (legs that touch USLAX in the next N days).
  2. Contextualize with congestion:
    • Call /port-congestion?port=USLAX to see if the port is operating below baseline.
    • If congestion is moderate or high and the ratio_vs_baseline < 0.9, escalate reroute probability.
  3. Estimate alternate plan costs:
    • If pivoting to transload + linehaul, call /freight-rates with the alternate lane ZIPs.
    • Store quotes in a lane cache keyed by origin-destination-pickup_date to avoid repetitive calls.
  4. Verify carriers:
    • Run /carriers on candidate carriers by DOT or name. Block auto-tender if status != active or safety_rating violates policy.
  5. Recalculate FSC and communicate:
    • Pull /fuel-prices and compute the FSC delta vs your internal baseline.
    • Attach a congestion trend chart using /historical for transparency.

The result: an automated “detect-decide-do” loop that minimizes human toil, preserves compliance, and delivers timely, credible updates to shippers.

End-to-End Example: Reference Implementation Snippets

Below are concise code examples to help you wire the loop described above. Adjust retry strategies, logging, and observability for your environment.

JavaScript (Node.js) – Disruption Detection and Deduplication 

import fetch from "node-fetch";

const BASE = "https://freightpulsehq.com/api/v1";
const HEADERS = { "X-API-Key": process.env.FP_KEY };

async function fetchDisruptionsNear(portLocode, severity = "high") {
const url = `${BASE}/disruptions?port=${encodeURIComponent(portLocode)}&severity=${severity}`;
const res = await fetch(url, { headers: HEADERS });
const body = await res.json();
if (!body.success) throw new Error(body.error || "Unknown error");
return body.data.results || [];
}

// Example dedup using an in-memory Set; replace with Redis in production.
const seen = new Set();

async function poll() {
try {
const results = await fetchDisruptionsNear("USLAX", "high");
for (const r of results) {
if (seen.has(r.id)) continue;
seen.add(r.id);
// Enqueue to your incident bus with shipment-port leg mapping
console.log("New disruption:", r.id, r.type, r.severity, r.title);
}
} catch (e) {
console.error("Polling error:", e.message);
}
}

// Backoff + jitter sample
function start() {
let delay = 30000;
(function tick() {
poll().finally(() => {
const jitter = Math.floor(Math.random() * 5000);
setTimeout(tick, delay + jitter);
delay = Math.min(delay * 1.25, 300000);
});
})();
}

start();

Python – Reroute Costing and Carrier Verification 

import os
import requests
from datetime import date

BASE = "https://freightpulsehq.com/api/v1"
HEADERS = { "X-API-Key": os.getenv("FP_KEY") }

def get_freight_rate(origin_zip, dest_zip, pickup=None):
params = {
"mode": "trucking",
"origin_zip": origin_zip,
"destination_zip": dest_zip
}
if pickup:
params["pickup_date"] = pickup.isoformat()
r = requests.get(f"{BASE}/freight-rates", headers=HEADERS, params=params, timeout=15)
data = r.json()
if not data.get("success"):
raise RuntimeError(data.get("error", "Unknown error"))
return data["data"]

def verify_carrier(query):
params = {"q": query, "type": "trucking"}
r = requests.get(f"{BASE}/carriers", headers=HEADERS, params=params, timeout=15)
data = r.json()
if not data.get("success"):
raise RuntimeError(data.get("error", "Unknown error"))
return data["data"]["results"]

def get_fuel():
r = requests.get(f"{BASE}/fuel-prices", headers=HEADERS, timeout=10)
data = r.json()
if not data.get("success"):
raise RuntimeError(data.get("error", "Unknown error"))
return data["data"]["data"]["diesel"]

def reroute_plan(o_zip, d_zip, carrier_dot):
# 1) Quote
quote = get_freight_rate(o_zip, d_zip, pickup=date.today())
# 2) Carrier check
carriers = verify_carrier(str(carrier_dot))
if not carriers:
return {"ok": False, "reason": "No carrier record"}
c = carriers[0]
if c["status"].lower() != "active":
return {"ok": False, "reason": "Carrier inactive"}
# 3) FSC context
diesel = get_fuel()
return {
"ok": True,
"price_usd": quote["price_usd"],
"transit_days": quote["transit_days"],
"carrier": {
"dot": c["dot_number"],
"legal_name": c["legal_name"],
"safety_rating": c.get("safety_rating")
},
"diesel": {
"current": diesel["national_average"],
"avg_30d": diesel["historical"]["30d_avg"]
}
}

if __name__ == "__main__":
plan = reroute_plan("90058", "85001", 54283)
print(plan)

Error Handling Patterns

FreightPulse returns structured errors with consistent HTTP status codes. Design your clients to branch on status codes and parse the error field.

Example error response: 

{
"success": false,
"error": "Human-readable message."
}

Production tips:

Real-World Use Cases

1) Geo-Fenced Disruption Alerting for a Forwarder’s Control Tower

Build a service that continuously polls /disruptions filtered by the control tower’s priority ports. When a high-severity cyclone or severe weather appears within the defined radius, the service cross-references bookings scheduled in the next 10 days, pushes Slack/PagerDuty alerts, and writes an incident record to your TMS. Use /port-congestion to add context to the alert, and /historical to attach a 30-day congestion trend.

Endpoints used: /disruptions, /port-congestion, /historical.

2) Auto-Reroute and Quote Assist for a 3PL

When a disruption triggers near a West Coast port, the 3PL system evaluates transload-and-linehaul options. It queries /freight-rates with candidate ZIP pairs to produce fast FTL estimates, then verifies a shortlist of carriers via /carriers. The operator sees a ranked set of options with price, transit days, and carrier safety, enabling a one-click pivot. Attach current diesel pricing from /fuel-prices to reflect FSC adjustments in the quote.

Endpoints used: /freight-rates, /carriers, /fuel-prices.

3) FSC Calculator Widget for a Shipper Portal

The shipper-facing portal displays today’s diesel national average, regional splits by PADD, and a chart of the last 90 days to justify FSC updates. The widget pulls /fuel-prices for the current snapshot and /historical for time series, calculating differences vs a contract baseline and surfacing the delta in a transparent, auditable way.

Endpoints used: /fuel-prices, /historical.

Deep Dive: Field-by-Field Interpretation and Best Practices

/disruptions: Interpreting Types and Severities

/port-congestion: Using Ratios and Baselines

/freight-rates: Lane Caching and Fallbacks

/carriers: Safety and Status Gates

/fuel-prices and /historical: FSC Governance

Security, Observability, and Reliability Patterns

Implementing production-grade automation requires attention to governance and reliability:

Additional Examples: Complete JSON and Interpretation

1) Country-Wide Port Scan

Quickly survey a country’s ports to highlight where conditions deviate from baseline. 

curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/port-congestion?country=United%20States"

{
"success": true,
"data": {
"results": [
{
"port": "Los Angeles-Long Beach",
"locode": "US LAX",
"country": "United States",
"congestion": "moderate",
"as_of": "2026-08-14",
"metrics": {
"recent_avg_portcalls_per_day": 8.7,
"baseline_avg_portcalls_per_day": 10.2,
"ratio_vs_baseline": 0.85
}
},
{
"port": "Port of New York/New Jersey",
"locode": "US NYC",
"country": "United States",
"congestion": "low",
"as_of": "2026-08-14",
"metrics": {
"recent_avg_portcalls_per_day": 7.9,
"baseline_avg_portcalls_per_day": 7.6,
"ratio_vs_baseline": 1.04
}
}
]
}
}

Interpretation: LA/LB sits below baseline (0.85), while NY/NJ sits near or slightly above. If a West Coast hazard emerges, favor East Coast routings where viable and communicate expected dwell differences.

2) Disruptions Filtered by Type

Focus on fast-moving severe weather without conflating it with broader cyclone events. 

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

{
"success": true,
"data": {
"results": [
{
"id": "nws:SW:98234",
"type": "severe_weather",
"severity": "high",
"title": "High Wind Warning - Los Angeles County",
"country": "United States",
"starts_at": "2026-08-20T03:00:00+00:00",
"source": "NOAA/NWS"
}
]
}
}

Interpretation: High-severity NWS alerts near LA typically impact terminal operations and drayage reliability. For same-day gate activity, auto-notify dray providers and buffer dwell times.

3) Historical Port Congestion Series for Trend Charts

Use historical series for dashboards and anomaly detection. 

curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/historical?metric=port_congestion:USLAX&period=90d"

{
"success": true,
"data": {
"metric": "port_congestion:USLAX",
"period": "90d",
"series": [
{ "date": "2026-05-15", "value": 0.93 },
{ "date": "2026-05-22", "value": 0.97 },
{ "date": "2026-05-29", "value": 0.88 }
]
}
}

Interpretation: Sustained values below 0.9 suggest underperformance vs baseline; if coupled with active disruptions, increase buffer times and trigger proactive customer comms.

Performance and Integration Tips

FAQ

How often do FreightPulse fuel prices update?

Fuel prices track EIA updates and include national and regional snapshots along with rolling averages. For automated FSC, treat the snapshot as authoritative for the current period and blend with the 30d average for smoother adjustments.

Can I look up ocean carriers as well as trucking carriers?

Yes. Use the /carriers endpoint with type=ocean and a valid organization number or name to retrieve ocean NVOCC/OTI directory details. Air lookups return available: false, so plan UI fallbacks accordingly.

Does the port congestion data reflect real-time vessel wait times?

No. Port congestion is based on a 7‑day average of port calls versus a 90‑day baseline and is typically lagged by about 6–7 days. It is best used as a context and trend signal, not as live AIS tracking.

How do I filter disruptions by a specific port radius?

Pass the port parameter with a port name or LOCODE (e.g., USLAX). FreightPulse applies sensible default radii—300 km globally and 100 km for US NWS severe weather—so you receive only relevant hazards near that port.

What happens if I forget a required parameter on /carriers or /freight-rates?

/carriers returns a structured 422 error when q is missing. /freight-rates responds with HTTP 200 but indicates available: false when required lane parameters are missing; detect this and prompt the user for the missing inputs.

Conclusion + CTA

When disruptions strike, the difference between a scramble and a smooth pivot is data: timely, relevant, and easy to act on. By consolidating hazard detection, port context, carrier verification, live truckload pricing, and fuel intelligence into one API, you can build incident playbooks that actually run—fast, repeatably, and with clear governance. Your engineers focus on business logic instead of vendor glue code; your operators act with confidence instead of hunting through portals.

Start by wiring /disruptions with a port filter, layer in /port-congestion for context, call /freight-rates to cost alternates, verify with /carriers, and reconcile FSC using /fuel-prices and /historical. Ship a minimal loop in days, then iterate: add more ports, refine thresholds, improve caching, and enhance observability. The payoff is immediate—shorter recovery times and stronger customer trust.

Build your next control tower module, TMS plugin, or risk dashboard on top of FreightPulse. Consolidate your logistics intelligence into one developer-friendly API and move from reactive firefighting to proactive, automated operations. Ready to explore endpoints and ship your first playbook? Try FreightPulse for free.