If you price freight lanes or budget fuel surcharges in the Midwest, you need a concrete, reproducible way to retrieve the EIA-derived “Midwest Diesel” benchmark and wire it into your finance stack. By the end of this guide you will be able to query FreightPulse for the Midwest Diesel metric, parse the response that wraps EIA data, and integrate it into your pricing, forecasting, or reconciliation code with clear handling of units, timestamps, and caching.
What you will build
You will make a simple, dependable integration against FreightPulse’s fuel endpoint that returns the EIA-sourced Midwest Diesel price. We will cover:
- How to authenticate using the X-API-Key header (and what you can do without a key).
- The exact response envelope you should expect and how to parse it safely.
- How to request the “Midwest Diesel” metric for finance workflows and read the values you actually need (USD per gallon).
- Practicalities: timestamps, units, caching, and guardrails that prevent quoting stale or unrelated data.
Access, authentication, and envelope
Keep these integration facts at hand; they will save you time during testing and deployment:
- Auth: header X-API-Key: YOUR_API_KEY. Guest without key: 100 requests/day per IP.
- Envelope: {"success":true,"data":{...}}
- Port congestion is IMF PortWatch, lagged ~6-7 days, 7-day avg vs 90-day baseline — not live AIS.
- Do not quote a freight-rates USD fare as today’s price.
- Metric: Midwest Diesel
- curl: curl -H "X-API-Key: YOUR_API_KEY" "https://freightpulsehq.com/api/v1/historical?metric=fuel_price_diesel_midwest&period=30d"
- No official historical series is published for fuel_price_diesel_midwest. Show the curl and series[].value. Do not reuse the diesel-national 5.257 fixture.
If you need an API key, create one via Register. Reference parameters and schema anytime in the Documentation.
The Midwest Diesel metric and units you should expect
The “Midwest Diesel” metric reflects the EIA diesel retail price level for the Midwest region and is served in United States dollars per gallon. In responses where the pricing block is present, the base currency is USD and the unit is gallon. Treat all monetary outputs as floats in USD; do not mix them with other currencies or liters.
FreightPulse wraps these values in a stable, top-level envelope with success and data keys. Always check the success flag before dereferencing nested fields. For finance-grade extracts you should also record the top-level timestamp (ISO-8601, typically UTC with an explicit offset) so you can reproduce downstream calculations and audit how fresh a price was when it entered a ledger or planning model.
Official sample for fuel prices (copy-paste ready)
The following live sample shows the authentication header, path, and a representative JSON payload. Use this to scaffold your parser and verify fields and units in tests:
cURL:
curl -H "X-API-Key: YOUR_API_KEY" "https://freightpulsehq.com/api/v1/historical?metric=fuel_price_diesel_midwest&period=30d"JSON:
{
"success": true,
"data": {
"timestamp": "2026-10-02T12:00:34+00:00",
"source": "EIA (U.S. Energy Information Administration)",
"currency": "USD",
"unit": "gallon",
"data": {
"diesel": {
"national_average": 6.382,
"change_week": -0.147,
"change_percent": -2.25,
"updated_at": "2026-09-28",
"regions": {
"east_coast": 6.137,
"midwest": 6.526,
"gulf_coast": 5.955,
"rocky_mountain": 6.407,
"west_coast": 7.357,
"california": 8.181
}
},
"gasoline": {
"national_average": 4.465,
"change_week": -0.013,
"change_percent": -0.29,
"updated_at": "2026-09-28",
"grades": {
"regular": 4.465,
"midgrade": 5.073,
"premium": 5.482
}
},
"bunker_fuel": {
"available": false,
"note": "No known free source (Rotterdam/Singapore/Houston) — requires a paid provider (e.g. Ship & Bunker, Argus)."
}
},
"historical": {
"diesel_30d_avg": 6.291,
"diesel_90d_avg": 5.561,
"diesel_yoy_change": 72,
"gasoline_30d_avg": 4.355,
"gasoline_90d_avg": 4.111,
"gasoline_yoy_change": 42.9
}
},
"meta": {
"request_id": "52112c12-9cba-475b-b45c-7c4176d43f0b"
}
}Fields you will typically consume for finance calculations:
- data.timestamp: ISO-8601 string with offset; record this for auditability and cache staleness checks.
- data.currency and data.unit: USD per gallon; store alongside the price to prevent unit drift.
- data.data.diesel.regions.midwest: the Midwest Diesel point-in-time level.
- data.data.diesel.updated_at: date of the underlying EIA update; use to align weekly accruals.
- Optional aggregates in data.historical for 30d/90d context; helpful for finance variance analysis but not a substitute for a dated series.
Requesting the “Midwest Diesel” series for finance workflows
For budgeting or accrual rollforward you often want a dated series you can sum, average, or join to GL periods. FreightPulse exposes the Midwest Diesel metric via a historical endpoint keyed by metric=fuel_price_diesel_midwest. Note: No official historical series is published for fuel_price_diesel_midwest. You can still call the endpoint and read series[].value when present; build your parser to degrade gracefully if series is missing and fall back to the latest point-in-time level from data.data.diesel.regions.midwest.
Copy-pasteable request:
Parsing guidance:
- Check success is true, then prefer a dated series at data.series (read series[].value and series[].date) if provided.
- If data.series is absent, use data.data.diesel.regions.midwest with data.data.diesel.updated_at as the effective date.
- Always treat numbers as USD per gallon; never convert to liters unless you explicitly handle unit conversion in downstream code.
Python example: fetch and read series[].value for Midwest Diesel
The snippet below calls the same endpoint as the cURL above and safely reads either a dated series or a single Midwest point with its effective date. It also captures timestamp, currency, and unit for finance-grade records.
import os
import requests
from datetime import datetime, timezone
API_URL = "https://freightpulsehq.com/api/v1/historical"
API_KEY = os.getenv("FREIGHTPULSE_API_KEY", "YOUR_API_KEY")
params = {
"metric": "fuel_price_diesel_midwest",
"period": "30d"
}
headers = {
"X-API-Key": API_KEY
}
resp = requests.get(API_URL, params=params, headers=headers, timeout=20)
resp.raise_for_status()
payload = resp.json()
if not payload.get("success"):
raise RuntimeError("FreightPulse returned success=false")
data = payload.get("data", {})
# Always record audit fields if present
fp_timestamp = data.get("timestamp") # e.g., "2026-10-02T12:00:34+00:00"
currency = data.get("currency") # "USD"
unit = data.get("unit") # "gallon"
# Prefer a dated series if provided
series = data.get("series", []) # Expect elements like {"date": "YYYY-MM-DD", "value": 6.526}
records = []
if isinstance(series, list) and series:
for pt in series:
# Read the field explicitly requested in the catalog facts
value = pt.get("value")
date = pt.get("date")
if value is None or date is None:
continue
records.append({
"date": date,
"midwest_diesel": float(value),
"currency": currency,
"unit": unit
})
else:
# Fallback to the current Midwest point if series is not published
diesel = (data.get("data", {}) or {}).get("diesel", {})
midwest_value = (diesel.get("regions", {}) or {}).get("midwest")
effective_date = diesel.get("updated_at") # YYYY-MM-DD when EIA last updated
if midwest_value is None:
raise KeyError("Midwest Diesel not found in response")
records.append({
"date": effective_date,
"midwest_diesel": float(midwest_value),
"currency": currency,
"unit": unit
})
# Example: compute a simple 30-day average if you got a series
if len(records) > 1:
avg = sum(r["midwest_diesel"] for r in records) / len(records)
print(f"Midwest Diesel 30d average: {avg:.3f} {currency}/{unit}")
else:
only = records[0]
print(f"Midwest Diesel latest: {only['midwest_diesel']:.3f} {currency}/{unit} (as of {only['date']})")
# Persist or pass 'records' into your finance model as needed
Finance-grade handling: timestamps, caching, and cutovers
Finance teams care about when a price was valid, not just when it was fetched. Use these practices when you operationalize the Midwest Diesel metric:
- Timestamps and timezone: The top-level timestamp is an ISO-8601 string with an explicit UTC offset. Store it and the effective date (e.g., data.data.diesel.updated_at) so you can justify which accounting period a price influenced.
- Units and currency: All values discussed here are USD per gallon. Persist both attributes with the numeric value to prevent silent unit regressions in downstream transforms.
- Caching: If you cache responses, key them by metric, period, and a content hash of the payload or updated_at. Expire the cache when the EIA update date changes to avoid mixing weeks.
- Cadence: EIA diesel retail prices have a weekly cadence. Exact publish timing may vary; consult the Documentation and treat updated_at as canonical for period alignment.
- Backfills: If data.series appears after a period where only a point-in-time level was available, prefer the series for retroactive reconciliations and variance analysis.
Avoiding common mistakes
- Do not quote a freight-rates USD fare as today’s fuel price. The Midwest Diesel metric is a fuel benchmark; keep it separate from spot rate or contract rate objects in your code.
- Do not blend Midwest with national or other regions when your policy specifies Midwest. Use data.data.diesel.regions.midwest explicitly for fuel surcharge calculations tied to that geography.
- Do not assume liters, euros, or per-barrel units. This feed uses USD per gallon unless you explicitly convert downstream.
- Do not treat port congestion as a live signal; FreightPulse’s congestion is based on IMF PortWatch and lagged by roughly 6–7 days. It is unrelated to “Midwest Diesel” and should not gate fuel pricing logic.
Guest access and deployment steps
You can test without an API key at modest volume. Guest access is capped at 100 requests/day per IP. This is usually enough to build a prototype, wire environment variables, and verify parsing and caching. For CI or production, create a key via Register and store it in your secret manager. In Kubernetes or similar orchestrators, mount it as FREIGHTPULSE_API_KEY and pass it to your service.
Validation checklist before you ship
- Authentication: X-API-Key header present in all production calls.
- Envelope: Assert payload.success is true, and guard every nested dereference with defaults.
- Fields: Read either data.series[].value (with date) or fallback to data.data.diesel.regions.midwest with updated_at.
- Audit: Persist data.timestamp (ISO-8601), data.currency, data.unit, and either date or updated_at for the price point.
- Caching: Invalidate cache when updated_at changes; avoid merging weeks.
- Testing: Under guest access, ensure your integration respects the 100 requests/day/IP limit.
FAQ
What unit and currency does Midwest Diesel use?
USD per gallon. Read data.currency and data.unit to confirm and store alongside the value.
How do I get a 30-day series for the Midwest Diesel metric?
Call GET https://freightpulsehq.com/api/v1/historical?metric=fuel_price_diesel_midwest&period=30d with the X-API-Key header. If data.series is present, iterate series[].value and series[].date. If a series is not published, use data.data.diesel.regions.midwest with data.data.diesel.updated_at for the effective date.
Can I use this to quote today’s national diesel average?
Do not invent or substitute a national value. This guide focuses on the Midwest Diesel metric. If you need other regions or aggregates, consult the Documentation and only use values returned by the API.
Is port congestion included or live?
Port congestion metrics on FreightPulse use IMF PortWatch and are lagged by approximately 6–7 days. They are not live AIS wait times and are unrelated to the Midwest Diesel metric.
Can I access the API without a key?
Yes. Guest access allows 100 requests per day per IP without a key. For sustained use, register and send X-API-Key: YOUR_API_KEY.
Get your integration into production
Create your API key and wire the X-API-Key header so you can call the Midwest Diesel metric reliably at build and run time. Start here: Register, then keep the schema and field references handy in the Documentation.