Home → Blog

Your analysts and procurement leaders are asking for “real-time carrier scorecards” that combine live truckload rates, carrier safety status, fuel costs, port risk, and nearby disruption alerts—without five vendors and a fragile data pipeline. By the end of this post, you’ll be able to stream those inputs from a single REST API and render an executive dashboard that updates continuously, using FreightPulse.

Introduction

Carrier decisions happen under time pressure: lane quotes change by the hour, fuel surcharges swing weekly, port conditions shift with regional congestion, and a weather system near a gateway can invalidate last week’s bid assumptions. Yet the data to power these decisions is usually scattered across separate systems and formats.

This post walks through an end-to-end pattern for building real-time carrier scorecards for market analysts and procurement teams. We’ll use FreightPulse to consolidate five sources—fuel prices, FTL freight quotes, port congestion, carrier verification, and natural-disruption alerts—behind one API and consistent JSON. You’ll see how to query each feed, interpret the fields that matter for scorecards, and stitch them into a dashboard that executives can trust.

The goal is speed to production. We’ll stick to practical code and concrete responses so you can copy, adapt, and ship.

Why FreightPulse

Quick Start

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

Authentication: Use the X-API-Key header. Unauthenticated requests are allowed within a small quota per IP, suitable for quick testing. All responses share the same envelope: {"success":true/false,"data":{...},"error":"message" // if success=false}.

First request: national and regional EIA fuel prices. Units are per gallon, currency USD.

cURL

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

JSON response (illustrative values from the documented format):

{
"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 for a scorecard: data.diesel.national_average (USD/gal), data.diesel.regions[region] for PADD-aligned context, and data.diesel.historical.* for trend arrows. Use timestamp (UTC) to drive cache invalidation and display freshness.

JavaScript example (fetch fuel prices and compute a weekly diesel delta):

async function fetchFuel() {
const res = await fetch("https://freightpulsehq.com/api/v1/fuel-prices", {
headers: { "X-API-Key": "YOUR_API_KEY" }
});
const body = await res.json();
if (!body.success) throw new Error(body.error || "API error");
const diesel = body.data.data.diesel;
return {
timestamp: body.data.timestamp,
nationalAvg: diesel.national_average,
weeklyDelta: diesel.change_week,
percentDelta: diesel.change_percent
};
}

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

Core Endpoints

1) Carrier verification (/carriers)

Use this to populate the trust and compliance slice of your scorecard: carrier status, safety rating, and driver count. This endpoint queries FMCSA SAFER for US trucking carriers by DOT number or name. Ocean lookups use the FMC directory. Air returns available:false.

Endpoint: GET /carriers

Key params:

cURL

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

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

What to show on the scorecard: legal_name, status, safety_rating, drivers. For ocean vetting, call with type=ocean and q set to the org number or name.

2) Live US FTL rate quotes (/freight-rates)

Feed your lane cost section with live trucking rates. Combine with diesel benchmarks to normalize rates by fuel exposure.

Endpoint: GET /freight-rates

Key params for trucking:

cURL

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

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

Fields to plot: price_usd for the quote amount and transit_days for an ETA expectation. If required params are missing, this endpoint returns HTTP 200 with available: false (not an error), so code defensively to detect availability.

3) Fuel cost benchmarks (/fuel-prices)

Use fuel benchmarks to calibrate fuel surcharges on quotes and to add a macro cost context to carrier performance. Values are USD per gallon and timestamped in UTC.

Endpoint: GET /fuel-prices

Key params: none

cURL

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

Important fields: data.diesel.national_average, data.diesel.regions.*, data.diesel.historical.{30d_avg,90d_avg,yoy_change_percent}. Use historical averages to smooth weekly volatility in your executive charts.

4) Port congestion signal (/port-congestion)

When your carrier or lane touches a gateway, this endpoint adds a congestion signal to the scorecard narrative. The metric compares the recent 7-day average portcalls to a 90-day baseline from IMF PortWatch (AIS-derived). Note: data is lagged approximately 6–7 days and is not live AIS tracking.

Endpoint: GET /port-congestion

Key params:

cURL

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

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

Fields to interpret: congestion is a qualitative label for executives; ratio_vs_baseline lets analysts chart severity over time. Always disclose the lag in UI tooltips or footnotes.

5) Natural-disruption alerts (/disruptions)

Augment carrier scorecards with forward-looking risk: cyclones, earthquakes, floods, volcano activity, droughts, wildfires, and severe weather. Filter by port radius to monitor events near a shipment’s gateway. These are natural hazards only.

