Home → Blog

In this playbook, we will walk through how 3PL providers can leverage lane-level data from FreightPulse to forecast capacity and optimize network planning. The core challenge is familiar: capacity volatility and cost swings across lanes create frequent fire drills. Teams stitch together EIA fuel datasets for surcharge baselines, query multiple freight rate sources for spot checks, scan port data to estimate downstream drayage congestion, verify carriers across databases, and monitor weather and seismic alerts from yet another set of feeds. Doing any of this manually (or via brittle scrapers) doesn’t scale—and it often breaks during peak season, exactly when you need it most.

A second, related problem is data latency and model drift in analytics pipelines. Even if you’ve built a robust internal data lake, you still need clean, standardized inputs for live US FTL quotes, fuel price curves, port congestion trends, and disruption alerts. Training a forecasting model on stale or mismatched data sources yields poor fits and spurious recommendations: you forecast ample capacity on a Transcon lane because your model didn’t ingest last week’s typhoon that stalled drayage at the West Coast. The solution is not “more data” but “the right data, standardized, and delivered consistently.” That is the operational gap this post addresses.

FreightPulse consolidates the critical logistics signals—EIA fuel prices, live US full-truckload (FTL) quotes, IMF PortWatch congestion approximations, FMCSA/FMC carrier lookups, and natural-disruption alerts—behind one REST API. For 3PL network planners, analysts, and platform teams, this means you can iterate faster on lane-level capacity forecasting, reduce integration surface area, and deploy decision automation with confidence. Below, we will show a practical path from zero to production: pulling data, interpreting the fields correctly, and wiring it into planning tools and alerting systems.

Why FreightPulse

FreightPulse eliminates the “data patchwork” that slows down forecasting tools. Instead of juggling five different providers and schemas, you pull unified JSON from one source. Here are the differentiators that matter for developers and operators:

Under the hood, this consolidation unlocks engineering best practices you already use elsewhere: standardized observability (the same success/data/error envelope for all endpoints), graceful fallback strategies (e.g., to historical series if a real-time quote is temporarily unavailable), and governance-friendly controls over who consumes which signal in which environment. With a single REST surface, you can instrument retries, circuit breakers, health checks, and structured logs uniformly across your stack.

Quick Start

The base URL for all requests is:

https://freightpulsehq.com/api/v1

Let’s start with a simple call to the national fuel price endpoint and inspect the response. You can run this directly in your terminal: 

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

A successful response returns a standardized JSON envelope with the key data payload: 

