Your finance team needs a dependable way to pull the EIA’s Midwest Gasoline metric into internal dashboards and models, without scraping or manually updating spreadsheets. By the end of this guide, you’ll be able to query FreightPulse for Midwest gasoline price context, read the units and currency precisely, understand what historical data is or is not available for this metric, and integrate a production-grade call into your codebase.
What you get from this endpoint and what you should not assume
FreightPulse provides an API surface for energy prices sourced from the EIA. Responses arrive in a consistent envelope so you can parse them reliably and cache what you need. You should expect to receive current price context (unit, currency, EIA source metadata) and gasoline price fields in the response body. You should not assume a published official historical time series for the Midwest Gasoline metric is available in the endpoint below; more on that in the historical section.
Key facts you will use in your integration:
- Auth: header X-API-Key: YOUR_API_KEY. Guest without key: 100 requests/day per IP.
- Envelope: {"success":true,"data":{...}} — always check success before reading data.
- Metric: Midwest Gasoline, sourced from EIA (U.S. Energy Information Administration).
- Units and currency: gallon and USD. Timestamps are ISO-8601 with timezone offset.
- FreightPulse’s port congestion metric is IMF PortWatch (lagged ~6–7 days, 7-day avg vs 90-day baseline). It is unrelated to gasoline pricing and not live AIS.
- Do not quote a freight-rates USD fare as today’s price; this guide concerns the EIA fuel-price metric.
Authentication, rate limits, and access patterns
You can start with guest access if you do not include an API key; guest requests are limited to 100 requests per day per IP. For production systems, add the header X-API-Key with your key to avoid hitting the guest limit and to simplify server-side observability. Always include the header in automated jobs to keep environments consistent.
If you have not created an account yet, use the links below:
Quickstart: one request that returns Midwest gasoline context
This is the official, copy-pasteable curl for the Midwest gasoline metric. It uses the documented header and endpoint. Replace YOUR_API_KEY with your key or omit the header for guest mode (100 requests/day per IP).
curl -H "X-API-Key: YOUR_API_KEY" "https://freightpulsehq.com/api/v1/historical?metric=fuel_price_gasoline_midwest&period=30d"Official sample JSON response (copy is verbatim so you can confirm field names and structure):
{
"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"
}
}Fields to pay attention to for finance and analytics:
- data.timestamp — ISO-8601 with timezone (UTC offset +00:00). Use this to timestamp your cache and time-align model inputs.
- data.source — EIA attribution; retain this in your lineage metadata.
- data.currency and data.unit — USD and gallon. Always carry units through your pipelines to avoid mixing per-gallon with per-barrel or per-liter series.
- data.data.gasoline.* — current gasoline price context and grade breakdown (regular, midgrade, premium). Do not invent a national average; read it from the payload when present.
- data.historical.* — rollup averages and YoY deltas that may help with normalization; treat these as context rather than a substitute for a Midwest-specific historical series.
Important note on historical availability for Midwest Gasoline
No official historical series is published for fuel_price_gasoline_midwest. You should still call the endpoint above for the Midwest Gasoline metric because the response envelope communicates currency, unit, timestamp, and gasoline context that you can use in your models. If a time series is ever included, it typically appears as a list (for example, series[]) in a historical block; when present, you would read series[i].value for numeric points.
Implementation guidance:
- Code defensively: check whether a series array exists before iterating.
- If no series is present, use the provided unit, currency, timestamp, and gasoline context fields in your downstream logic.
- Do not substitute another commodity (e.g., diesel) for the Midwest gasoline historical series, and do not reuse any fixture from a different metric.
Production-grade Python example
This sample calls the same endpoint as the curl above, validates the standard envelope, extracts gasoline context, and conditionally iterates a historical series only if present. It avoids assumptions about missing fields.
import os
import time
import requests
API_URL = "https://freightpulsehq.com/api/v1/historical"
PARAMS = {
"metric": "fuel_price_gasoline_midwest",
"period": "30d"
}
HEADERS = {
# Use YOUR_API_KEY or remove this header for guest mode (100 requests/day per IP).
"X-API-Key": os.getenv("FREIGHTPULSE_API_KEY", "YOUR_API_KEY")
}
def fetch_midwest_gasoline():
r = requests.get(API_URL, params=PARAMS, headers=HEADERS, timeout=20)
r.raise_for_status()
payload = r.json()
if not isinstance(payload, dict) or not payload.get("success"):
raise RuntimeError("Unsuccessful response or unexpected envelope")
data = payload.get("data", {})
meta = payload.get("meta", {})
# Metadata you should store for auditability
ts = data.get("timestamp") # ISO-8601, includes timezone offset
src = data.get("source") # EIA (U.S. Energy Information Administration)
currency = data.get("currency") # USD
unit = data.get("unit") # gallon
# Gasoline context: national and grades (note: do not invent a national average)
energy = data.get("data", {})
gasoline = energy.get("gasoline", {})
gasoline_updated = gasoline.get("updated_at")
grades = gasoline.get("grades", {}) or {}
regular = grades.get("regular")
midgrade = grades.get("midgrade")
premium = grades.get("premium")
# Optional historical handling: only iterate if a 'series' exists
hist = data.get("historical", {}) or {}
series = hist.get("series") # This may be absent for this metric
historical_values = []
if isinstance(series, list):
for pt in series:
# Read numeric value when present without inventing data
val = pt.get("value")
dt = pt.get("date") or pt.get("timestamp")
if val is not None:
historical_values.append({"date": dt, "value": val})
return {
"timestamp": ts,
"source": src,
"currency": currency,
"unit": unit,
"updated_at": gasoline_updated,
"regular": regular,
"midgrade": midgrade,
"premium": premium,
"historical_series_points": len(historical_values),
"request_id": meta.get("request_id"),
}
if __name__ == "__main__":
out = fetch_midwest_gasoline()
print(out)Handling units, currency, and timestamps correctly
All prices in the sample response are denominated in USD and measured per gallon. Do not convert or re-denominate implicitly; make conversions explicit and unit-tested if your model requires barrels or liters. Timestamps are ISO-8601 with an explicit timezone offset (+00:00 in the sample), which you can parse in most standard libraries to UTC for storage. When caching responses, include the timestamp, unit, currency, and any updated_at fields in your cache key to prevent cross-metric contamination.
Practical tips:
- Cache lifetime: if you run hourly ETL, store the full JSON blob and its parsed summary for reproducibility; do not assume minute-level changes for an EIA-sourced metric.
- Pagination: not indicated in the provided sample — treat this endpoint as a single-document payload. If a series appears in future responses, it would typically be an array inside the payload rather than a paginated cursor.
- Non-trading days: gasoline price updates reference EIA reporting cadence, not market trading sessions; do not apply market-hours logic.
Error handling, idempotency, and resiliency
The response is wrapped in a {"success":true,"data":{...}} envelope. Always check success before accessing data. On non-200 HTTP statuses, raise and back off. For guest usage, account for the 100 requests/day per IP limit; if you are near that threshold, add a server-side key and centralize calls to prevent exceeding the limit across multiple jobs or developers.
Suggested approach:
- Use timeouts and retries with exponential backoff for network issues.
- Validate required fields: timestamp, currency, unit, and gasoline grades before persisting downstream.
- Log and propagate data.meta.request_id to correlate application logs with provider-side traces when engaging support.
Interpreting the gasoline fields for finance use cases
The gasoline block provides the current national context and grade breakdowns. While the endpoint centers on the Midwest gasoline metric, you should still read unit, currency, and updated_at to ensure that internal cost models reflect the correct reporting period. Because no official Midwest historical series is published, risk systems should avoid synthetic backfills from unrelated series and instead combine the gasoline grade context with your internal operational data (e.g., station mix by grade, hedging exposure denominated per gallon) for period-over-period analysis.
Guidelines for integration into finance models:
- Do not hardcode national averages or invent missing values. Only use the values the API returns in your execution run.
- Normalize values to your payout or accrual cadence using the timestamp and updated_at fields for alignment.
- When a historical list is not present, annotate your data record as “point-in-time context” rather than “time series” to avoid misleading visualization or regression inputs.
Testing plan and data governance checklist
Before promoting this integration to production, verify your handling of envelope structure, missing historical series, and the EIA attribution. Automated tests should validate both the presence and the absence of a series[] list so that your code is resilient when structures evolve.
- Schema tests: assert that success is boolean; data is an object; and currency/unit are strings.
- Semantics tests: if grades.regular exists, it is numeric; if historical.series exists, each element with value is numeric and date/timestamp is parseable.
- Lineage: store source and request_id to enable traceability and audits.
- Security: ensure the X-API-Key is injected at runtime via environment variables and not hardcoded into repositories.
FAQ
How do I authenticate and what happens if I omit the API key?
Send X-API-Key: YOUR_API_KEY in the request header. If you omit it, you are treated as a guest with 100 requests/day per IP. For CI/CD or production batch jobs, add the header to avoid rate-limit surprises.
What units and currency should I assume for Midwest Gasoline?
Use the fields from the response: currency is USD and unit is gallon. Do not assume other denominations; explicitly convert if you need liters or barrels.
Where can I get historical time series for fuel_price_gasoline_midwest?
No official historical series is published for this metric. You can still call the endpoint to obtain timestamped context and grade-level gasoline fields. If a series array appears in responses in the future, read series[i].value where present.
Is the response live and how often should I poll?
The data references EIA reporting; treat this as periodically updated rather than tick-level streaming. Polling more frequently than your downstream need offers limited benefit; cache responses alongside timestamp and updated_at to avoid redundant calls.
Does this endpoint include port congestion or other logistics metrics?
No. FreightPulse port congestion uses IMF PortWatch (lagged ~6–7 days, 7-day average vs 90-day baseline) and is separate from gasoline pricing. Do not treat it as live AIS wait times or mix it into the gasoline response.
Move this from a prototype to a stable data feed by creating an account and reading the exact field definitions and limits in the docs. Start here: Register and review the API reference at Documentation.