Home → Blog

You need a reliable, finance-grade way to fetch the official diesel fuel price fixture as JSON so your surcharge formulas, budgets, or risk dashboards use a consistent source of truth. By the end of this guide, you will make a successful first request to the FreightPulse Fuel Prices API, parse the canonical fields, and integrate them into a finance workflow without guessing fields or formats.

What you will implement

This guide is a first-request walkthrough that gets you from zero to a working call against the FreightPulse Finance metric “Fuel Prices,” returning the official JSON fixture you will reference in your models. You will:

Every step below uses only the documented endpoint, fields, and behaviors, so you can copy and paste with confidence.

Endpoint and authentication

The Fuel Prices Finance metric is available at a single endpoint:

All responses use a consistent envelope: {"success":true,"data":{...}}. You will read your required fields from data.

Data dictionary for finance workflows

The fixture exposes the diesel price and related aggregates you will most likely need for finance calculations:

Units and source of record:

Important constraint for finance users: Do not quote a freight-rates USD fare as today’s price using this endpoint; it is specifically the Fuel Prices metric (diesel). When modeling freight spend, keep fares separate from fuel price indexing.

Make your first request (curl)

Copy and run the following command. It includes the documented authentication header and calls the single Fuel Prices endpoint:

curl -H "X-API-Key: YOUR_API_KEY" "https://freightpulsehq.com/api/v1/fuel-prices"

If you do not supply a key, your IP is limited to 100 requests per day. For production finance jobs, use an API key to avoid silent throttling during end-of-month close or daily batch windows. You can create a key after you Register.

Sample JSON response and field mapping

The following response illustrates the documented fields and envelope. Values are illustrative and not live prices:

{
"success": true,
"data": {
"diesel": {
"national_average": 4.21,
"change_week": -0.03,
"regions": {
"california": 5.15
},
"historical": {
"30d_avg": 4.27
}
}
}
}

How to use these fields in finance contexts:

Minimal Python example

This Python snippet calls the same endpoint, checks the envelope, and extracts the core finance fields for downstream calculations:

import requests

API_URL = "https://freightpulsehq.com/api/v1/fuel-prices"
headers = {
"X-API-Key": "YOUR_API_KEY"
}

resp = requests.get(API_URL, headers=headers, timeout=10)
resp.raise_for_status()
payload = resp.json()

if not payload.get("success"):
raise RuntimeError("Fuel Prices API returned success=false")

data = payload.get("data", {})
diesel = data.get("diesel", {})

national_avg = diesel.get("national_average")
weekly_change = diesel.get("change_week")
regions = diesel.get("regions", {})
california = regions.get("california")
historical = diesel.get("historical", {})
avg_30d = historical.get("30d_avg")

# Example: decide which value to index in your finance model
if national_avg is None:
raise ValueError("Missing diesel.national_average from Fuel Prices fixture")

print({
"national_average_usd_per_gallon": national_avg,
"change_week_usd_per_gallon": weekly_change,
"california_usd_per_gallon": california,
"avg_30d_usd_per_gallon": avg_30d
})

How to wire these fields into finance formulas

This section shows where each field typically lands in finance logic. Replace the model specifics with your organization’s policy; do not substitute this with a freight fare.

Governance tip: Keep the input fixture (the JSON you fetch) immutable in storage to support audit trails for close reviews and external audit sampling.

Units, currency, and accuracy notes

Every numeric fuel price value in this fixture is denominated in USD per gallon, with the source noted as EIA. Build unit tests that assert both currency and unit to avoid silent regressions if your pipeline ever ingests an incompatible data source.

Do not re-interpret this endpoint as a live freight fare or a live congestion proxy. The Fuel Prices metric is separate from freight fares; keep those models distinct. Additionally, where your finance suite references congestion alongside fuel (for scenario analysis), note that port congestion in this catalog is sourced from IMF PortWatch, lagged approximately 6–7 days and based on a 7-day average versus a 90-day baseline (not live AIS). Keep that lag in mind when pairing congestion insights with weekly diesel changes.

Caching and refresh strategy

Because fuel-linked finance jobs often run on fixed schedules (daily or weekly), you should:

Guest usage is capped at 100 requests per day per IP. If your finance workflows involve multiple environments (dev, CI, prod), count aggregate calls against this limit or use an API key in each environment to avoid unplanned throttling.

Error handling and envelope validation

Always check the top-level envelope before reading nested fields:

If you encounter unexpected shapes, note the time, the run context (e.g., close vs. forecast), and halt mutation of your finance data until the response validates. This prevents tainting your subledgers with partial inputs.

Non-functional considerations for Finance teams

JavaScript example (Node.js, fetch)

If you prefer JavaScript, this snippet demonstrates the same minimal extraction against the official fixture:

import fetch from "node-fetch";

const API_URL = "https://freightpulsehq.com/api/v1/fuel-prices";

async function getFuelPrices() {
const res = await fetch(API_URL, {
method: "GET",
headers: { "X-API-Key": "YOUR_API_KEY" }
});

if (!res.ok) {
throw new Error(`HTTP ${res.status}`);
}

const payload = await res.json();

if (!payload.success) {
throw new Error("Fuel Prices API returned success=false");
}

const diesel = payload.data?.diesel || {};
const nationalAverage = diesel.national_average;
const weeklyChange = diesel.change_week;
const california = diesel.regions?.california;
const avg30d = diesel.historical?.["30d_avg"];

if (nationalAverage == null) {
throw new Error("Missing diesel.national_average");
}

return {
national_average_usd_per_gallon: nationalAverage,
change_week_usd_per_gallon: weeklyChange,
california_usd_per_gallon: california,
avg_30d_usd_per_gallon: avg30d
};
}

getFuelPrices()
.then(console.log)
.catch(err => {
console.error("Failed to fetch Fuel Prices:", err);
process.exit(1);
});

Testing strategy that avoids rework at month-end

Operational runbook notes

When the job fails to parse the envelope or diesel.national_average is missing:

Where your finance team pairs fuel exposure with congestion or other operational indicators, remember the provided congestion metric is lagged by ~6–7 days and is a 7-day average versus a 90-day baseline, sourced from IMF PortWatch—not live AIS. Align analysis windows accordingly to prevent mismatched time bases in scenario models.

Common pitfalls to avoid

FAQ

Is there pagination on this endpoint?

No pagination is required for this fixture. The documented response is a small, single-object payload.

How often does the price update?

The guide does not specify an update schedule in the fixture itself. Treat the endpoint as providing the latest available EIA-sourced dataset and archive each pull with your system’s timestamp for auditability.

What units and currency should I model in my ledger?

All prices are USD per gallon. Do not convert unless your policy explicitly calls for a different presentation currency or unit.

Can I access the API without a key?

Yes, as a guest you are limited to 100 requests per day per IP. For batch jobs or month-end close, create an API key to avoid rate-related interruptions.

Does the response include live congestion or freight fare data?

No. This endpoint is strictly the Fuel Prices Finance metric. Do not treat it as a live congestion or freight fare source. Where referenced, congestion data is IMF PortWatch-based and lagged ~6–7 days.

Ready to wire the official Fuel Prices fixture into your finance models? Create your key and start integrating today: Register. For field-by-field references and additional context, see the Documentation.