You need a reliable, finance-grade way to programmatically fetch the current East Coast Diesel price (as reported by the U.S. Energy Information Administration) and wire it into budgets, fuel-surcharge models, or risk dashboards. By the end of this guide, you will query FreightPulse for East Coast Diesel, parse the response you need, and ship a production-safe integration that respects authentication, rate limits, timestamps, units, and caching.
What the “East Coast Diesel” metric represents
East Coast Diesel on FreightPulse is an EIA-reported retail diesel price for the East Coast region, denominated in USD per gallon. It is a finance-relevant reference price commonly used for weekly fuel-surcharge formulas, cost-of-goods updates, and transportation budget scenarios. The API provides a unified envelope with source, timestamp, currency, and unit so you can reconcile it cleanly with your finance data models.
Important context you can rely on when combining this with other FreightPulse data points:
- Port congestion on FreightPulse is sourced from IMF PortWatch, lagged by ~6–7 days and computed as a 7‑day average against a 90‑day baseline. It is not live AIS wait times.
- Do not quote a freight-rates USD fare as today’s price. This guide focuses on the EIA “East Coast Diesel” metric only.
Authentication, headers, and the response envelope
FreightPulse uses a simple API key in the X-API-Key header. Requests return a JSON envelope with a success flag and a data payload so you can standardize error handling in finance services.
- Auth: header X-API-Key: YOUR_API_KEY. Guest without key: 100 requests/day per IP.
- Envelope: {"success":true,"data":{...}}
If you do not have an API key yet, guest access is available as noted above. To increase limits and stabilize production traffic, create an account via Register. See request/response specifics in the Documentation.
The endpoints you will use
This finance integration relies on the FreightPulse fuel endpoints:
- GET https://freightpulsehq.com/api/v1/fuel-prices — live fuel snapshot envelope (authenticated with X-API-Key).
- GET https://freightpulsehq.com/api/v1/historical?metric=fuel_price_diesel_east_coast&period=30d — historical context for the East Coast Diesel metric, as shown in the official sample below.
Note on history: No official historical series is published for fuel_price_diesel_east_coast beyond what the endpoint returns. Use the provided sample and fields exactly as documented; do not assume a separate series[] exists if it’s not present in your response.
Quick start with cURL (copy and run)
The following is the official example request. Keep the URL, parameters, and header as-is. Replace YOUR_API_KEY with your key if you have one; otherwise you can test within guest limits.
curl -H "X-API-Key: YOUR_API_KEY" "https://freightpulsehq.com/api/v1/historical?metric=fuel_price_diesel_east_coast&period=30d"Official JSON response and what you’ll actually use
This is the official sample response for the call above. Copy it exactly if you need a fixture for local testing, but do not hardcode values in production.
{
"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’ll actually use in a finance integration:
- data.timestamp: ISO 8601 in UTC (+00:00). Use it to snapshot the valuation time in your ledger.
- data.currency: USD. Keep all downstream math in USD unless you explicitly FX-convert later.
- data.unit: gallon. Price is per gallon; convert to liters or barrels only if your cost model requires it.
- data.data.diesel.regions.east_coast: The East Coast Diesel price you need for finance calculations.
- data.data.diesel.updated_at: EIA’s reporting date; typically weekly. Cache around this cadence.
- data.historical.*: Rolling aggregates that can inform finance variance analysis; use them as indicators, not as a replacement for a tick-by-tick series.
Do not present the national_average as a substitute for East Coast Diesel in region-specific formulas. Always source the regional value at data.data.diesel.regions.east_coast for the computation described in this article.
Python example: fetch and use East Coast Diesel in a surcharge calculation
The snippet below calls the same endpoint as the cURL example, extracts the East Coast Diesel price, asserts currency/unit, and demonstrates a simple weekly fuel-surcharge computation. Adapt the constants to match your internal policy.
import os
import requests
from decimal import Decimal, ROUND_HALF_UP
API_URL = "https://freightpulsehq.com/api/v1/historical"
PARAMS = {
"metric": "fuel_price_diesel_east_coast",
"period": "30d"
}
HEADERS = {
"X-API-Key": os.getenv("FREIGHTPULSE_API_KEY", "YOUR_API_KEY")
}
def fetch_east_coast_diesel():
r = requests.get(API_URL, params=PARAMS, headers=HEADERS, timeout=20)
r.raise_for_status()
payload = r.json()
if not payload.get("success"):
raise RuntimeError("FreightPulse API returned success=false")
data = payload["data"]
# Sanity checks for finance integrations
assert data.get("currency") == "USD", "Unexpected currency"
assert data.get("unit") == "gallon", "Unexpected unit"
price = Decimal(str(data["data"]["diesel"]["regions"]["east_coast"]))
ts = data["timestamp"] # ISO 8601 UTC
updated_at = data["data"]["diesel"]["updated_at"] # EIA reporting date
return price, ts, updated_at
def apply_surcharge(base_linehaul_usd, fuel_floor=Decimal("1.25"), per_10c_pct=Decimal("0.5")):
"""
Example policy:
- No surcharge below a fuel floor (USD/gal).
- For every $0.10/gal above the floor, add 0.5% to the linehaul.
"""
diesel, ts, updated_at = fetch_east_coast_diesel()
if diesel <= fuel_floor:
return {
"linehaul_usd": Decimal(str(base_linehaul_usd)),
"surcharge_pct": Decimal("0.00"),
"diesel_usd_per_gal": diesel,
"valued_at": ts,
"eia_reporting_date": updated_at
}
steps = ((diesel - fuel_floor) / Decimal("0.10"))
surcharge_pct = (steps.quantize(Decimal("1."), rounding=ROUND_HALF_UP)) * per_10c_pct
linehaul = Decimal(str(base_linehaul_usd))
total = (linehaul * (Decimal("1.00") + surcharge_pct / Decimal("100"))).quantize(Decimal("0.01"))
return {
"linehaul_usd": total,
"surcharge_pct": surcharge_pct.quantize(Decimal("0.01")),
"diesel_usd_per_gal": diesel,
"valued_at": ts,
"eia_reporting_date": updated_at
}
if __name__ == "__main__":
quote = apply_surcharge(base_linehaul_usd=Decimal("1200.00"))
print(quote)Handling data quality, currency/units, and caching
Units and currency:
- Currency is USD and unit is gallon. If your accruals or AP pipeline require liters, convert at 1 gallon ≈ 3.78541 liters and document the conversion factor in your finance policy.
- Do not alter rounding upstream. Normalize to Decimal in your code and centralize rounding policies (e.g., 2 decimals for surcharges, 4 for internal analytics).
Timestamps and cadence:
- data.timestamp is an ISO 8601 UTC stamp indicating when FreightPulse assembled the payload.
- data.data.diesel.updated_at is the EIA reporting date; typically weekly. Treat the price as a weekly fix for billing cycles.
- Cache for the duration of the EIA week if your SLA allows it, then refresh on the next updated_at. Use strong ETags only if provided in your own reverse proxy; the API contract here is header-based auth plus the JSON envelope.
Rate limits and retries:
- Guest access: 100 requests/day per IP without a key. Use pooling and caching in shared services to stay under this cap.
- On transient 5xx or network timeouts, use exponential backoff and log request_id from meta to aid support.
Finance integration patterns for East Coast Diesel
Integrating this metric typically falls into one of three finance patterns:
- Weekly surcharge tables: Pull the current East Coast Diesel once after the EIA update, compute the weekly surcharge tiers, and publish a versioned rate card in your ERP.
- Budget and variance tracking: Store each week’s price alongside data.timestamp and updated_at, and compute variances against your approved fuel baseline in your BI tool.
- Scenario planning: Combine today’s regional price with rolling aggregates (e.g., diesel_30d_avg) to stress-test sensitivity in your P&L without overfitting to a single week.
A note on other FreightPulse metrics you might juxtapose for finance: port congestion comes from IMF PortWatch and is lagged by ~6–7 days, calculated as a 7-day average vs a 90-day baseline. It’s not a live AIS wait-time feed, so timestamp alignment differs from the weekly EIA cadence. Avoid mixing real-time assumptions into these lagged indicators in your cost models.
Production checks before you ship
1) Validate the envelope and required fields
Always check success is true, then assert currency=USD and unit=gallon. Fail fast with a descriptive error if any assertion fails, so the issue surfaces in logs before finance runs.
2) Use the regional field for East Coast
Read data.data.diesel.regions.east_coast for your calculations. Do not substitute with a national average when your policy requires a regional rate.
3) Persist a minimal audit trail
Store {price, data.timestamp, data.data.diesel.updated_at, source, meta.request_id} with your computed outputs. This is enough to backfill or reconcile invoices later.
4) Respect guest caps or use a key
If your service runs more than a few times daily across multiple nodes, use an API key and centralize fetching to one job that caches to a KV store (e.g., Redis), then fan out to downstream consumers.
Troubleshooting
- Missing East Coast value: Confirm you’re reading data.data.diesel.regions.east_coast. If the regions map is absent, log the full payload; your integration should degrade gracefully and alert ops.
- Unexpected currency or unit: The sample and contract specify USD and gallon. If it differs, pause automated postings and file an issue with your logged meta.request_id.
- Data staleness: Compare data.timestamp and data.data.diesel.updated_at. If updated_at hasn’t advanced after an expected EIA release window, keep last known good in effect and schedule a retry.
FAQ
Q1: Do I need an API key?
A: You can start without one (100 requests/day per IP). For production finance workloads, use X-API-Key: YOUR_API_KEY to avoid hitting guest caps.
Q2: Which fields drive fuel-surcharge math?
A: data.data.diesel.regions.east_coast is the regional price; pair it with data.data.diesel.updated_at (reporting date) and data.timestamp (valuation time).
Q3: Are these prices live?
A: EIA diesel values are typically weekly. Use updated_at to align billing cycles and set cache TTLs accordingly. Do not assume intra-day updates.
Q4: Is there a historical time series?
A: No official historical series is published for fuel_price_diesel_east_coast beyond what the endpoint returns. Use the provided aggregates (e.g., diesel_30d_avg) for context, and archive weekly values yourself for long-run analysis.
Q5: Can I mix this with port congestion data?
A: Yes, but remember port congestion is lagged (~6–7 days) from IMF PortWatch and is a 7-day average vs a 90-day baseline. Align timestamps carefully in finance reports.
Ready to wire East Coast Diesel into your finance stack with predictable cadence and clean auditability? Create your key on Register and review the exact request/response fields in the Documentation.