Home → Blog

Modern shippers and 3PLs don’t lose customers because trucks can’t move—they lose them because silence fills the gaps when plans change. A delayed pickup with no updated ETA, a vessel arriving into a congested port with no explanation, a sudden winter storm rerouting drivers without any narrative: these are the moments that fracture trust. If you operate a supply chain SaaS product or run a customer success team at a 3PL, you need a reliable, defensible way to publish live ETAs and exception narratives that combine multiple data sources in one place—without maintaining five different feeds and brittle parsers.

This post demonstrates how to build real-time, customer-facing ETAs and exception narratives using FreightPulse. You’ll learn how to enrich shipment timelines with diesel price transparency for surcharge explanations, inject live FTL rate/ETA context, watch port congestion trends for scenario planning, verify carriers, and listen for natural-disruption alerts near ports before they become “fire-drill” calls. We’ll work through concrete API calls, explain responses field-by-field, and share best practices for resiliency and observability so your team can go from whiteboard to production quickly.

We’ll also focus on the one requirement your customers demand: clarity. When a shipment is on time, say why you’re confident. When it slips, provide a crisp exception narrative grounded in data—“high winds within 100 km of USLAX” or “7-day portcall average at 85% of baseline”—and automatically adjust SLAs and ETAs across your customer portal or TMS widgets. With FreightPulse, you can pull fuel prices, freight rates, port congestion trends, carrier details, and natural-disruption alerts from a single REST API that normalizes responses into a consistent schema designed for production systems.

Why FreightPulse

There’s a gulf between “we connected a feed” and “we ship to production daily with reliable data customers trust.” FreightPulse closes that gap by consolidating critical logistics intelligence behind one REST interface so you don’t waste engineering cycles stitching together disparate feeds or writing fragile scrapers. Here are four practical reasons teams adopt FreightPulse when they need customer-facing ETAs and exception narratives:

The headline: one normalized API that gives your product the “complete sentence” it needs—price context, ETA windows, carrier verification, congestion trends, and disruption narratives—so your CS team can say exactly what’s happening and why.

Quick Start

FreightPulse is a straightforward HTTP+JSON service with a single base URL:

Base URL: https://freightpulsehq.com/api/v1

All responses share this shape: 

{
"success": true,
"data": { ... }
// If success=false:
// "error": "Human-readable message"
}

Make your first request to retrieve national fuel prices (EIA) with historical context: 

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
}
}
}
}
}

How to use this data: add a “Fuel Surcharge” explainer to your quote page. Show that surcharges are tied to the EIA national average diesel price, and use change_percent to narrate week-over-week deltas. Present regional context for multi-PADD operations, and use historical bands to temper customer expectations (“diesel is trending 8.2% lower YoY, which we’re passing through in our contractual FSC index”).

Core Endpoints for Real-Time ETAs and Exception Narratives

This section drills into endpoints you’ll stitch together to power ETAs and transparent exception narratives: live FTL freight rates for baseline transit windows, natural-disruption alerts for proactive risk annotations, port-congestion trends for macro context, carrier lookups for verification, and historical series for dashboards. We include cURL, field explanations, and integration tips.

1) Live Freight Rates and Transit Windows: GET /freight-rates

Purpose: Retrieve a live quote and indicative transit window for US FTL lanes (via Warp) and limited ocean/air (Asian origins to US destinations). This supplies the backbone ETA you display to customers immediately at quote or booking time.

Endpoint: /freight-rates

Key params:

Example cURL: 

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

Example 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-by-field:

Implementation tips:

2) Natural-Disruption Alerts (Proactive Risk Narratives): GET /disruptions

Purpose: Feed your exception GPU: cyclones, earthquakes, severe weather, and more—filtered by port radius or country—so you can proactively narrate risk and adjust ETAs or SLAs when warranted. Perfect for “Potential impact near USLAX: moderate cyclone risk” banners.

Endpoint: /disruptions

Key params:

Example cURL: 

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

Example 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-by-field:

Implementation tips:

3) Port Congestion Trends (Macro Context, SLA Expectations): GET /port-congestion

Purpose: Provide macro congestion context that influences planning and expectation-setting for ocean legs and drayage. Congestion is approximated from IMF PortWatch AIS data as a 7-day average of portcalls vs a 90-day baseline. Important: this data is lagged ~6–7 days and is not live AIS tracking.

Endpoint: /port-congestion

Key params (at least one required):

Example cURL: 

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

Example 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-by-field:

Implementation tips:

4) Carrier Verification (Trust and Compliance): GET /carriers

Purpose: Let your users (or internal ops) verify US trucking carriers via FMCSA SAFER and look up ocean NVOCC/OTI carriers from the FMC directory—without leaving your app. This reduces risk of tendering to a non-compliant or inactive carrier and adds credibility in customer communications.

