Home → Blog

Building lane-level demand forecasts and making confident capacity commitments is hard when your signals are scattered. Truckload quotes live in one tool, diesel prices in another, port congestion in a third, and disruption alerts yet somewhere else. Forecasts get stale before they’re even reviewed, and capacity teams either overcommit (and eat margin) or undercommit (and lose freight).

In this post, we’ll walk through how to use FreightPulse event streams and endpoints to build production-ready lane forecasts and capacity commitments. We’ll cover how to turn live US full‑truckload (FTL) quotes, historical fuel price series, port congestion trends, carrier verification, and natural-hazard alerts into a single operational picture your planners and TMS can trust—without stitching together five different feeds. We’ll go deep on endpoint usage, interpretation tips, and practical patterns like retries, circuit breakers, and observability that keep your forecasting pipeline resilient.

By the end, you’ll have a blueprint for an end-to-end workflow: ingest FreightPulse data, engineer lane features, project demand and rate pressure, and trigger capacity commitments with confidence. You’ll see complete cURL and code examples, JSON response walk-throughs, and implementation guidance for real-world deployment across freight forwarders, 3PLs, and enterprise logistics teams.

Why FreightPulse

FreightPulse consolidates the logistics intelligence you actually need to forecast, price, and commit—EIA fuel prices, live US FTL quotes, IMF PortWatch congestion, FMCSA/FMC carrier verification, and natural-hazard alerts—behind a single, consistent JSON API. The net effect is fewer integrations, less engineering overhead, and faster iteration from idea to production.

Quick Start

The FreightPulse base URL is:

https://freightpulsehq.com/api/v1

Let’s begin with a simple request to pull national diesel and gasoline prices plus PADD-region breakdowns. This establishes your baseline fuel signal for surcharge models and cost normalization in your lane forecasts. 

curl "https://freightpulsehq.com/api/v1/fuel-prices"

A representative 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 for Lane-Level Forecasts and Capacity Commitments

A robust demand and capacity system needs pricing, congestion context, carrier trust, and disruption awareness. Below we cover the endpoints most relevant to forecasting and commitment logic, with example cURL calls, complete JSON responses, and guidance on using each field in your models and workflows.

1) Live Freight Quotes: GET /freight-rates

Purpose: Retrieve live US FTL truckload quotes for specific lanes. These quotes, paired with fuel and congestion signals, shape your near-term rate expectations and win-rate strategies for spot and mini-bids. Ocean/air modes are available for select lanes and can inform intermodal planning into US ZIPs.

Key parameters: 

curl "https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=10001&destination_zip=90210&pickup_date=2026-08-24&total_weight_lb=40000"

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

How to use:

Notes:

2) Fuel Baseline and Trend: GET /fuel-prices and GET /historical

Purpose: Model your cost floor and fuel surcharge logic. Fuel spikes often precede or coincide with quote volatility, especially in long-haul dry van and reefer. Combining current prices with recent historical series improves forecast stability and alerting sensitivity.

GET /fuel-prices is shown in Quick Start. For time-series features (e.g., trend acceleration or rolling z-scores), pull historical series: 

curl "https://freightpulsehq.com/api/v1/historical?metric=fuel_price_diesel_national&period=90d"

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

How to use:

3) Congestion Context: GET /port-congestion

Purpose: Understand port-level activity pressure that can propagate into inland capacity tightness (especially transload-heavy markets like LA/LB into Inland Empire). The endpoint reports a 7‑day average of port calls vs a 90‑day baseline using IMF PortWatch (AIS-derived) data. Note: This is a lagged approximation with ~6–7 days of delay; it is not live AIS tracking or real-time vessel wait times.

Key parameters: 

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

How to use:

4) Carrier Verification: GET /carriers

Purpose: Verify carriers you plan to award lane commitments to. For US trucking, use FMCSA SAFER lookups; for ocean, use FMC NVOCC/OTI directory. This reduces fraud risk and helps your procurement team set filters (e.g., minimum safety rating or driver count thresholds).

Key parameters: 

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

How to use:

5) Disruption Awareness: GET /disruptions

Purpose: Detect cyclones, earthquakes, floods, wildfires, volcano events, drought, and severe weather that could affect origin/destination lanes or ports. Filter by port radius or country and feed your risk engine to adjust forecasts, surge pricing, or capacity rebalancing.

Key parameters: 

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

How to use:

Error Handling and Common Patterns

All responses conform to a common shape. On error, you’ll receive a structure with success=false and an error message. Your client can centralize parsing and instrumentation. 

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

Best practices:

Designing a Lane-Level Demand Forecast with FreightPulse Signals

Lane-level forecasting benefits from combining rate, cost, congestion, and hazard features. Here’s a practical approach to building a feature set and connecting it to capacity decisions.

Modeling tips:

End-to-End Example: Python Feature Ingestion and Signal Fusion

Below is a compact Python sketch showing how to pull several FreightPulse signals and compute simple lane features. You can adapt this into your batch jobs, airflow DAGs, or microservices. 