Endpoint: GET /disruptions

Key params:

cURL

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

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

Use id for deduplication, type/severity for filtering, and starts_at (UTC) for timelines and alerting SLAs.

Real-World Use Cases

Putting It Together: A Minimal Scorecard Data Pull

Below is a small JavaScript sequence that fetches the core inputs for one carrier and lane, suitable for a scorecard card-render. It calls the same endpoints shown above and extracts only what the UI needs.

async function fetchScorecard({ dotNumber, originZip, destinationZip, port }) {
const headers = { "X-API-Key": "YOUR_API_KEY" };

const [carrierRes, fuelRes, rateRes, congRes, disRes] = await Promise.all([
fetch(`https://freightpulsehq.com/api/v1/carriers?q=${encodeURIComponent(dotNumber)}`, { headers }),
fetch("https://freightpulsehq.com/api/v1/fuel-prices", { headers }),
fetch(`https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=${encodeURIComponent(originZip)}&destination_zip=${encodeURIComponent(destinationZip)}`, { headers }),
fetch(`https://freightpulsehq.com/api/v1/port-congestion?port=${encodeURIComponent(port)}`, { headers }),
fetch(`https://freightpulsehq.com/api/v1/disruptions?port=${encodeURIComponent(port)}&severity=high`, { headers })
]);

const [carrier, fuel, rate, congestion, disruptions] = await Promise.all([
carrierRes.json(), fuelRes.json(), rateRes.json(), congRes.json(), disRes.json()
]);

if (!carrier.success) throw new Error(carrier.error || "Carrier lookup error");
if (!fuel.success) throw new Error(fuel.error || "Fuel price error");
if (!rate.success) throw new Error(rate.error || "Rate quote error");
if (!congestion.success) throw new Error(congestion.error || "Port congestion error");
if (!disruptions.success) throw new Error(disruptions.error || "Disruption error");

const c = carrier.data.results[0] || null;
const diesel = fuel.data.data.diesel;
const portRow = (congestion.data.results || [])[0] || null;

return {
carrier: c ? {
dot: c.dot_number,
name: c.legal_name,
status: c.status,
safety: c.safety_rating,
drivers: c.drivers
} : null,
fuel: {
timestamp: fuel.data.timestamp,
dieselNational: diesel.national_average,
weeklyDelta: diesel.change_week
},
rate: {
mode: rate.data.mode,
service: rate.data.service,
priceUsd: rate.data.price_usd,
transitDays: rate.data.transit_days
},
port: portRow ? {
name: portRow.port,
congestion: portRow.congestion,
ratio: portRow.metrics.ratio_vs_baseline,
asOf: portRow.as_of
} : null,
disruptions: disruptions.data.results
};
}

Practical tips:

FAQ

How often do FreightPulse fuel prices update?

The /fuel-prices endpoint aligns to EIA publication cadence and includes a timestamp in UTC. Use that field to control cache and to display the last update time in dashboards or emails.

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

Yes. Use /carriers with type=ocean and q as the organization number or name to query the FMC directory. For US trucking, leave type as the default (trucking) and use a DOT number or name.

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

No. /port-congestion is based on IMF PortWatch AIS-derived activity and reports a 7-day average versus a 90-day baseline with a ~6–7 day lag. Treat it as a directional congestion signal, not live queue lengths.

Can I try the API without configuring authentication?

FreightPulse allows limited unauthenticated requests per IP so you can explore quickly. For production, add the X-API-Key header and implement retry/backoff around 429 rate limits.

What happens if I miss a required parameter?

FreightPulse uses predictable error handling: you’ll receive success=false with an error message for most cases (e.g., 422 on missing q for /carriers). Note that /freight-rates returns HTTP 200 with "available": false when required lane params are missing.

Conclusion + CTA

Executive carrier scorecards have to merge cost, capacity, compliance, and risk in one view. With FreightPulse, you can pull live US FTL quotes, EIA diesel benchmarks, FMCSA/FMC carrier status, port congestion signals, and natural-disruption alerts through one REST API and one response schema—no stitching together separate feeds.

Start by wiring the five endpoints above into your data layer, normalize units and timestamps, and render a compact card per carrier and lane. Add trendlines from /historical where you need context. When you’re ready to ship your dashboard, you’ll have a production-ready pipeline with minimal integration overhead.

Try FreightPulse for free and build your first real-time carrier scorecard in an afternoon.