# Gas Prices API - US Gasoline & Diesel by State, Weekly Histo (`martin10291/us-gas-prices-api`) Actor

Official US gas prices as JSON, no API key: weekly retail regular, midgrade, premium gasoline and diesel prices (USD/gallon) for the US, 10 PADD regions, 9 states and 10 cities from the EIA survey, with week-over-week and year-over-year change, 52-week high/low, history since 1990 (weekly, monthly o

- **URL**: https://apify.com/martin10291/us-gas-prices-api.md
- **Developed by:** [Martin Petrov](https://apify.com/martin10291) (community)
- **Categories:** Travel, Developer tools, Automation
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.70 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Gas Prices API - US Gasoline & Diesel by State, Weekly History

**Problem:** your fleet app, trip-cost calculator, fintech dashboard, newsroom or AI agent needs today's US gas price for a state or city, the diesel price for a trucking region, or a clean price history. Station-price sites forbid scraping, and the official EIA numbers come as Excel workbooks with 179,000 cells and cryptic series codes.

**This API:** one JSON call, no API key, answers from a maintained copy of the official EIA weekly survey (updated every week, release date on every row).

- **Fuels:** `regular`, `midgrade`, `premium`, `allGrades` gasoline and `diesel` (on-highway No 2), USD per gallon including taxes.
- **Areas (29):** US average, 10 PADD regions (`PADD1` East Coast ... `PADD5` West Coast, `PADD5XCA`), 9 states (`CA`, `CO`, `FL`, `MA`, `MN`, `NY`, `OH`, `TX`, `WA`), 10 cities (`BOS`, `CHI`, `CLE`, `DEN`, `HOU`, `LAX`, `MIA`, `NYC`, `SFO`, `SEA`). Names work too (`California`, `Midwest`, `New York City`).
- **latest:** price, week-over-week and year-over-year change (USD and %), 52-week high/low, difference to the US average; `sort` = cheapest / most expensive / biggest weekly rise.
- **history:** weekly since 1990 (gasoline) / 1994 (diesel), or `monthly` / `yearly` averages.
- **trip:** fuel cost of a trip from `distanceMiles` or `distanceKm` and `mpg` or `litersPer100km`, per area, cheapest first.
- **Monitor:** `onlyNew` + `monitorId` returns each new weekly release once (schedule it weekly).

### Example (API)

```bash
curl -X POST "https://api.apify.com/v2/acts/martin10291~us-gas-prices-api/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "latest", "areas": ["US", "CA", "NYC"], "fuels": ["regular", "diesel"]}'
```

Output row (measured 2026-11-13, EIA release 2026-11-10):

```json
{"area": "CA", "areaName": "California", "areaType": "state", "fuel": "regular", "week": "2026-11-09", "price": 5.562,
 "previousWeekPrice": 5.748, "changeWeek": -0.186, "changeWeekPct": -3.24, "yearAgoPrice": 4.5, "changeYear": 1.062,
 "high52w": 6.227, "low52w": 3.977, "vsNational": 1.567, "historyFrom": "2000-06-05", "unit": "USD per gallon (retail, including taxes)",
 "releaseDate": "2026-11-10", "nextReleaseDate": "2026-11-17",
 "source": "Source: U.S. Energy Information Administration, Gasoline and Diesel Fuel Update (2026-11-10), public domain"}
```

More inputs:

- `{"mode": "history", "areas": ["US"], "fuels": ["diesel"], "startDate": "2020-01-01", "interval": "monthly"}` -> monthly average diesel price.
- `{"mode": "latest", "fuels": ["regular"], "sort": "priceAsc"}` -> every area, cheapest first.
- `{"mode": "trip", "areas": ["TX", "CA"], "distanceKm": 500, "litersPer100km": 7}` -> trip cost per area.
- `{"mode": "areas"}` -> covered areas, fuels and first week.

### Use from agents (MCP)

Add the Apify MCP server (`https://mcp.apify.com?tools=martin10291/us-gas-prices-api`) to Claude, Cursor or any MCP client and ask: "What does regular gas cost in California this week, and how much did it change in a year?".

### Data source

U.S. Energy Information Administration (EIA), Gasoline and Diesel Fuel Update (https://www.eia.gov/petroleum/gasdiesel/). EIA content is public domain; every row carries the acknowledgment with the release date as EIA asks. EIA surveys retail stations every Monday and publishes on Monday/Tuesday. No scraping, no personal data.

### FAQ

- **How fresh is the data?** EIA surveys stations every Monday and publishes Monday/Tuesday; our copy refreshes every 3 hours, so a new week appears within hours of the release. `releaseDate` and `nextReleaseDate` are on every row; if EIA is down the last copy is served with `"stale": true`.
- **Limits:** up to 60 areas and 20,000 rows per call (`limit`, default 1000). Diesel exists for US, PADD regions, CA and PADD5XCA only (EIA does not publish other diesel areas).
- **Errors:** an unknown area, fuel, mode or a bad date returns a clear `invalid input` message with the valid values; nothing is charged for an error.
- **Station prices?** No: this is the official weekly average per area (what news and government reports quote), not a per-station feed.

### Pricing

$1.00 per 1,000 rows. A `latest` call for one state and fuel = 1 row.

# Actor input Schema

## `mode` (type: `string`):

latest = newest weekly price per area and fuel with weekly/yearly change and 52-week high/low; history = price series between startDate and endDate (weekly, or monthly/yearly averages); trip = fuel cost of a trip from distance and fuel economy at the current local price; areas = list of covered areas, fuels and first week.

## `areas` (type: `array`):

US, PADD1..PADD5 (East Coast, Midwest, Gulf Coast, Rocky Mountain, West Coast), PADD1A/1B/1C, PADD5XCA, states CA CO FL MA MN NY OH TX WA, cities BOS CHI CLE DEN HOU LAX MIA NYC SFO SEA, or names like 'California' / 'New York City'. 'all' = every area. Empty = all areas for latest, US for history and trip.

## `fuels` (type: `array`):

regular, midgrade, premium, allGrades, diesel ('all' = every fuel). Empty = regular + diesel for latest, regular for history and trip. Diesel is published for US, PADD regions, CA and PADD5XCA.

## `sort` (type: `string`):

latest mode: area order (default), cheapest first, most expensive first, or biggest weekly rise first.

## `startDate` (type: `string`):

history mode: first week, YYYY-MM-DD (or YYYY / YYYY-MM). Default one year ago. Gasoline from 1990/1994, diesel from 1994.

## `endDate` (type: `string`):

history mode: last week, YYYY-MM-DD. Default latest.

## `interval` (type: `string`):

history mode: weekly survey values, or monthly / yearly averages of the weekly values.

## `distanceMiles` (type: `number`):

trip mode: trip distance in miles (or use distanceKm).

## `distanceKm` (type: `number`):

trip mode: trip distance in kilometers (used when distanceMiles is empty).

## `mpg` (type: `number`):

trip mode: vehicle fuel economy in US mpg. Default 25 when litersPer100km is also empty.

## `litersPer100km` (type: `number`):

trip mode: fuel economy in L/100 km (used when mpg is empty).

## `limit` (type: `integer`):

Maximum rows returned (1-20000). Default 1000.

## `onlyNew` (type: `boolean`):

Return only rows not returned before for this Monitor ID, e.g. schedule weekly to get each new EIA release once.

## `monitorId` (type: `string`):

Name of the monitor state used by onlyNew. Different IDs keep separate memories.

## Actor input object example

```json
{
  "mode": "latest",
  "areas": [
    "US",
    "CA",
    "TX",
    "NYC"
  ],
  "fuels": [
    "regular",
    "diesel"
  ],
  "sort": "area",
  "interval": "weekly",
  "limit": 1000,
  "onlyNew": false
}
```

# Actor output Schema

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

latest: one row per area and fuel with price, weekly/yearly change, 52-week high/low and difference to the US average; history: one row per area, fuel and week (or month/year); trip: trip cost per area; areas: coverage list. Every row carries the EIA source and release date.

# 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 = {
    "mode": "latest",
    "areas": [
        "US",
        "CA",
        "TX",
        "NYC"
    ],
    "fuels": [
        "regular",
        "diesel"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("martin10291/us-gas-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 = {
    "mode": "latest",
    "areas": [
        "US",
        "CA",
        "TX",
        "NYC",
    ],
    "fuels": [
        "regular",
        "diesel",
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("martin10291/us-gas-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 '{
  "mode": "latest",
  "areas": [
    "US",
    "CA",
    "TX",
    "NYC"
  ],
  "fuels": [
    "regular",
    "diesel"
  ]
}' |
apify call martin10291/us-gas-prices-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,martin10291/us-gas-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/eXw1d5lJ6J5S1rv7E/builds/yfBKYiF3WD2Gi6bya/openapi.json