Endpoint: /carriers

Key params:

Example cURL: 

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

Example 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-by-field:

Implementation tips:

5) Fuel Prices and Historical Series (Transparent Surcharge Story): GET /fuel-prices and GET /historical

Purpose: Anchor your fuel-surcharge logic and trend visualizations with authoritative national averages and region breakdowns. Pair current /fuel-prices with /historical for charts and YoY context. This makes your FSC policy visible and defensible to shippers.

Endpoints: /fuel-prices and /historical

Historical params:

Historical example cURL: 

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

Example 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 }
]
}
}

Field-by-field:

Implementation tips:

Combining Data for ETAs and Exception Narratives

An ETA on its own is a number; an exception narrative is the story that builds trust. Below we show how to stitch together a baseline ETA from /freight-rates with targeted risk signals from /disruptions and context from /port-congestion, then add cost transparency from /fuel-prices and carrier trust from /carriers.

Here’s a minimal JavaScript example showing how a backend service might assemble a customer-facing payload for a New York → Beverly Hills FTL move with a risk overlay and fuel context. 

// Node.js/TypeScript-style pseudo-implementation

import fetch from "node-fetch";

const BASE = "https://freightpulsehq.com/api/v1";
const headers = { "X-API-Key": "YOUR_API_KEY" };

async function getBaselineQuote() {
const url = `${BASE}/freight-rates?mode=trucking&origin_zip=10001&destination_zip=90210&pickup_date=2026-08-24`;
const r = await fetch(url, { headers });
return r.json();
}

async function getFuel() {
const r = await fetch(`${BASE}/fuel-prices`, { headers });
return r.json();
}

async function getLAConcession() {
const r = await fetch(`${BASE}/port-congestion?port=USLAX`, { headers });
return r.json();
}

async function getUSLAXDisruptions() {
const r = await fetch(`${BASE}/disruptions?port=USLAX&severity=high`, { headers });
return r.json();
}

async function buildCustomerFacingETA() {
const [quote, fuel, cong, dis] = await Promise.all([
getBaselineQuote(), getFuel(), getLAConcession(), getUSLAXDisruptions()
]);

const eta = quote?.data?.delivery_date;
const transit_days = quote?.data?.transit_days;

const diesel = fuel?.data?.data?.diesel?.national_average;
const dieselWoW = fuel?.data?.data?.diesel?.change_percent;

const congestion = cong?.data?.results?.[0];
const congestionNarrative = congestion ?
`Port activity at ${congestion.port} is ${congestion.congestion} (${Math.round(congestion.metrics.ratio_vs_baseline * 100)}% of 90-day baseline, as of ${congestion.as_of}).`
: null;

const disruptions = dis?.data?.results || [];
const severeRisk = disruptions.length > 0;

return {
baseline_eta: eta,
transit_days,
cost_context: {
diesel_usd_per_gallon: diesel,
diesel_week_over_week_change_pct: dieselWoW
},
exception_risks: disruptions.map(d => ({
id: d.id,
type: d.type,
severity: d.severity,
title: d.title,
starts_at: d.starts_at
})),
macro_context: congestionNarrative,
recommended_actions: severeRisk ? [
"Notify consignee of weather-related risk near USLAX.",
"Add 12–24 hours buffer to delivery commitment.",
"Enable dispatch contingency for alternate drayage window."
] : []
};
}

buildCustomerFacingETA().then(console.log).catch(console.error);

This pattern yields an ETA that isn’t just a date—it’s a defensible promise with supporting evidence and recommended actions.

Error Handling, Retries, and Observability

All FreightPulse endpoints return a top-level success boolean and either data or error. That uniform contract lets you implement a single middleware for validation, logging, and retries across services.

Typical error shape: 

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

Best practices:

Example Python utility wrapping calls with timeouts and structured logging: 

import requests
import time
import logging

BASE = "https://freightpulsehq.com/api/v1"
HEADERS = {"X-API-Key": "YOUR_API_KEY"}
logging.basicConfig(level=logging.INFO)

def fetch_json(path, params=None, timeout=5.0, retries=2):
url = f"{BASE}{path}"
for attempt in range(retries + 1):
try:
r = requests.get(url, headers=HEADERS, params=params, timeout=timeout)
payload = r.json()
logging.info("fp_call path=%s status=%s success=%s", path, r.status_code, payload.get("success"))
if payload.get("success") is True:
return payload["data"]
else:
# known business error, no retry
logging.warning("fp_error path=%s error=%s", path, payload.get("error"))
return None
except Exception as e:
logging.exception("fp_exception path=%s attempt=%d", path, attempt)
if attempt < retries:
sleep = (2 ** attempt) * 0.25
time.sleep(sleep)
else:
return None

data = fetch_json("/fuel-prices")
print(data)

