# Fuel Prices API (`khadinakbar/fuel-prices-api`) Actor

Get official U.S. EIA weekly retail gasoline and diesel prices by nation, PADD, state, and city. Returns USD per gallon, week-ending date, and week/year change. HTTP-only, no login. Built for fleet cost tracking, energy research, and AI agents.

- **URL**: https://apify.com/khadinakbar/fuel-prices-api.md
- **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community)
- **Categories:** Travel, Automation, MCP servers
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 fuel price rows

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Fuel Prices API

Pass a U.S. area such as `US`, `California`, `PADD 1`, or `Los Angeles` and get **official EIA weekly retail gasoline and diesel prices** — dollars per gallon, week-ending date, and week/year change. Each dataset row is one location + fuel + week from EIA's Gasoline and Diesel Fuel Update. Designed for fleet cost tracking, energy research, and AI agents that need a structured national average without a login or API key.

This is the EIA weekly survey average. It is not a live gas-station pump price and not a GasBuddy station scrape.

### Best fit for this Actor

- You need the current U.S., PADD, state, or selected-city retail average for regular gasoline or on-highway diesel.
- You want a three-week window from the same official weekly update, with week-over-week and year-ago change on the latest week.
- You are calling this from Apify API, schedules, or MCP and need flat JSON plus a stable `OUTPUT.outcome`.
- For live street-level station prices, start with a station-level fuel Actor instead of this survey API.

### Fleet diesel check for California versus the U.S.

A logistics operator is reviewing next week's California lane costs. They pass `locations: ["US", "California"]` and `fuelType: "diesel"`. The dataset returns two rows: the U.S. on-highway diesel average and the California diesel average, both for the same EIA week ending, plus `changeFromLastWeek`. They compare the California premium to the national row and keep `sourceUrl` as the official citation.

### Quick start input

```json
{
    "locations": ["US", "California"],
    "fuelType": "both",
    "historyWeeks": 1,
    "maxResults": 10
}
```

Empty `locations` returns every area EIA published that week. `maxResults` is the run-wide cost ceiling.

### Input reference

| Field | Type | What it controls |
|---|---|---|
| `locations` | array | U.S. areas such as `US`, `California`, `PADD 1`, or `Los Angeles`. Aliases like `usa`, `nyc`, and `padd5` work. Empty = all published areas. |
| `fuelType` | enum | `regular`, `diesel`, or `both` (default). Midgrade and premium are not on the weekly landing tables. |
| `historyWeeks` | integer | 1–3 recent EIA weekly columns. Default 1 (latest week only). |
| `maxResults` | integer | Run-wide row cap, 1–200. Default 50. Prefill 10. |

### What data you receive

One dataset item is one EIA weekly price for a location, fuel, and week.

```json
{
    "locationName": "California",
    "locationType": "state",
    "locationCode": "CALIFORNIA",
    "fuelType": "regular",
    "fuelLabel": "Regular gasoline",
    "priceUsdPerGallon": 5.678,
    "currency": "USD",
    "unit": "gallon",
    "period": "2026-09-07",
    "periodLabel": "09/07/26",
    "frequency": "weekly",
    "changeFromLastWeek": 0.158,
    "changeFromLastYear": 1.256,
    "source": "eia-gasoline-diesel-update",
    "sourceUrl": "https://www.eia.gov/petroleum/gasdiesel/",
    "retrievedAt": "2026-09-10T00:00:00.000Z"
}
```

`locationType` is `national`, `padd`, `state`, or `city`. Diesel is published for the U.S., PADDs, and California; gasoline also covers selected states and cities.

### Real-world use cases

#### 1. National plus California gasoline

```json
{
    "locations": ["US", "California"],
    "fuelType": "regular",
    "maxResults": 10
}
```

#### 2. On-highway diesel for a fleet lane

```json
{
    "locations": ["US", "California", "PADD 3"],
    "fuelType": "diesel"
}
```

#### 3. City regular gasoline snapshot

```json
{
    "locations": ["Los Angeles", "Houston", "Chicago"],
    "fuelType": "regular"
}
```

