# Fuel Prices Scraper (`crawlerbros/fuel-prices-scraper`) Actor Daily US fuel prices (regular, mid-grade, premium, diesel) at national, state, and metro level. HTTP-only, no proxy, no auth. Filters: states allowlist, fuelTypes, minPrice/maxPrice, sortBy. Source: AAA Fuel Gauge. - **URL**: https://apify.com/crawlerbros/fuel-prices-scraper.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Developer tools, Automation, Other - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 13 bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing from $1.00 / 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/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 Scraper Daily US fuel prices from the [AAA Fuel Gauge](https://gasprices.aaa.com/). National, state (50 + DC), and metro/county averages for regular, mid-grade, premium, and diesel — with current/yesterday/week/month/year-ago history. HTTP-only — no cookies, no proxy, no auth. ### What this actor does - Fetches the public AAA Fuel Gauge pages - Parses national, state, and metro-level fuel prices - Returns one record per scope (1 national / 51 state / hundreds of metro records) - Includes price history (yesterday / week ago / month ago / year ago) and derived change metrics (in cents) - Pro filters narrow output to specific states, fuel types, price bands, or metro substring matches ### Modes | Mode | What it does | |---|---| | `national` | 1 record — current US national average for all 4 fuel grades | | `state` (default) | 51 records — current + history for each of 50 states + DC | | `metro` | Per-state metro/county tables (~200+ records when no state filter is set) | ### Output per record State / metro records include: - `scope` (`national` / `state` / `metro`) - `country` (national only — always `US`) - `state`, `stateCode` (state and metro records) - `metro` (metro records only) - `regular`, `midGrade`, `premium`, `diesel` (USD/gal — only fuels actually published) - `history` (object — `yesterday` / `weekAgo` / `monthAgo` / `yearAgo` × fuel grade) - `changeFromYesterday`, `changeFromWeekAgo`, `changeFromMonthAgo`, `changeFromYearAgo` (cents — computed from `primaryFuelType`, default `regular`) - `recordType: "fuelPrices"`, `scrapedAt` Empty fields are omitted from the output (no nulls). ### Input | Field | Type | Default | Description | |---|---|---|---| | `mode` | enum | `state` | `national` / `state` / `metro` | | `states` | array | `[]` | Two-letter state codes or full names — e.g. `["NY","CA"]` or `["New York","California"]`. Empty = all 50 + DC | | `fuelTypes` | array | all four | Subset of `regular` / `midGrade` / `premium` / `diesel`. Drops other grades from each record | | `includeHistory` | bool | `true` | Include yesterday/week-ago/month-ago/year-ago averages | | `includeChangeMetrics` | bool | `true` | Compute `changeFromYesterday` etc. (in cents) for the primary fuel | | `minPrice` | number | – | Drop records whose primary fuel is below this price | | `maxPrice` | number | – | Drop records whose primary fuel is above this price | | `primaryFuelType` | enum | `regular` | Which fuel grade `minPrice`/`maxPrice`/sort/change use | | `sortBy` | enum | `state_asc` | `price_asc` / `price_desc` / `state_asc` | | `metroNameFilter` | array | `[]` | Only emit metro records whose name contains one of these substrings (case-insensitive) | | `maxItems` | int | `500` | Hard cap on emitted records | #### Example: state averages ```json { "mode": "state", "states": [], "includeHistory": true, "includeChangeMetrics": true, "sortBy": "price_asc" } ```` #### Example: metros in NY + CA ```json { "mode": "metro", "states": ["NY", "CA"], "metroNameFilter": ["new york", "los angeles", "san francisco"] } ``` #### Example: cheapest diesel by state ```json { "mode": "state", "primaryFuelType": "diesel", "fuelTypes": ["diesel"], "sortBy": "price_asc", "maxItems": 10 } ``` ### Use cases - **Fleet planning** — compare diesel prices across states for routing - **News + editorial** — daily "where gas is cheapest" digest, broken out by state and metro - **Consumer apps** — power a "national fuel price" widget with one daily run - **Trend tracking** — monitor `changeFromYearAgo` to flag big YoY moves - **Inflation dashboards** — fuel is a leading retail-inflation indicator ### FAQ **Does it require a login or cookies?** No. The AAA Fuel Gauge is fully public. **Is a proxy needed?** No. Datacenter IPs work fine. **Does it cover countries other than the US?** Not yet. AAA's Fuel Gauge is US-only. **Why aren't station-level (per-pump) prices included?** Per-station data sources (e.g. GasBuddy) are heavily rate-limited and blocked from datacenter IPs. State + metro aggregates from AAA are the most reliable, free, datacenter-friendly source. **How fresh is the data?** AAA updates daily (overnight). The actor reads the page directly so each run reflects the latest published averages. **Why do some states miss a fuel grade?** Some states don't publish every grade. The omit-empty contract drops missing fields rather than emit nulls. **Why is `changeFromMonthAgo` sometimes missing?** It's computed only when both current price and the relevant history bucket are present. **What does `metroNameFilter` match against?** Case-insensitive substring of the metro/county 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 } ``` # 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 '' with your token const client = new ApifyClient({ 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("crawlerbros/fuel-prices-scraper").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 '' with your token. client = ApifyClient("") # 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("crawlerbros/fuel-prices-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).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 crawlerbros/fuel-prices-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/fuel-prices-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Fuel Prices Scraper", "description": "Daily US fuel prices (regular, mid-grade, premium, diesel) at national, state, and metro level. HTTP-only, no proxy, no auth. Filters: states allowlist, fuelTypes, minPrice/maxPrice, sortBy. Source: AAA Fuel Gauge.", "version": "1.0", "x-build-id": "pm95udYAU64G965cK" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~fuel-prices-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-fuel-prices-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/crawlerbros~fuel-prices-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-fuel-prices-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/crawlerbros~fuel-prices-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-fuel-prices-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "title": "Mode", "enum": [ "national", "state", "metro" ], "type": "string", "description": "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.", "default": "state" }, "states": { "title": "States allowlist", "type": "array", "description": "Two-letter state codes (e.g. `NY`, `CA`, `TX`). Empty = all 50 states + DC. For `mode=metro`, this controls which state pages get scraped.", "default": [], "items": { "type": "string" } }, "fuelTypes": { "title": "Fuel types", "type": "array", "description": "Which fuel grades to include in each record. Empty = all four (regular, midGrade, premium, diesel).", "items": { "type": "string", "enum": [ "regular", "midGrade", "premium", "diesel" ], "enumTitles": [ "Regular", "Mid-grade", "Premium", "Diesel" ] }, "default": [ "regular", "midGrade", "premium", "diesel" ] }, "includeHistory": { "title": "Include price history", "type": "boolean", "description": "When true (state/metro modes), include yesterday/week-ago/month-ago/year-ago averages. Default true.", "default": true }, "minPrice": { "title": "Min price (USD/gal)", "minimum": 0, "maximum": 20, "type": "number", "description": "Drop records whose primary fuel (regular by default) is below this price." }, "maxPrice": { "title": "Max price (USD/gal)", "minimum": 0, "maximum": 20, "type": "number", "description": "Drop records whose primary fuel (regular by default) is above this price." }, "primaryFuelType": { "title": "Primary fuel type for filters/sort", "enum": [ "regular", "midGrade", "premium", "diesel" ], "type": "string", "description": "Which fuel grade is used by `minPrice` / `maxPrice` / `sortBy` filters. Default: regular.", "default": "regular" }, "sortBy": { "title": "Sort by", "enum": [ "price_asc", "price_desc", "state_asc" ], "type": "string", "description": "How to order emitted records. Cheapest-first / most-expensive-first / alphabetical by state.", "default": "state_asc" }, "includeChangeMetrics": { "title": "Include derived change metrics", "type": "boolean", "description": "When true and history is fetched, also emit `changeFromYesterday`, `changeFromWeekAgo`, `changeFromMonthAgo`, `changeFromYearAgo` (in cents).", "default": true }, "metroNameFilter": { "title": "Metro name filter (mode=metro only)", "type": "array", "description": "Only emit metro records whose name contains one of these substrings (case-insensitive). e.g. ['New York','Los Angeles'].", "default": [], "items": { "type": "string" } }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Hard cap on emitted records.", "default": 500 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```