Observability and governance:

End-to-End Examples by Endpoint

This section provides additional, concrete JSON examples across key endpoints so you can see realistic payloads you’ll parse in production, with guidance on interpreting fields to drive customer-facing narratives.

Fuel Prices: Example and Field Usage 

{
"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
}
}
}
}
}

Freight Rates: Example and Field Usage 

{
"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"
}
}

Port Congestion: Example and Field Usage 

{
"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
}
}
]
}
}

Carrier Lookup: Example and Field Usage 

{
"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"
}
}
]
}
}

Disruptions: Example and Field Usage 

{
"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"
}
]
}
}

Real-World Use Cases You Can Ship This Quarter

1) Customer-Facing ETA Widget with Risk Narratives

Build a reusable widget that shows a baseline ETA (from /freight-rates), then layers risk banners if /disruptions returns moderate/high events near relevant ports. For ocean-linked legs, add a macro context line from /port-congestion (ratio_vs_baseline + as_of) so customers understand whether delays are structural rather than operational. Endpoints used: /freight-rates, /disruptions, /port-congestion.

2) Transparent Fuel-Surcharge Calculator and Explainer

Integrate /fuel-prices for current national and regional diesel averages, and graph the trend line from /historical. Display the precise FSC formula and cite current national_average and change_percent so shippers see that surcharges reflect market movements, not guesswork. Endpoints used: /fuel-prices, /historical.

3) Carrier Vetting and Tender Compliance Panel

Before tendering, automatically run /carriers against the selected trucking provider’s DOT number. If status is not active or the safety_rating is concerning, flag the tender and propose alternatives. This reduces risk exposure and speeds up audits. Endpoints used: /carriers.

4) Port-Centric Forecasting Sidebar for Forwarders

Add a “Port Outlook” sidebar to your booking or tracking page. Query /port-congestion for key ports (Shanghai, Singapore, Rotterdam, Los Angeles-Long Beach, and others) and show ratio_vs_baseline over time from /historical (port_congestion:<portid>). Pair with /disruptions to annotate macro vs acute risk. Endpoints used: /port-congestion, /historical, /disruptions.

5) SLA Breach Early-Warning Service for 3PL CS Teams

Run a periodic job that scans active shipments by lane/port, pulls fresh /disruptions for nearby hazards, and compares against planned delivery windows from /freight-rates. If high-severity risk is detected, create a ticket with pre-filled exception narrative and suggested remediation steps. Endpoints used: /disruptions, /freight-rates.

Performance Tips and Integration Patterns

Frequently Asked Questions

How often do FreightPulse fuel prices update?

Fuel prices reflect EIA updates and include national averages plus PADD region breakdowns. We also provide historical bands (30d, 90d, YoY) so you can narrate trends alongside your FSC formula and show how current values compare to rolling norms.

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

Yes. The /carriers endpoint supports trucking (FMCSA SAFER) and ocean NVOCC/OTI lookups (FMC directory) via the type parameter. For trucking, query by DOT or name; for ocean, use organization numbers or names to validate partners.

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

No. Congestion is an approximation based on IMF PortWatch AIS-derived portcalls and is reported as a 7-day average relative to a 90-day baseline. The data is lagged by roughly 6–7 days, making it ideal for trend analysis and expectation-setting—not live queue monitoring.

Can I filter disruption alerts by proximity to a specific port?

Yes. Use the port parameter on /disruptions to return events within a fixed radius around a port (300 km globally, 100 km for US weather). This enables targeted, shipment-relevant risk narratives that your CS team can present proactively.

What’s the response contract for errors, and how should I handle them?

Every response includes a top-level success flag. If success=false, the body includes an error message. Implement retries with exponential backoff for transient issues and serve cached data gracefully where appropriate to keep your customer pages responsive.

Conclusion + Call to Action

Real-time customer-facing ETAs aren’t just about speed—they’re about context. When you combine a precise delivery window with a clear exception narrative and data-backed cost explanation, your customer success team moves from defensive firefighting to proactive trust-building. That’s how you reduce churn, accelerate issue resolution, and turn your portal into the single source of truth your shippers prefer.

With FreightPulse, you don’t need to wire five different feeds, normalize their shapes, and maintain brittle adapters. You can fetch diesel indices, live FTL transit windows, disruption alerts near critical ports, congestion trends, and carrier verifications from one consistent REST interface, with fields designed for production-grade SLAs, dashboards, and audit trails. It’s the fastest path from prototype to a customer-facing experience your team can stand behind.

If you’re ready to deliver ETAs and exception narratives that earn trust, explore the endpoints in this post and start integrating them into your quoting, tracking, and CS playbooks today. Visit FreightPulse to learn more, and Try FreightPulse for free to build your first customer-facing ETA widget with disruption-aware narratives and transparent surcharge explanations.