#### 4. Three-week history for the U.S.

```json
{
    "locations": ["US"],
    "fuelType": "both",
    "historyWeeks": 3
}
```

#### 5. Full weekly table, capped

```json
{
    "fuelType": "both",
    "maxResults": 50
}
```

Leave `locations` empty to take every national, PADD, state, and city cell EIA published that week, then stop at `maxResults`.

### Why agents choose this Actor

- Official EIA weekly survey, not an unofficial station feed.
- Flat keys (`locationName`, `fuelType`, `priceUsdPerGallon`, `period`, `sourceUrl`) instead of Excel columns.
- `maxResults` is a hard cost ceiling. Unmatched areas such as Boston diesel finish as `VALID_EMPTY` or `PARTIAL` instead of a hollow success.
- Terminal `OUTPUT.outcome` values (`COMPLETE`, `PARTIAL`, `VALID_EMPTY`, `INVALID_INPUT`, `UPSTREAM_FAILED`) are stable enough to branch on.
- No EIA API key and no login. The weekly update page is public HTML.

### Agent checklist

1. Pass U.S. area names or EIA PADD labels. City and ZIP station lookup is out of scope.
2. Set `fuelType` to `regular`, `diesel`, or `both`, and `maxResults` to the number of rows you can bill.
3. After the run, read `OUTPUT.outcome`, then the dataset. Zero rows with `VALID_EMPTY` means EIA did not publish that location/fuel pair.
4. Keep `sourceUrl` as the citation. Prices are weekly averages, not the pump you drive past today.
5. Raise `historyWeeks` to 2 or 3 only when you need the other columns on the same weekly update page.

### Use through the API

```bash
curl "https://api.apify.com/v2/acts/khadinakbar~fuel-prices-api/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "locations": ["US", "California"],
    "fuelType": "both",
    "maxResults": 10
  }'
```

When the Actor completes, read dataset items from the default dataset and the `OUTPUT` record from the default key-value store.

### Use with AI agents through Apify MCP

> Get the latest EIA weekly regular gasoline and on-highway diesel prices for US and California. Return locationName, fuelType, priceUsdPerGallon, period, changeFromLastWeek, and sourceUrl. Then inspect OUTPUT.outcome before summarizing.

Connect through <https://mcp.apify.com>. After the tool call, read the dataset and the `OUTPUT` / `RUN_SUMMARY` records.

### Pricing

This Actor uses Pay per event plus Apify platform usage. Open the live Pricing tab for current event details, and use Apify's run cost controls to keep the workflow aligned with your budget.

The named result event is `fuel-price-row` (one persisted EIA price row) plus `apify-actor-start`. Invalid input and fully empty unmatched queries stay unbilled for the named result charge.

### Outcome vocabulary

These values live in the key-value store records `OUTPUT` and `RUN_SUMMARY`, not on each dataset row.

| Outcome | Meaning |
|---|---|
| `COMPLETE` | Requested locations were processed and useful rows were saved. |
| `PARTIAL` | Some locations missed, or `maxResults` / the event cap stopped the run; saved rows are still in the dataset. |
| `VALID_EMPTY` | The request was valid and EIA had no published cell for that location/fuel pair. |
| `INVALID_INPUT` | The fuel type or input could not be used. No price-row events are charged. |
| `UPSTREAM_FAILED` | The EIA weekly update page did not return usable tables. |

### Connect the workflow

