Home → Blog

You need current, trustworthy US diesel price data to calculate fuel surcharges, forecast budgets, and explain cost movements to stakeholders—and you don’t want to juggle multiple feeds or scrape PDFs. By the end of this post, you’ll query national and regional diesel prices from a single REST API, plot a short historical series for context, and plug those numbers into a freight-cost workflow alongside live FTL quotes—without wiring up five different data sources.

Introduction

Diesel volatility bleeds straight into transportation budgets. If your TMS, rate engine, or analytics stack isn’t ingesting fresh EIA diesel prices and turning them into fuel surcharges—or explaining week-over-week impacts—then you’re guessing. Even if you have a data source, the plumbing tends to sprawl across separate integrations: one for prices, one for quotes, another for port conditions, and another for disruptions. Every new source means more maintenance and more brittle code.

This post shows how to build a diesel-aware logistics workflow using one API: FreightPulse. You’ll fetch national and PADD-region diesel prices, grab recent history for context, and—if you choose—pull live truckload quotes or factor in lagged port congestion and natural-disruption alerts, all behind the same JSON schema. The goal: production-ready, explainable numbers with minimal integration overhead.

Why FreightPulse

Quick Start

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

Authentication: Send an X-API-Key header. Unauthenticated requests are allowed up to a daily per-IP threshold for exploration. Production systems should include your key in every call.

First request: fetch current EIA diesel and gasoline prices with regional breakdowns.

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

Illustrative JSON response (fields are documented; numeric values below are examples provided by FreightPulse):

{
"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 you’ll likely use:

Core Endpoints

1) /fuel-prices — Weekly EIA diesel/gasoline with PADD regions

Use this endpoint to power fuel surcharge formulas and dashboards. No parameters are required.

Endpoint: GET /fuel-prices

Required params: none

Notes: Values are denominated in USD per gallon. Timestamp is UTC. Update cadence follows EIA’s weekly reporting schedule, and FreightPulse attaches computed deltas and short-term averages to simplify analysis.

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

Response shape (illustrative values as documented above):

{
"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 explanation:

2) /historical — Fuel-price series for trend charts

Build a lightweight trendline or run a moving average without hoarding your own warehouse. You can fetch a 30-day, 90-day, or 1-year span of weekly national fuel price series.

Endpoint: GET /historical

Key params:

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

Response (illustrative values; dates and numbers are representative from the documentation):

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

How to use it:

3) /freight-rates — Live US FTL quotes to pair with surcharges

If your cost model needs both a linehaul quote and a fuel component, you can query a live FTL quote within the same API, then apply your surcharge percentage or per-mile add-on using the numbers you got from /fuel-prices.

Endpoint: GET /freight-rates

Key params for trucking mode:

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

Example response (values illustrative from documentation):

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

Notes:

4) Optional context: /port-congestion (lagged approximation) and /disruptions

While fuel drives baseline cost, schedule risk often comes from congestion and weather. FreightPulse provides a lagged port-congestion approximation and natural-disruption alerts you can query without changing auth or JSON handling patterns.

Endpoint: GET /port-congestion

Key params: port (name or LOCODE like USLAX), country, or region (at least one required). Optional congestion filter.

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

Example response (values illustrative from documentation):

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

Important: This series is an approximation from IMF PortWatch AIS data with a typical 6–7 day lag, computed as a 7-day average versus a 90-day baseline. It is not live AIS tracking and should be used for context and trend, not minute-by-minute queue lengths.

Endpoint: GET /disruptions

Key params: type, severity, country, and port (radius filter: 300km for global hazards; 100km for US weather). Use to flag inbound shipments potentially impacted by cyclones, earthquakes, or severe weather.

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

Example response (illustrative):

{
"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 severity and type to triage which shipments might need contingency routing, safety stock, or revised ETAs.

Python example: fetch diesel and compute a simple surcharge

The snippet below calls /fuel-prices, reads the diesel national average, and computes a basic surcharge as a percentage add-on. Adjust the formula to your carrier contracts.

import requests

API_BASE = "https://freightpulsehq.com/api/v1"
API_KEY = "YOUR_API_KEY" # For exploration, guest requests are allowed up to a daily per-IP threshold.

def get_diesel_price():
r = requests.get(f"{API_BASE}/fuel-prices", headers={"X-API-Key": API_KEY}, timeout=15)
r.raise_for_status()
payload = r.json()
if not payload.get("success"):
raise RuntimeError(payload.get("error", "Unknown error"))
data = payload["data"]["data"]["diesel"]
return {
"timestamp": payload["data"]["timestamp"],
"national": data["national_average"],
"change_week": data.get("change_week"),
"change_percent": data.get("change_percent"),
"regions": data.get("regions", {})
}

def compute_surcharge(linehaul_usd, national_diesel):
# Example: 1.25% surcharge per $0.10 above $2.50 baseline (illustrative rule of thumb).
# Replace with your contract terms. Values are USD per gallon.
baseline = 2.50
step = 0.10
pct_per_step = 0.0125
steps = max(0, int(round((national_diesel - baseline) / step)))
surcharge_pct = steps * pct_per_step
return round(linehaul_usd * surcharge_pct, 2), round(surcharge_pct * 100, 2)

if __name__ == "__main__":
diesel = get_diesel_price()
linehaul = 3200.00 # Example linehaul quote (USD), e.g., from /freight-rates
surcharge_usd, surcharge_pct = compute_surcharge(linehaul, diesel["national"])
print(f"Diesel (USD/gal): {diesel['national']} at {diesel['timestamp']}")
print(f"Surcharge: {surcharge_pct}% = ${surcharge_usd} on a ${linehaul} linehaul")

Operational notes:

Real-World Use Cases

FAQ

How often do FreightPulse fuel prices update?

Fuel prices follow the EIA weekly cadence. The /fuel-prices endpoint returns the current print with a UTC timestamp plus useful deltas (week-over-week change and percent). Cache within the same reporting period to avoid redundant calls.

Can I get a historical series for diesel to draw a chart?

Yes. Use /historical with metric=fuel_price_diesel_national and a period of 30d, 90d, or 1y. You’ll get a compact array of date/value points (USD per gallon) suitable for spark lines or rolling-average comparisons.

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

No. /port-congestion is a lagged approximation from IMF PortWatch AIS data with a typical 6–7 day delay. Results are expressed as a 7-day average versus a 90-day baseline. Use it for context and trend, not live queue monitoring.

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). Set type to trucking or ocean and pass q with a DOT number, organization number, or name.

Do I need an API key to try the endpoints?

You can explore as a guest with a daily per-IP allowance. For production, send the X-API-Key header with your requests. The response envelope is the same in both cases.

Conclusion + CTA

If diesel moves your P&L, your systems should surface it where decisions happen: in quotes, in dashboards, in forecasts. With FreightPulse, you get EIA diesel/gasoline, live US FTL quotes, disruption alerts, carrier lookups, and a lagged port-congestion approximation—through one REST API and a consistent JSON pattern that’s easy to test and deploy.

Start by wiring /fuel-prices into your surcharge function, then add /historical for context and /freight-rates to show an all-in estimate. As you mature, bring in /disruptions and /port-congestion to help stakeholders understand why costs and timings shift. You’ll reduce integration surface area and move from raw data to decisions faster.

FreightPulse is ready when you are. Explore endpoints in your terminal today, then harden your integration behind your key. Try FreightPulse for free and ship a fuel-aware workflow that your ops team can trust.