# US Gas Price Tracker by State & Metro (`dataspryva/us-gas-price-tracker-by-state-and-metro`) Actor

Daily US fuel prices for regular, mid-grade, premium, and diesel at the national, state, and metro level, with yesterday/week/month/year-ago history and derived price changes.

- **URL**: https://apify.com/dataspryva/us-gas-price-tracker-by-state-and-metro.md
- **Developed by:** [Dataspryva](https://apify.com/dataspryva) (community)
- **Categories:** Automation, Travel, Developer tools
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
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

## US Gas Price Tracker by State & Metro

Get daily US gas and diesel prices without visiting a fuel-price site yourself. This actor reads the public AAA Fuel Gauge data and returns it as structured records at whichever level you need: one national figure, all 50 states plus DC, or metro/county breakdowns within specific states.

### What this actor does

- **Three scopes:** a single national average, state-level averages (50 states + DC), or metro/county averages within chosen states
- **Four fuel grades:** regular, mid-grade, premium, and diesel, each only included when the source actually publishes it
- **Historical comparison:** yesterday, week-ago, month-ago, and year-ago prices alongside today's, plus derived cent-value changes for a chosen primary fuel
- **Narrowing filters:** by state, by fuel grade, by a price band on the primary fuel, and by metro-name substring
- **Empty fields are omitted** — a record only includes the fuel grades and history buckets the source actually published for it

### Output per record

- `scope` — `national`, `state`, or `metro`
- `country` — always `US`, present only on national records
- `state`, `stateCode` — state name and two-letter code, present on state and metro records
- `metro` — metro/county area name, present only on metro records
- `regular`, `midGrade`, `premium`, `diesel` — current price in USD/gallon for each grade the source publishes
- `history` — an object with `yesterday`, `weekAgo`, `monthAgo`, and `yearAgo` prices per fuel grade, when `includeHistory` is enabled (state/metro modes) or whenever the source publishes it on the home page (national mode, where `includeHistory` isn't consulted)
- `changeFromYesterday`, `changeFromWeekAgo`, `changeFromMonthAgo`, `changeFromYearAgo` — price change in cents for the chosen `primaryFuelType`, when `includeChangeMetrics` is enabled and the matching history value exists
- `recordType` — always `fuelPrices`
- `scrapedAt` — when the record was fetched

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | string | `state` | `national` (1 record), `state` (50 + DC), or `metro` (per-state metro/county averages) |
| `states` | array | `[]` | Two-letter state codes to include (e.g. `NY`, `CA`). Empty includes all 50 states + DC. For `mode=metro`, this also controls which states' metro pages are read |
| `fuelTypes` | array | `["regular","midGrade","premium","diesel"]` | Which fuel grades to include in each record |
| `includeHistory` | boolean | `true` | Include yesterday/week-ago/month-ago/year-ago prices (state/metro modes) |
| `minPrice` | number | – | Drop records whose primary fuel is priced below this value |
| `maxPrice` | number | – | Drop records whose primary fuel is priced above this value |
| `primaryFuelType` | string | `regular` | Which fuel grade `minPrice`, `maxPrice`, `sortBy`, and the change metrics use |
| `sortBy` | string | `state_asc` | `price_asc`, `price_desc`, or `state_asc` |
| `includeChangeMetrics` | boolean | `true` | Compute `changeFromYesterday`/`changeFromWeekAgo`/`changeFromMonthAgo`/`changeFromYearAgo` in cents, when history is available |
| `metroNameFilter` | array | `[]` | Only emit metro records whose name contains one of these substrings (mode=metro only) |
| `maxItems` | integer | `500` | Hard cap on emitted records (1–5000) |

#### Example: all states, cheapest first

```json
{
  "mode": "state",
  "sortBy": "price_asc",
  "includeHistory": true
}
```

#### Example: metro breakdown for two states

```json
{
  "mode": "metro",
  "states": ["NY", "CA"],
  "metroNameFilter": ["new york", "los angeles", "san francisco"]
}
```

#### Example: cheapest diesel states only

```json
{
  "mode": "state",
  "primaryFuelType": "diesel",
  "fuelTypes": ["diesel"],
  "sortBy": "price_asc",
  "maxItems": 10
}
```

### Use cases

- **Fleet and logistics planning** — compare diesel prices across states before routing
- **News and editorial research** — pull a "cheapest gas by state" snapshot on demand
- **Consumer price widgets** — feed a national or regional average into a dashboard
- **Trend monitoring** — watch `changeFromYearAgo` to catch large year-over-year price swings
- **Economic analysis** — fuel prices as an input to broader cost-of-living or inflation tracking

### FAQ

**Where does this data come from?**
The public AAA Fuel Gauge pages, the same averages AAA publishes for national, state, and metro-level gas prices.

**Do I need a login, cookies, or proxy?**
No. The source pages are fully public and the actor reads them without authentication.

**Does this cover countries outside the US?**
No, this is US-only; the underlying source does not publish averages for other countries.

**Why isn't per-station pricing included?**
This actor reports state and metro averages rather than individual gas-station prices, since AAA's own data is published at that level.

**How current is the data?**
AAA refreshes its averages daily, and each run reads the page live, so results reflect whatever AAA has published at run time.

**Why might a record be missing a fuel grade?**
Not every state or metro area has a published price for every grade (mid-grade and premium especially). The actor omits a grade from a record rather than sending a null or zero value.

**Why is a change metric like `changeFromMonthAgo` sometimes absent?**
It's only computed when both the current price and the matching history value are available for that record's primary fuel.

**What does `metroNameFilter` match against?**
A case-insensitive substring match against the metro/county area name as published by AAA (e.g. `Albany-Schenectady-Troy`, `Nassau-Suffolk`).

# Actor input Schema

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

What to scrape. `national` = single record (US average). `state` = 51 records (50 states + DC) with current/yesterday/week/month/year-ago prices. `metro` = metro/county-level prices for the requested states.

## `states` (type: `array`):

Two-letter state codes (e.g. `NY`, `CA`, `TX`). Empty = all 50 states + DC. For `mode=metro`, this controls which state pages get scraped.

## `fuelTypes` (type: `array`):

Which fuel grades to include in each record. Empty = all four (regular, midGrade, premium, diesel).

## `includeHistory` (type: `boolean`):

When true (state/metro modes), include yesterday/week-ago/month-ago/year-ago averages. Default true.

## `minPrice` (type: `number`):

Drop records whose primary fuel (regular by default) is below this price.

## `maxPrice` (type: `number`):

Drop records whose primary fuel (regular by default) is above this price.

## `primaryFuelType` (type: `string`):

Which fuel grade is used by `minPrice` / `maxPrice` / `sortBy` filters. Default: regular.

## `sortBy` (type: `string`):

How to order emitted records. Cheapest-first / most-expensive-first / alphabetical by state.

## `includeChangeMetrics` (type: `boolean`):

When true and history is fetched, also emit `changeFromYesterday`, `changeFromWeekAgo`, `changeFromMonthAgo`, `changeFromYearAgo` (in cents).

## `metroNameFilter` (type: `array`):

Only emit metro records whose name contains one of these substrings (case-insensitive). e.g. \['New York','Los Angeles'].

## `maxItems` (type: `integer`):

Hard cap on emitted records.

## Actor input object example

```json
{
  "mode": "state",
  "states": [],
  "fuelTypes": [
    "regular",
    "midGrade",
    "premium",
    "diesel"
  ],
  "includeHistory": true,
  "primaryFuelType": "regular",
  "sortBy": "state_asc",
  "includeChangeMetrics": true,
  "metroNameFilter": [],
  "maxItems": 500
}
```

# Actor output Schema

## `fuelPrices` (type: `string`):

Dataset containing all scraped US fuel price records.

# 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": "state",
    "states": [],
    "fuelTypes": [
        "regular",
        "midGrade",
        "premium",
        "diesel"
    ],
    "includeHistory": true,
    "primaryFuelType": "regular",
    "sortBy": "state_asc",
    "includeChangeMetrics": true,
    "metroNameFilter": [],
    "maxItems": 500
};

// Run the Actor and wait for it to finish
const run = await client.actor("dataspryva/us-gas-price-tracker-by-state-and-metro").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": "state",
    "states": [],
    "fuelTypes": [
        "regular",
        "midGrade",
        "premium",
        "diesel",
    ],
    "includeHistory": True,
    "primaryFuelType": "regular",
    "sortBy": "state_asc",
    "includeChangeMetrics": True,
    "metroNameFilter": [],
    "maxItems": 500,
}

# Run the Actor and wait for it to finish
run = client.actor("dataspryva/us-gas-price-tracker-by-state-and-metro").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": "state",
  "states": [],
  "fuelTypes": [
    "regular",
    "midGrade",
    "premium",
    "diesel"
  ],
  "includeHistory": true,
  "primaryFuelType": "regular",
  "sortBy": "state_asc",
  "includeChangeMetrics": true,
  "metroNameFilter": [],
  "maxItems": 500
}' |
apify call dataspryva/us-gas-price-tracker-by-state-and-metro --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,dataspryva/us-gas-price-tracker-by-state-and-metro"
        }
    }
}
```

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/i0pJ7pbD6yKWoYc8s/builds/WGBnikzS50WwGLCOA/openapi.json