import requests
import statistics
from datetime import date

BASE = "https://freightpulsehq.com/api/v1"

def get_json(url):
r = requests.get(url, timeout=15)
r.raise_for_status()
return r.json()

def fuel_signals():
fp = get_json(f"{BASE}/fuel-prices")
diesel_now = fp["data"]["data"]["diesel"]["national_average"]
diesel_30 = fp["data"]["data"]["diesel"]["historical"]["30d_avg"]
diesel_90 = fp["data"]["data"]["diesel"]["historical"]["90d_avg"]
return {
"diesel_now": diesel_now,
"diesel_30d_avg": diesel_30,
"diesel_90d_avg": diesel_90
}

def lane_quote(origin_zip, destination_zip, pickup=None):
url = f"{BASE}/freight-rates?mode=trucking&origin_zip={origin_zip}&destination_zip={destination_zip}"
if pickup:
url += f"&pickup_date={pickup}"
data = get_json(url)
return data["data"]

def port_context(port_code="USLAX"):
pc = get_json(f"{BASE}/port-congestion?port={port_code}")
if pc["data"]["results"]:
m = pc["data"]["results"][0]["metrics"]
return {
"ratio_vs_baseline": m["ratio_vs_baseline"],
"recent_avg": m["recent_avg_portcalls_per_day"],
"baseline_avg": m["baseline_avg_portcalls_per_day"]
}
return {}

def hazard_near_port(port_code="USLAX", severity="high"):
hz = get_json(f"{BASE}/disruptions?port={port_code}&severity={severity}")
return len(hz["data"]["results"])

def compute_features(origin, dest, port="USLAX"):
fuel = fuel_signals()
quote = lane_quote(origin, dest, pickup=str(date.today()))
portc = port_context(port)
hazards = hazard_near_port(port)

price = quote["price_usd"]
fuel_adj_price = price / max(fuel["diesel_now"], 1e-6)

return {
"price_usd": price,
"transit_days": quote.get("transit_days"),
"fuel_now": fuel["diesel_now"],
"fuel_adj_price": round(fuel_adj_price, 2),
"port_ratio": portc.get("ratio_vs_baseline"),
"hazard_events": hazards
}

print(compute_features("10001", "90210", "USLAX"))

What this provides:

Operations-Grade Practices: Reliability, Governance, and Performance

Production forecasting and capacity systems must be resilient. The following patterns help you run FreightPulse integrations with confidence.

Real-World Use Cases

Fuel Surcharge Calculator for TMS Rating

Use /fuel-prices to fetch the current national diesel and regional basis. Pair with /historical to compute 30/90-day anchors. The calculator outputs a fuel surcharge per mile for each lane and updates nightly. Operators see transparent, auditable adjustments aligned with market movements. Endpoints used: GET /fuel-prices, GET /historical.

Port-Congestion Dashboard for Coastal Imports

A forwarder builds a dashboard that visualizes /port-congestion across major US ports, overlaid with /disruptions filtered by port radius. Planners quickly explain demand surges or dips on related inland lanes and pre-stage capacity before the next wave hits. Endpoints used: GET /port-congestion, GET /disruptions.

Carrier Vetting and Auto-Award

A 3PL integrates /carriers into its TMS to verify FMCSA SAFER status and a minimum safety rating before auto-awarding tenders. Coupled with /freight-rates, the engine selects a carrier pool with verified credentials and competitive quotes. Endpoints used: GET /carriers, GET /freight-rates.

Lane-Level Demand Forecast and Capacity Commitments

A supply chain team ingests /freight-rates daily for its top 500 lanes, normalizes with /fuel-prices, applies congestion context from /port-congestion, and overlays hazard alerts from /disruptions. The forecast flags the top 10 tightening lanes by week, triggering pre-committed capacity blocks with vetted carriers via /carriers verification checks. Endpoints used: GET /freight-rates, GET /fuel-prices, GET /port-congestion, GET /disruptions, GET /carriers.

Exception Monitoring and Risk Alerts

An operations control tower subscribes to periodic pulls of /disruptions and changes in /freight-rates for active shipments’ lanes. Significant deviations trigger notifications to planners with direct links to re-quote options and dynamic rerouting. Endpoints used: GET /disruptions, GET /freight-rates.

Additional Code Examples: JavaScript Fetch for Front-End Dashboards

Front-end teams can query FreightPulse directly from server-side rendered routes or from back-end-for-front-end (BFF) layers. Here is a minimal Node/SSR-friendly example. 

async function getJson(url) {
const r = await fetch(url, { method: "GET" });
if (!r.ok) throw new Error(`HTTP ${r.status}`);
return await r.json();
}

async function getLaneSnapshot(origin, dest) {
const base = "https://freightpulsehq.com/api/v1";
const [rates, fuel, cong] = await Promise.all([
getJson(`${base}/freight-rates?mode=trucking&origin_zip=${origin}&destination_zip=${dest}`),
getJson(`${base}/fuel-prices`),
getJson(`${base}/port-congestion?port=USLAX`)
]);

const price = rates.data.price_usd;
const dieselNow = fuel.data.data.diesel.national_average;
const ratio = cong.data.results?.[0]?.metrics?.ratio_vs_baseline ?? null;

return {
priceUsd: price,
dieselNow,
fuelAdjusted: price / Math.max(dieselNow, 1e-6),
laPortRatio: ratio
};
}