- After you have a city gasoline average, enrich nearby businesses with [Google Maps Leads Scraper](https://apify.com/khadinakbar/google-maps-leads-scraper) when you also need local company contacts.
- To track energy-related equities beside the fuel average, continue with [Stock Price Tracker](https://apify.com/khadinakbar/stock-price-tracker).
- When you also need vehicle listing prices in the same metro as a city gasoline average, continue with [Autotrader Scraper](https://apify.com/khadinakbar/autotrader-scraper).

### Best results

- Use `US` plus the states or cities you actually route through. Empty `locations` is for a full weekly snapshot.
- Choose `diesel` for fleet lanes; EIA publishes diesel for the U.S., PADDs, and California, not every gasoline city.
- Keep `historyWeeks` at 1 unless you need the prior two columns from the same page.
- Cite `sourceUrl`. The weekly update usually posts on Monday for the prior week.

### Builder's note

I built this after reading the live EIA Gasoline and Diesel Fuel Update HTML rather than wiring the registered Open Data API. The landing page already publishes three dated weekly columns plus week/year change, and a GET without an API key is enough for the advertised job. In my testing, diesel city rows such as Boston are simply absent from the diesel table — treating that as `VALID_EMPTY` is more honest than inventing a station price. I also kept midgrade and premium out of the public contract because those grades are not on the weekly landing tables.

### FAQ

**Is this live pump data?**
No. It is EIA's weekly retail survey average. Station-level cash/credit prices are a different product.

**Do I need an EIA API key?**
No. The Actor reads the public weekly update page over HTTP.

**Which locations are included?**
Gasoline: U.S., PADDs, selected states, and selected cities. Diesel: U.S., PADDs, and California. Asking for an unpublished pair returns no billed row.

**Can an AI agent use this?**
Yes. Pass locations and a fuel type, then read one row per price and inspect `OUTPUT.outcome`.

### Responsible use

This Actor returns public U.S. government fuel-price statistics for research, planning, and enrichment. Treat the output as weekly survey averages, keep request volume courteous to EIA, and use results in line with EIA copyright and reuse policy and applicable laws. It is not a substitute for a regulated energy-market feed or a live station price.

EIA and U.S. Energy Information Administration are trademarks of their respective owners. GasBuddy is a trademark of its owner. This independent Actor is not affiliated with, associated with, or endorsed by EIA or GasBuddy.

# Actor input Schema

## `locations` (type: `array`):

U.S. areas to return, such as US, California, PADD 1, or Los Angeles. Aliases like usa, nyc, and padd5 are accepted. Leave empty to return every area EIA published that week. This is not a street address or a live gas-station search.

## `fuelType` (type: `string`):

Which EIA weekly product to return. regular is all-formulations retail gasoline; diesel is on-highway diesel; both returns both products when EIA publishes that location. Default both. Midgrade and premium grades are not on the weekly update landing tables.

## `historyWeeks` (type: `integer`):

How many of the three most recent EIA weekly columns to keep. 1 (default) is the latest week only; 3 returns the full three-week window shown on the Gasoline and Diesel Fuel Update. This is not a multi-year history download.

## `maxResults` (type: `integer`):

Hard cap on dataset rows for the run. Default 50. Each saved row is one fuel-price-row event. Use this as the cost ceiling; it is not pagination into a previous run.

## Actor input object example

```json
{
  "locations": [
    "US",
    "California"
  ],
  "fuelType": "both",
  "historyWeeks": 1,
  "maxResults": 10
}
```

# Actor output Schema

## `results` (type: `string`):

Dataset items containing location, fuel type, USD per gallon, week-ending date, and week/year change when EIA published them.

## `summary` (type: `string`):

Run summary including outcome, itemsPushed, unmatched locations, EIA status, warnings, and billing counters.

## `runSummary` (type: `string`):

Machine-readable RUN\_SUMMARY record mirroring OUTPUT for integrations that read RUN\_SUMMARY directly.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "locations": [
        "US",
        "California"
    ],
    "fuelType": "both",
    "historyWeeks": 1,
    "maxResults": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("khadinakbar/fuel-prices-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "locations": [
        "US",
        "California",
    ],
    "fuelType": "both",
    "historyWeeks": 1,
    "maxResults": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("khadinakbar/fuel-prices-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "locations": [
    "US",
    "California"
  ],
  "fuelType": "both",
  "historyWeeks": 1,
  "maxResults": 10
}' |
apify call khadinakbar/fuel-prices-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,khadinakbar/fuel-prices-api"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/fyidDRAQhhbCB6zCa/builds/hJJSOPNudiffEeyUJ/openapi.json