{
"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 to note:

This one call demonstrates why unification matters: you get a clean JSON schema, consistent source annotation, and fields crafted for logistics use cases. We’ll now build on this foundation and pull lane-level signals for forecasting.

Core Endpoints for Lane-Level Capacity Forecasting

/freight-rates — Live US FTL quotes for lanes

Purpose: Fetch spot-like live quotes for US trucking lanes (via Warp), including service, price, and transit days. Use this to measure current market tension and calibrate your lane-level capacity score. Combining this with historical diesel and port context yields a richer forecasting signal than rates alone.

Key params:

Example request: 

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

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 guide:

Notes:

/port-congestion — Maritime activity approximations for drayage and inland planning

Purpose: Estimate port activity levels using IMF PortWatch data (derived from AIS) as a ratio of recent 7-day average port calls versus a 90-day baseline. This is not real-time vessel wait time. It’s a lagged (approximately 6–7 days) approximation designed for trend analysis—perfect for predicting how maritime bottlenecks might propagate into drayage and inland TL capacity and pricing over the following weeks.

Key params:

Example request: 

curl "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 guide:

Best practices:

/disruptions — Natural-hazard alerts for proactive re-routing

Purpose: Consolidate natural hazards (cyclones, earthquakes, severe weather, and more) from GDACS, USGS, and NOAA/NWS. Use this feed to protect loads and to forecast temporary capacity shocks (e.g., winter storms in the Midwest tightening TL capacity quickly).

Key params:

Example request: 

curl "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 guide:

/carriers — FMCSA and FMC verification to de-risk procurement

Purpose: Lookup US trucking carriers (FMCSA SAFER) by DOT number or name, and ocean NVOCC/OTI carriers (FMC) by org number or name. This enables automated compliance checks and supply base expansion without manual directory lookups.

Key params:

Example request (trucking): 

curl "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 guide:

/fuel-prices — Surcharge calculators and modeling features

Purpose: Retrieve diesel and gasoline price levels nationally and by region, plus rolling averages and YoY changes. For TL forecasting, diesel is the key exogenous feature feeding both surcharge models and expected future rate bands.

Key params: None required.

Example request: 

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

We saw the response structure earlier. Use diesel.national_average for standard FSC baselines; regions when you localize surcharge assumptions; and historical averages to construct lagged features. You can also fetch time series via /historical for model training.

/historical — Baselines for modeling and backtests

Purpose: Fetch historical time series for national fuel prices and daily port-congestion approximations across curated major ports. Historical series are the canonical inputs for training and validating forecasting models without building your own crawlers.

Key params:

Example request (diesel series): 

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

Example request (port congestion series for Los Angeles–Long Beach, if supported as a curated metric id): 

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

Interpretation tips:

End-to-End Examples: cURL, Python, and JavaScript

Below are minimal code samples that fetch lane-level signals and prepare them for capacity scoring. These are intentionally concise so you can slot them into schedulers, serverless tasks, or microservices.

Example: Fetch a live TL quote and combine with fuel price and port congestion context (cURL only). 

# 1) Live FTL quote for lane 10001 -> 90210
curl "https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=10001&destination_zip=90210"

# 2) Fuel prices (national + regions)
curl "https://freightpulsehq.com/api/v1/fuel-prices"

# 3) Port congestion near LA/LB
curl "https://freightpulsehq.com/api/v1/port-congestion?port=USLAX"

Example: Python script to fetch disruptions near a port and score risk for loads set to pass through that node. 

import json
import time
import requests

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

def get_disruptions(port, severity="moderate"):
url = f"{BASE}/disruptions?port={port}&severity={severity}"
r = requests.get(url, timeout=10)
payload = r.json()
if not payload.get("success"):
raise RuntimeError(payload.get("error", "Unknown error"))
return payload["data"]["results"]

def score_risk(disruptions):
# Simple heuristic: more events and higher severities raise risk
weights = {"low": 0.3, "moderate": 0.6, "high": 1.0}
score = 0.0
for ev in disruptions:
sev = ev.get("severity", "low")
score += weights.get(sev, 0.3)
return min(score, 3.0)

if __name__ == "__main__":
events = get_disruptions("USLAX", severity="moderate")
risk = score_risk(events)
print(json.dumps({"port": "USLAX", "events": events, "risk_score": risk}, indent=2))

Example: JavaScript (Node) fetching historical diesel data to compute a 4-week moving average. 

import https from "https";

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

function fetchJSON(path) {
return new Promise((resolve, reject) => {
https.get(`${BASE}${path}`, (res) => {
let data = "";
res.on("data", (chunk) => data += chunk);
res.on("end", () => {
try { resolve(JSON.parse(data)); }
catch (e) { reject(e); }
});
}).on("error", reject);
});
}

function movingAverage(values, window) {
const out = [];
for (let i = 0; i < values.length; i++) {
const start = Math.max(0, i - window + 1);
const slice = values.slice(start, i + 1);
const avg = slice.reduce((a, b) => a + b, 0) / slice.length;
out.push(avg);
}
return out;
}

(async () => {
const resp = await fetchJSON("/historical?metric=fuel_price_diesel_national&period=1y");
if (!resp.success) throw new Error(resp.error || "Unknown error");
const series = resp.data.series || [];
const values = series.map(p => p.value);
const ma4 = movingAverage(values, 4);
console.log(JSON.stringify({ size: series.length, ma4_last: ma4[ma4.length - 1] }, null, 2));
})();

Designing a Lane-Level Capacity Forecast with FreightPulse

A practical capacity forecast combines exogenous signals (fuel, port trends, disruptions) and endogenous signals (live rates, transit times drift) aligned to a lane entity. Here’s a high-level approach:

  1. Define lanes and their port catchment: E.g., if a lane historically serves drayage and inland moves tied to LA/LB, associate it with USLAX for maritime context.
  2. Ingest time series: Use /historical for fuel and port congestion; persist responses daily for backtests.
  3. Add live snapshots: Poll /freight-rates on a cadence (e.g., hourly or daily) for representative OD pairs to capture current pricing pressure and transit day drift.
  4. Overlay disruptions: Subscribe to /disruptions around critical ports and weather-prone regions; transform into binary or graded features by severity.
  5. Model and thresholds: Fit a regression or gradient boosting model that outputs a capacity tightness score (e.g., 0–100). Drive playbooks: advance tendering, carrier diversification, dynamic surcharge policy, or pre-allocations per lane.

This entire loop runs on a single API surface and a shared JSON envelope, simplifying observability and operational controls. You can implement retries with exponential backoff uniformly, apply circuit breakers on a per-endpoint basis, and export standardized logs for audits and root-cause analysis.

Reliability, Observability, and Governance Best Practices

When you consolidate multiple logistics signals behind a single REST surface, you can apply platform patterns that raise reliability and speed up debugging:

These patterns help keep your lane-level capacity forecasts resilient during peak (when disruptions and maritime shifts are common) and transparent to auditors and leadership.

Error Handling and Troubleshooting Guidance

FreightPulse returns a standardized envelope across endpoints, which simplifies error handling:

Common scenarios:

Debug tips:

Real-World Use Cases for 3PLs and Network Planners

Fuel surcharge calculator with forecasting:

Port-congestion dashboard for drayage and inland planning:

Carrier vetting and tender automation:

Disruption-aware shipment tracker:

Lane-level capacity forecast and auto-tendering thresholds:

Deep Dive: Field-by-Field Interpretation Across Endpoints

It’s worth reiterating the most decision-critical fields and how to use them:

Performance Tips and Client Patterns

Additional Example Responses and Usage Notes

Here are more full JSON examples to help you validate parsing logic across multiple endpoints.

Freight rates with optional params (illustrative): 

{
"success": true,
"data": {
"mode": "trucking",
"service": "FTL (53' dry van)",
"source": "Warp",
"price_usd": 4235.50,
"transit_days": 3,
"pickup_date": "2026-09-02",
"delivery_date": "2026-09-05"
}
}

Port congestion filtered by region (illustrative multi-result shape): 

{
"success": true,
"data": {
"results": [
{
"port": "Port of Shanghai",
"locode": "CN SHA",
"country": "China",
"congestion": "high",
"as_of": "2026-08-14",
"metrics": {
"recent_avg_portcalls_per_day": 12.1,
"baseline_avg_portcalls_per_day": 10.9,
"ratio_vs_baseline": 1.11
}
},
{
"port": "Singapore",
"locode": "SG SIN",
"country": "Singapore",
"congestion": "moderate",
"as_of": "2026-08-14",
"metrics": {
"recent_avg_portcalls_per_day": 15.4,
"baseline_avg_portcalls_per_day": 16.2,
"ratio_vs_baseline": 0.95
}
}
]
}
}

Disruptions filtered by type (wildfire, illustrative): 

{
"success": true,
"data": {
"results": [
{
"id": "usgs:WF:789123",
"type": "wildfire",
"severity": "high",
"title": "Wildfire Event - Northern California",
"country": "United States",
"starts_at": "2026-08-21T03:00:00+00:00",
"source": "NOAA/NWS"
},
{
"id": "gdacs:WF:789124",
"type": "wildfire",
"severity": "moderate",
"title": "Wildfire Event - Southern Oregon",
"country": "United States",
"starts_at": "2026-08-22T10:00:00+00:00",
"source": "GDACS"
}
]
}
}

FAQ

How often do FreightPulse fuel prices update?

Fuel prices track the EIA data cadence, and responses include a timestamp so you can validate freshness. For forecasting and surcharge calculation, schedule a daily pull and persist the values with the provided timestamp to avoid double-counting updates.

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

Yes. The /carriers endpoint supports trucking (FMCSA SAFER) and ocean NVOCC/OTI (FMC) lookups. Use the type parameter to target the dataset that matches your use case; the response remains in the same success/data envelope regardless of type.

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

No. Port congestion data is a lagged approximation (about 6–7 days) using a 7-day average of port calls compared to a 90-day baseline. It’s designed for trend analysis and forecasting, not for minute-by-minute operational dispatch. Use it to anticipate drayage and inland impacts rather than to manage same-day port moves.

What’s the best way to combine live rates and fuel prices in a capacity model?

Start by normalizing live price_usd from /freight-rates with diesel baselines from /fuel-prices or /historical. Residuals beyond what diesel explains often capture network pressure. Add port-congestion ratios and disruption severity to improve early warnings on tightening lanes.

How should I handle missing or partial responses?

Always check the success flag. If false, consult the error field and avoid parsing data. For partial cases like “available”: false on /freight-rates when required params are missing, prompt for corrected inputs and retry. Maintain a small cache of recent valid responses to keep dashboards informative during transient gaps.

Conclusion + CTA

Lane-level capacity forecasting doesn’t fail for lack of ideas; it fails when data pipelines collapse under their own complexity. The fastest path to resilient forecasts is consolidating the inputs that matter—fuel, live rates, port trends, carrier verification, and disruption alerts—behind a single, consistent API. That’s exactly what FreightPulse delivers. With unified JSON responses, lag-aware maritime context, live US FTL quotes, and natural-hazard alerts, you can finally connect maritime signals to inland capacity, ground your surcharge math in reliable data, and automate tendering decisions with confidence.

Whether you are a 3PL building a planning console, a freight forwarder creating a port health dashboard, or a supply chain SaaS platform shipping a new analytics module, you can go from concept to production in days, not months. Start by wiring /freight-rates for lane snapshots, layer in /fuel-prices and /historical for baselines, pull /port-congestion to anticipate drayage-driven shocks, and subscribe to /disruptions to protect active loads. Then operationalize with retries, circuit breakers, and structured observability to keep it humming during peak.

Explore what’s possible with FreightPulse, and put unified logistics intelligence behind your forecasting and planning workflows today. Ready to build? Try FreightPulse for free and start shipping lane-level capacity forecasting that your operators will trust.