getLaneSnapshot("10001", "90210").then(console.log).catch(console.error);

In a dashboard, you’d render priceUsd and fuelAdjusted side-by-side for quick interpretation, along with laPortRatio to explain why Southern California outbound may be tightening or loosening.

Field-by-Field Interpretation Guide

This section summarizes the most decision-relevant fields and how they map to business logic.

Putting It Together: A Capacity Commitment Playbook

Here’s a practical playbook to move from signals to capacity commitments while protecting margin and service:

  1. Daily signal refresh
    • Pull top-lane /freight-rates, current /fuel-prices, /disruptions filtered by relevant ports/states, and the latest /port-congestion snapshots.
    • Normalize prices by diesel; compute deltas vs 7/14-day rolling medians; attach congestion ratio and hazard counts.
  2. Forecast and flag
    • Run a 7–14 day lane-level forecast. Flag lanes with price-adjusted tightness above a threshold (e.g., top decile of combined pressure index).
    • Generate P50 and P90 rates for decision envelopes; use P90 for conservative awards on volatile lanes.
  3. Carrier screening
    • For flagged lanes, fetch /carriers by DOT/name to confirm active status and acceptable safety rating. Create a vetted shortlist.
  4. Pre-commit blocks
    • Allocate capacity blocks to vetted carriers at target rates derived from quantile forecasts, accounting for fuel escalators and expected congestion impacts.
    • Set time-boxed options (e.g., holds that expire if signals soften), and monitor actuals vs expected.
  5. Feedback loop
    • Track award acceptance, service levels, and realized costs. Recalibrate features and thresholds weekly; update alerting on hazard proximity and port shifts.

Additional Endpoint Examples and Best Practices

Example: Ocean Inbound Signal for Intermodal Planning

While trucking is the primary mode for lane-level FTL forecasts, mixing ocean inbound context can improve planning for coastal markets. 

curl "https://freightpulsehq.com/api/v1/freight-rates?mode=ocean&origin_country=CN&dest_zip=90745&container_size=40HC"

{
"success": true,
"data": {
"mode": "ocean",
"service": "FCL 40HC",
"source": "Warp",
"price_usd": 3825.50,
"transit_days": 14,
"pickup_date": "2026-08-24",
"delivery_date": "2026-09-07"
}
}

Pair this with /port-congestion for LA/LB and hazard alerts to anticipate transload surges pushing linehaul demand inland.

Error Example: Missing Parameter on /carriers

Your client should anticipate 422 for missing required parameters and gracefully display actionable error messages to operators. 

{
"success": false,
"error": "Missing required parameter: q"
}

Recommendation: Centralize request validation client-side to avoid unnecessary round-trips.

FAQ

How often do FreightPulse fuel prices update?

Fuel prices reflect EIA data and include current national averages plus PADD-region breakdowns, along with recent historical averages for 30/90-day windows. Treat weekly changes as your primary short-horizon signal and use the historical fields to stabilize surcharges and forecasts.

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

Yes. The /carriers endpoint supports US trucking lookups (FMCSA SAFER) and ocean NVOCC/OTI lookups (FMC directory). Use the type parameter to switch between trucking and ocean searches.

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

No. Port congestion is a lagged approximation derived from IMF PortWatch AIS data. It reports a 7-day average versus a 90-day baseline with roughly a 6–7 day delay. Use it for trend context and pair with /disruptions for more immediate signals.

Can I get live US FTL quotes for specific lanes?

Yes. Use /freight-rates with mode=trucking and pass origin_zip and destination_zip to retrieve live quotes, transit days, and delivery windows. Combine with /fuel-prices and /port-congestion to inform pricing and capacity decisions.

How should I handle errors and ensure reliable ingestion?

Implement centralized parsing of the common response envelope, retries with exponential backoff, circuit breakers for repeated failures, and observability (latency, success flags, and per-lane metrics). Cache slower-moving data like weekly fuel series and lagged congestion to improve responsiveness.

Conclusion + CTA

Lane-level demand forecasting and capacity commitments succeed when your signals are fresh, aligned, and interpretable. With live US FTL quotes, fuel baselines, lagged port congestion context, carrier verification, and hazard alerts all in one place, FreightPulse accelerates your path from prototype to production—and gives planners the confidence to pre-commit capacity where it matters most.

Instead of wrestling five separate integrations and reconciling mismatched schemas, treat FreightPulse as your logistics intelligence backbone. Build clearer forecasts, explain variance with grounded context, and automate the bridge from model insight to operational commitment.

Start building today with FreightPulse. Explore the endpoints, wire them into your TMS, and stand up a lane forecast that your operators will actually use. Ready to go? Try FreightPulse for free.