Home → Blog

You have rich operational data flowing through your platform—loads, carriers, quotes, lane performance—but the “premium” insights customers keep asking for (fuel-surcharge automation, live truckload quotes in context, port congestion signals, carrier safety checks, and disruption alerts near ports) require stitching together five different feeds and vendor contracts. By the end of this post, you’ll be able to ship a production-grade insights module that monetizes logistics data using one consolidated REST API, with copy‑pasteable requests and responses you can wire into dashboards, alerts, and pricing logic.

Introduction

Premium insights products for supply chain users are often blocked by fragmented data plumbing. You need EIA fuel prices for surcharges, live US truckload quotes to signal market tightness, port congestion indicators to warn of slowdowns, carrier compliance checks to reduce risk, and hazard alerts to keep exceptions out of headlines. Each source has its own schema, quota model, and reliability quirks.

FreightPulse consolidates these logistics intelligence feeds behind one API, normalizes responses, and removes the glue work. The result: your team focuses on building revenue‑generating features instead of wrangling vendor SDKs and reconciling units and timestamps.

This tutorial shows how supply chain SaaS platforms and 3PLs can build and monetize a premium insights layer using FreightPulse’s fuel, freight, port, carrier, and disruption endpoints. You’ll see concrete requests, realistic JSON outputs, and patterns for turning them into features your customers will pay for.

Why FreightPulse

Quick Start

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

Authentication: Send your API key in the X-API-Key header (X-API-Key: YOUR_API_KEY). Unauthenticated requests are allowed up to a daily guest quota per IP, so you can try requests immediately.

First request: Pull national and regional fuel prices (EIA), including weekly deltas and historical averages. Currency: USD. Unit: gallon.

cURL

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

JSON response (illustrative values from the documented shape)

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

Field highlights you’ll use: data.diesel.national_average (USD/gallon), data.diesel.change_percent, and data.diesel.regions.* for regionalization. The timestamp is ISO8601 in UTC. For dashboards, cache this response until the next weekly EIA update to minimize calls.

JavaScript example (same endpoint)

async function getFuelPrices() {
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 || "Request failed");

const diesel = body.data.data.diesel;
const national = diesel.national_average; // USD per gallon
const changePct = diesel.change_percent; // week-over-week %
const westCoast = diesel.regions.west_coast; // USD per gallon

return { national, changePct, westCoast };
}

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

Core Endpoints

1) Fuel prices for surcharges and cost baselining

Endpoint: GET /fuel-prices

Key params: none. Response includes national diesel/gasoline averages, regional PADD breakdowns, and short historical context.

Use it to: drive weekly fuel surcharge tables, annotate TMS cost widgets, or show regional diesel variance in carrier portals.

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

Important fields:

2) Live US FTL freight quotes to price and benchmark lanes

Endpoint: GET /freight-rates

Key params: mode (trucking default), origin_zip (required for trucking), destination_zip (required for trucking). Optional: pickup_date, qty, total_weight_lb. Ocean/air modes exist with different params, but focus on US trucking quotes here.

Use it to: show “market quote now” widgets inside your lane page, build index-based surcharges, or compare your contracted rates to a live market touchpoint.

curl -H "X-API-Key: YOUR_API_KEY" "https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=10001&destination_zip=90210"
{
"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 highlights: data.price_usd (market anchor for pricing), data.transit_days (set customer expectations), and pickup/delivery dates where provided. If you omit required params, you’ll receive HTTP 200 with available: false instead of an error—handle that gracefully in UI state.

3) Port congestion for planning and ETA risk scoring

Endpoint: GET /port-congestion

Key params: port (name or LOCODE like USLAX), or country, or region. Optional: congestion (low|moderate|high) to filter results.

Important: This is a lagged approximation, derived from a 7‑day average of port calls vs a 90‑day baseline. Data is delayed ~6–7 days; it is not real‑time AIS tracking. Use it for trend and planning, not minute‑by‑minute berth wait times.

curl -H "X-API-Key: YOUR_API_KEY" "https://freightpulsehq.com/api/v1/port-congestion?port=USLAX"
{
"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 highlights: results[].congestion (categorical), metrics.ratio_vs_baseline (useful for trend charts and alerts), and as_of (staleness indicator). For a premium dashboard, also pull historical series via /historical to render a time chart.

4) Carrier verification to reduce risk in tendering

Endpoint: GET /carriers

Key params: q (required), type (trucking default | ocean | air). Trucking queries FMCSA SAFER; ocean queries FMC NVOCC/OTI directory; air currently returns available:false.

Use it to: vet carriers at tender time, display safety and driver counts in booking flows, and avoid non‑compliant moves.

curl -H "X-API-Key: YOUR_API_KEY" "https://freightpulsehq.com/api/v1/carriers?q=54283"
{
"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 highlights: results[].status, safety_rating, drivers, and DOT number for linking to internal policies and audit logs.

5) Disruption monitoring near ports

Endpoint: GET /disruptions

Key params: type (cyclone|earthquake|flood|volcano|drought|wildfire|severe_weather), severity (low|moderate|high), country, port (filters by distance: 300 km; for US weather, 100 km). This feed focuses on natural hazards only—no labor strikes or geopolitical events.

Use it to: alert customers when a cyclone or severe weather is approaching a relevant port, or flag shipments for manual review.

curl -H "X-API-Key: YOUR_API_KEY" "https://freightpulsehq.com/api/v1/disruptions?port=USLAX&severity=high"
{
"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 highlights: results[].type, severity, starts_at (ISO8601), and port‑filtered targeting to limit noisy alerts.

Real-World Use Cases

Practical integration notes

End-to-end example: Build a “Lane Insights” panel

This pattern combines three endpoints into one monetizable panel tied to a lane (e.g., 10001 → 90210):

  1. Market quote: Call /freight-rates with origin_zip and destination_zip to show price_usd and transit_days.
  2. Fuel context: Call /fuel-prices to compute a surcharge and show week-over-week change_percent for operator context.
  3. Ocean risk context: If the lane connects to a coastal delivery, query /port-congestion on the relevant port and surface congestion with ratio_vs_baseline.

Because all three calls share the same authentication and response wrapping, you can standardize your HTTP client and telemetry around one library, reducing maintenance and enabling faster iteration.

FAQ

How often do FreightPulse fuel prices update?

The /fuel-prices endpoint reflects EIA weekly updates. The response includes an ISO8601 timestamp; cache the result and refresh on a weekly cadence or when the timestamp changes.

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

Yes. Use /carriers with type=ocean to query the FMC NVOCC/OTI directory by organization number or name. Trucking (default) queries FMCSA SAFER by DOT number or name. Air currently returns available:false.

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

No. /port-congestion is a lagged approximation derived from a 7‑day average of port calls compared to a 90‑day baseline, with about a 6–7 day delay. It’s ideal for trend analysis and planning, not for live berth or anchorage wait times.

Can I try the API without creating an account?

Yes. Guest access is available without an API key up to a small daily quota per IP, which is useful for exploration and prototyping requests.

What’s the response format across endpoints?

All endpoints return the same wrapper: {"success": true/false, "data": {...}}. On errors, you get {"success": false, "error": "Human-readable message."}. This consistency makes it straightforward to centralize error handling.

Conclusion + CTA

You can deliver a premium insights layer—fuel surcharges, live lane quotes, port congestion trends, carrier vetting, and disruption alerts—without five separate integrations. Consolidate your data plumbing with FreightPulse, ship faster, and focus on features customers will pay for. Try FreightPulse for free and wire the endpoints above into your next release today.