You need a reliable way to programmatically fetch the EIA-sourced Gulf Coast Diesel price so you can calculate fuel surcharges, update budget models, or reconcile transportation costs. By the end of this guide, you will be able to call the FreightPulse fuel-prices API, extract the Gulf Coast Diesel value (USD per gallon), and persist your own historical series for financial analytics and reporting.
What you will build with the Gulf Coast Diesel metric
This walkthrough focuses on one task: ingesting the Gulf Coast Diesel price into your finance workflows. Typical outputs include a daily or weekly price table, a surcharge index keyed to your lanes, and variance analysis against contracts. All examples call only the documented FreightPulse endpoint for this metric and keep values in USD per gallon.
API access, authentication, and envelope
FreightPulse supports authenticated requests via an HTTP header and offers limited guest access:
- Auth: header X-API-Key: YOUR_API_KEY. Guest without key: 100 requests/day per IP.
- All responses are wrapped in an envelope: {"success":true,"data":{...}}
If you expect higher volumes, register for an API key: Register. For parameter details, see the Documentation.
The endpoint to call for Gulf Coast Diesel
Use the historical endpoint with the Gulf Coast Diesel metric. This returns an envelope with the latest values in USD per gallon and associated metadata. No official historical series is published for fuel_price_diesel_gulf_coast; you will store your own series for analytics.
Copy-paste cURL
curl -H "X-API-Key: YOUR_API_KEY" "https://freightpulsehq.com/api/v1/historical?metric=fuel_price_diesel_gulf_coast&period=30d"Official sample response and the fields you actually need
Below is the verbatim response sample for the endpoint above. Note that currency and unit are USD and gallon, respectively. You will read the Gulf Coast Diesel value from data.diesel.regions.gulf_coast and persist it with a timestamp for your own history.
{
"success": true,
"data": {
"timestamp": "2026-10-03T00:00:19+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": "95242e83-a30f-4767-bcd6-bc53e60d204e"
}
}What to read for Gulf Coast Diesel:
- data.unit and data.currency: confirm the price is USD per gallon.
- data.timestamp: UTC timestamp for when this payload was generated.
- data.data.diesel.updated_at: the as-of date for the diesel values.
- data.data.diesel.regions.gulf_coast: the Gulf Coast Diesel price to persist in your system.
Do not invent your own national average and do not quote a freight-rates USD fare as today’s price. For finance workflows, bind the value you use to its updated_at date and timestamp for traceability.
Parse Gulf Coast Diesel and build your own series (Python)
Because no official historical series is published for fuel_price_diesel_gulf_coast, you should snapshot the value into your datastore each time you call the endpoint and create a local series. The example below calls the same endpoint, extracts the Gulf Coast value, and appends it to a series array where series[i].value holds the numeric price.
import os
import sys
import json
import time
from datetime import datetime, timezone
import urllib.request
API_URL = "https://freightpulsehq.com/api/v1/historical?metric=fuel_price_diesel_gulf_coast&period=30d"
API_KEY = os.getenv("FREIGHTPULSE_API_KEY", "YOUR_API_KEY")
def fetch_gulf_coast_diesel():
req = urllib.request.Request(API_URL, headers={"X-API-Key": API_KEY})
with urllib.request.urlopen(req, timeout=20) as resp:
body = resp.read()
data = json.loads(body.decode("utf-8"))
if not data.get("success"):
raise RuntimeError("API returned success=false")
payload = data["data"]
ts_iso = payload.get("timestamp") # e.g., 2026-10-03T00:00:19+00:00 (UTC)
asof = payload["data"]["diesel"].get("updated_at") # e.g., 2026-09-28 (date)
price = payload["data"]["diesel"]["regions"]["gulf_coast"] # USD per gallon
unit = payload.get("unit")
currency = payload.get("currency")
return {
"timestamp": ts_iso,
"as_of": asof,
"value": price,
"unit": unit,
"currency": currency,
"source": payload.get("source")
}
def append_to_local_series(point, series_path="gulf_coast_diesel_series.jsonl"):
# Persist an append-only local series so you can compute your own history.
# Each line: {"ts": "...", "as_of": "...", "value": 5.955, "unit": "gallon", "currency": "USD"}
record = {
"ts": point["timestamp"],
"as_of": point["as_of"],
"value": point["value"],
"unit": point["unit"],
"currency": point["currency"]
}
with open(series_path, "a", encoding="utf-8") as f:
f.write(json.dumps(record, ensure_ascii=False) + "\n")
def load_series(series_path="gulf_coast_diesel_series.jsonl"):
series = []
if not os.path.exists(series_path):
return series
with open(series_path, "r", encoding="utf-8") as f:
for line in f:
if line.strip():
series.append(json.loads(line))
return series
if __name__ == "__main__":
point = fetch_gulf_coast_diesel()
append_to_local_series(point)
series = load_series()
# Example: read series[].value for analytics/finance workflows
latest = series[-1] if series else None
if latest:
print(f"As-of {latest['as_of']} Gulf Coast Diesel = {latest['value']} {latest['currency']}/{latest['unit']}")
else:
print("No data yet")In this example, series is your local historical record, and series[i].value is the Gulf Coast Diesel price you will use in downstream finance calculations. The units remain gallon and USD as indicated by the API response.
Handling history when no official series is published
Because there is no official historical series published for fuel_price_diesel_gulf_coast, your options are:
- Snapshot the endpoint at a consistent cadence and write an append-only series with fields: ts (UTC), as_of (date), value (USD/gallon).
- De-duplicate by as_of if you poll multiple times on the same reporting date.
- Cache the latest record and update only when updated_at changes.
This approach provides a stable series[].value timeline for budgets, indexation, and reporting without relying on an additional historical feed.
Finance-grade implementation details that save time
- Units and currency: Prices are in USD per gallon. Always confirm via data.currency and data.unit before usage.
- Timestamps and timezone: data.timestamp is ISO-8601 with UTC offset. Align your warehouse to UTC to avoid DST drift.
- As-of date: For reporting, anchor values to data.data.diesel.updated_at rather than your ingestion time.
- Caching: Because updated_at may not change intra-day, a 1–6 hour cache TTL reduces request volume without losing fidelity.
- Guest access: Without a key, you are limited to 100 requests/day per IP. Add X-API-Key: YOUR_API_KEY for higher limits (see Documentation).
Data provenance and scope
The fuel price source is EIA (U.S. Energy Information Administration), exposed via FreightPulse. This guide only covers the Gulf Coast Diesel metric and does not quote or infer any freight-rate USD fares as current prices. If you also consume congestion data from FreightPulse, note that port congestion is IMF PortWatch, lagged ~6–7 days, 7-day average vs 90-day baseline — not live AIS.
Operational guidance: retries, quotas, and idempotency
- Retries: Use exponential backoff on transient 5xx. Do not retry on 4xx without changing inputs.
- Idempotency: Treat ingestion as upsert keyed by as_of to avoid double-counting if your job re-runs.
- Request planning: With guest access, a once-per-day poll per environment stays within 100/day. Use an API key for higher environments or more frequent polling.
- Monitoring: Alert when the response envelope has success=false or when currency/unit deviates from USD/gallon.
Common pitfalls
- Mixing units: Always read unit and currency fields; do not assume defaults in downstream reports.
- Treating ingestion time as price date: Use updated_at for financial period alignment.
- Over-polling: If updated_at has not changed, skip writes; keep one record per as_of date.
- Assuming live congestion: If you later add port congestion, remember FreightPulse cites IMF PortWatch lagged ~6–7 days, not live AIS.
FAQ
Q: How do I authenticate?
Send the header X-API-Key: YOUR_API_KEY. Guests without a key have 100 requests/day per IP.
Q: Which field is the Gulf Coast Diesel price?
Read data.data.diesel.regions.gulf_coast. Confirm unit=gallon and currency=USD.
Q: Is there an official historical series for Gulf Coast Diesel?
No. There is no official historical series published for fuel_price_diesel_gulf_coast. Create your own series by snapshotting and storing value, as_of, and timestamp. Your analytics can then use series[].value.
Q: Can I use the national average instead?
The response includes a national_average field, but do not invent a national average and do not substitute it for the Gulf Coast metric. Use the region-specific value required by your finance model.
Q: What is the data source for these prices?
EIA (U.S. Energy Information Administration), as noted in data.source.
Set up your ingestion now so your finance models have a clean Gulf Coast Diesel time series. Create an API key at Register and integrate with the Documentation for deployment details.