Home → Blog

You need a reliable, finance-grade way to fetch the EIA’s East Coast gasoline price signal and drop it into your P&L, hedging, or surcharge models. By the end of this guide, you will be able to authenticate, query, parse, and cache FreightPulse’s East Coast Gasoline metric and integrate it into a production finance workflow.

What you will build and why it matters to Finance

You will wire up a pull to FreightPulse’s fuel-price APIs, normalize the units and timestamps for ledger-safe use (USD per gallon, UTC timestamps), and expose the resulting values to your finance systems. This lets you calculate fuel surcharges, attribute variance in transportation COGS, and backtest scenarios without scraping or manual CSV imports.

Illustration: East Coast Gasoline Price API

The focus is the East Coast Gasoline metric sourced from the EIA via FreightPulse. You will learn the minimal set of endpoints, headers, and JSON fields you need, and how to avoid common misreads (such as treating a lagged signal as live).

Authentication, access caps, and request envelope

FreightPulse fuel-price endpoints require an API key passed as a header. Guest access is allowed for light testing without a key, capped at 100 requests per day per IP. All responses use a consistent envelope you can validate before parsing.

If you don’t have a key yet, start as a guest and switch to a key when you hit the cap or need stability. You can obtain a key any time via Register. Refer to the Documentation for endpoint coverage.

Endpoints you will use

Important fidelity notes you must preserve in finance workflows:

Copy-paste cURL for East Coast Gasoline (30 days)

This is the official call you can paste into a shell. It uses the X-API-Key header for authenticated access. If you omit the header, you will be treated as a guest with 100 requests/day per IP.

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

Official JSON response example (copy verbatim into tests)

This block is the live sample provided by FreightPulse. Keep its field names, units, and date handling intact when writing your parser. Currency is USD and unit is gallon.

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

Field notes that matter for Finance:

Second JSON example (same official response for fixture-based tests)

Maintain a fixture with the exact same fields and values to write deterministic unit tests for your parser and accounting adapters.

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

Third JSON example (same official response for integration smoke tests)

Use the same response body to validate headers, envelope parsing, and numeric coercion in your CI smoke tests.

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

How to interpret results for ledger and risk

The East Coast Gasoline metric is priced in USD per gallon and should be treated as a lagged benchmark from the EIA via FreightPulse. For finance workflows:

Python example: fetch and read series[].value for East Coast Gasoline

This Python snippet calls the same 30‑day endpoint. If a series array is present, it will iterate series[].value (USD per gallon). If the array is absent, it falls back to logging the envelope and timestamp so your finance job can decide how to proceed.

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_gasoline_east_coast&period=30d"
API_KEY = os.getenv("FREIGHTPULSE_API_KEY", "YOUR_API_KEY")

def fetch():
req = urllib.request.Request(API_URL, headers={"X-API-Key": API_KEY})
with urllib.request.urlopen(req, timeout=20) as resp:
body = resp.read().decode("utf-8")
return json.loads(body)

def main():
payload = fetch()
if not payload.get("success"):
print("Request failed: ", json.dumps(payload, indent=2))
sys.exit(1)

data = payload.get("data", {})
ts = data.get("timestamp")
src = data.get("source")
curr = data.get("currency")
unit = data.get("unit")

# Attempt to read a historical series when present
series = data.get("series", [])
if isinstance(series, list) and len(series) > 0:
# Expect objects like {"timestamp": "...", "value": <float>}
values = [pt.get("value") for pt in series if pt.get("value") is not None]
print(f"Series points for East Coast Gasoline: {len(values)} (currency={curr}, unit={unit})")
# Example: compute simple average for the window for a finance backtest
if values:
avg_window = sum(values) / len(values)
print(f"Window average: {avg_window}")
else:
# No official historical series is published; log envelope details for auditing
print("No series[] present. Using envelope metadata only.")
print(f"timestamp={ts}, source={src}, currency={curr}, unit={unit}")

if __name__ == "__main__":
main()

Notes:

JavaScript example: minimal fetch with header and safe parsing

This Node.js example fetches the same endpoint and shows how to guard against a missing series array while still making the result usable for finance scripts.

import fetch from "node-fetch";

const API_URL = "https://freightpulsehq.com/api/v1/historical?metric=fuel_price_gasoline_east_coast&period=30d";
const API_KEY = process.env.FREIGHTPULSE_API_KEY || "YOUR_API_KEY";

async function run() {
const res = await fetch(API_URL, {
headers: { "X-API-Key": API_KEY }
});

const json = await res.json();
if (!json.success) {
throw new Error("FreightPulse request failed: " + JSON.stringify(json));
}

const { data } = json;
const { timestamp, currency, unit } = data || {};
const series = Array.isArray(data?.series) ? data.series : [];

if (series.length > 0) {
const last = series[series.length - 1];
console.log("Last East Coast Gasoline tick (USD/gal):", last.value);
} else {
console.log("No series[] present; envelope timestamp:", timestamp, "currency:", currency, "unit:", unit);
}
}

run().catch((e) => {
console.error(e);
process.exit(1);
});

Production concerns: idempotency, caching, and pagination

Idempotency: For finance postings, snapshot the full JSON body alongside your journal entry key and request_id (if present in meta). This makes replays idempotent and auditable.

Caching: Cache a single response per batch window (e.g., nightly) to avoid double-counting within the same ledger period and to respect the guest cap (100 requests/day per IP without a key). Consider warming the cache a few minutes before your batch starts so upstream latency does not hold up postings.

Pagination: Where not documented, do not assume pagination. For historical series, always check for the existence of a series array. If you need larger horizons, consult the Documentation before building pagers.

Timezone: Timestamps are UTC (+00:00). Convert to your accounting calendar as needed, but store raw UTC for audit.

Finance integrations: surcharge and exposure mapping

Use the East Coast Gasoline metric as the driver for surcharges applied to loads originating or terminating on the East Coast. Keep national averages split from regional signals to maintain attribution accuracy in your variance analysis.

Cross-checks and guardrails that prevent bad postings

Implement these checks to avoid finance errors:

Re-using the official JSON body for tests

Most teams need at least three fixtures to validate parsers across environments (local, CI, and staging). You can reuse the official sample identically for all three so every environment proves its header, envelope, and numeric parsing before you wire real keys. Here it is again for easy copy.

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

Operational checklist for finance deployment

FAQ

Is the East Coast Gasoline metric live or lagged?

It is sourced from the EIA and should be treated as a benchmark with reporting lag. Use the response timestamp to anchor any postings and avoid portraying it as a live intraday price.

How do I access the API without a key?

You can omit the X-API-Key header and operate as a guest with 100 requests per day per IP. For production finance jobs, use a key to avoid rate-related failures.

What units and currency should I assume?

Prices are denominated in USD per gallon. Confirm via the currency and unit fields in the envelope and propagate those into your GL metadata.

Where is the East Coast gasoline historical series?

No official historical series is published for fuel_price_gasoline_east_coast. Your code should gracefully handle cases where series[] is absent and rely on documented aggregates or policy-driven fallbacks.

Can I use national gasoline averages as a proxy for East Coast?

Do not substitute national aggregates when your finance logic requires the East Coast metric. Keep proxies and actuals explicitly labeled to avoid attribution errors.

Get credentials and ship your finance integration

Stand up your production integration by registering for an API key, reading the field notes above into your code comments, and wiring the endpoint into your nightly finance batch. Create your account via Register, and keep the reference close at hand with the Documentation.