# AAA Fuel Prices Scraper (`automation-lab/aaa-fuel-prices-scraper`) Actor Scrape AAA fuel price averages for US states and metro areas. - **URL**: https://apify.com/automation-lab/aaa-fuel-prices-scraper.md - **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community) - **Categories:** Travel, Automation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per event 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/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 ## AAA Fuel Prices Scraper Scrape public AAA Fuel Prices data for national, state, and metro gasoline price averages in the United States. ### What this actor does AAA Fuel Prices Scraper collects fuel price average records from AAA's public fuel price website. It is designed for logistics teams, fleet operators, travel planners, analysts, and monitoring workflows that need repeatable fuel-price snapshots. ### Data source The actor reads public pages from `https://gasprices.aaa.com`. No login is required. No API key is required. No browser automation is used. ### Main source page The main state averages page is: `https://gasprices.aaa.com/state-gas-price-averages/` This page includes current regular, mid-grade, premium, and diesel averages for US states and DC. ### State detail pages For each state, AAA publishes a detail page such as: `https://gasprices.aaa.com/?state=CA` State pages can include historical comparison rows and metro-area averages. ### Typical use cases Track daily state fuel averages. Monitor metro fuel prices for routing and dispatch decisions. Compare diesel prices across operating regions. Feed dashboards for travel-cost planning. Archive recurring price snapshots for analysis. Build alerts when a state or metro changes above a threshold. ### Input overview You can run a broad state-average scrape or narrow the run to selected states. The default prefill targets a few common states and enables detail collection. Use `maxItems` to limit the number of dataset records. ### State codes Use two-letter state codes such as `CA`, `TX`, `NY`, or `FL`. Leave the list empty to collect all state averages from the main table. When detail collection is enabled, selected state codes also control which state pages are visited. ### Scrape modes `stateAverages` collects the national/current state table only. `stateDetails` adds historical comparison rows from selected state pages. `all` collects current state averages, historical rows, and metro averages. ### Metro areas When `includeMetroAreas` is enabled, the actor reads AAA metro tables from state pages. Metro rows use `locationType = metro`. Metro output includes the parent `stateCode` and `stateName`. ### Historical averages When `includeHistoricalAverages` is enabled, the actor collects comparison periods where AAA publishes them. Supported period labels are normalized to: `current` `yesterday` `week_ago` `month_ago` `year_ago` ### Output overview Each dataset item is one fuel-price average record. Records can represent the whole United States, a state, or a metro area. All prices are numeric USD-per-gallon values when available. ### Output fields `locationType` identifies whether the row is `national`, `state`, or `metro`. `locationName` is the human-readable location. `stateCode` is the two-letter state code when relevant. `stateName` is the full state name when relevant. `metroName` is the AAA metro name when relevant. `period` is the normalized comparison period. `regularUsd` is the regular gasoline average. `midGradeUsd` is the mid-grade gasoline average. `premiumUsd` is the premium gasoline average. `dieselUsd` is the diesel average. `priceDate` is the date displayed by AAA. `sourceUrl` is the source page used for the row. `scrapedAt` is the actor extraction timestamp. ### Example output item ```json { "locationType": "metro", "locationName": "Los Angeles-Long Beach, CA", "stateCode": "CA", "stateName": "California", "metroName": "Los Angeles-Long Beach", "period": "current", "regularUsd": 5.828, "midGradeUsd": 6.041, "premiumUsd": 6.225, "dieselUsd": 7.092, "priceDate": "6/11/26", "sourceUrl": "https://gasprices.aaa.com/?state=CA", "scrapedAt": "2026-06-11T08:52:49.345Z" } ```` ### Example input: all data for three states ```json { "stateCodes": ["CA", "TX", "NY"], "mode": "all", "includeMetroAreas": true, "includeHistoricalAverages": true, "maxItems": 250 } ``` ### Example input: fast state table ```json { "stateCodes": [], "mode": "stateAverages", "includeMetroAreas": false, "includeHistoricalAverages": false, "maxItems": 60 } ``` ### Example input: one state with details ```json { "stateCodes": ["CA"], "mode": "all", "includeMetroAreas": true, "includeHistoricalAverages": true, "maxItems": 100 } ``` ### How much does it cost to scrape AAA fuel prices? This actor uses pay-per-event pricing. There is a small one-time start event of `$0.005` per run. Each saved fuel-price record is charged as one result event with tiered prices: - FREE: `$0.0000575` per record - BRONZE: `$0.00005` per record - SILVER: `$0.000039` per record - GOLD: `$0.00003` per record - PLATINUM: `$0.00002` per record - DIAMOND: `$0.000014` per record Use `maxItems` and selected `stateCodes` to control run size. ### Performance The actor uses HTTP requests and HTML parsing. It does not launch a browser. Typical state-average runs complete quickly. Metro detail runs make one additional request per selected state. ### Proxy usage The actor does not require a proxy by default. AAA fuel price pages are public and return HTML over standard HTTP requests. If AAA changes access controls in the future, proxy options can be revisited. ### Limits and safety Use `maxItems` to cap dataset output. Use selected `stateCodes` for smaller recurring runs. Use `stateAverages` mode for the cheapest broad daily monitoring run. ### Data freshness AAA displays a price date on the source pages. The actor stores that value in `priceDate`. The actor also stores `scrapedAt` so you can distinguish the source date from the run timestamp. ### Data accuracy The actor reports the values shown by AAA at scrape time. It does not calculate or interpolate prices. If a price is missing on the source page, the field is returned as `null`. ### Handling page changes The actor validates that at least one record was extracted. If AAA changes the table structure and no records are found, the run fails instead of silently returning empty data. ### Integrations Use this actor as the fuel-price data step in repeatable operations workflows: - **Actor to Google Sheets dashboard**: schedule a daily run, export the dataset to Google Sheets, and chart regular, premium, and diesel averages by state. - **Diesel price alerts**: run selected states each morning, compare `dieselUsd` against your threshold, and send Slack, email, or webhook alerts when a region moves above budget. - **Fleet BI sync**: pull results with the Apify API into BigQuery, Snowflake, Power BI, Tableau, or a transport management system for cost-per-mile analysis. - **Travel-cost calculators**: combine current AAA state averages with route distance data to estimate trip and reimbursement costs. - **Regional monitoring archives**: append scheduled dataset exports to your data lake so analysts can compare AAA snapshots over time. ### Scheduling For daily monitoring, schedule the actor once per day after AAA updates prices. For broad national coverage, use `stateAverages` mode. For regional route planning, select the states where you operate and enable metro areas. ### Recommended configurations For a lightweight national/state snapshot, leave `stateCodes` empty and choose `stateAverages`. For a fleet operating in a few regions, list those states and choose `all`. For long-term trend archives, keep historical averages enabled. ### Troubleshooting If you see fewer rows than expected, check `maxItems` first. If a state has no metro rows, AAA may not publish metro data for that state. If a price field is null, AAA did not publish that value in the parsed row. ### FAQ #### Does this scrape individual gas stations? No. This actor scrapes AAA average prices by national, state, and metro geography. #### Does it require an AAA account? No. It only reads public AAA Fuel Prices pages. #### Does it use GasBuddy? No. The source is AAA Fuel Prices. #### Can I scrape only diesel? The actor saves all available fuel grades. Filter the dataset to `dieselUsd` in your downstream workflow. #### Can I monitor every state? Yes. Leave `stateCodes` empty for all current state averages. Enable detail collection if you also need metro and historical rows. ### Compliance note Use this actor responsibly and respect the target website's public availability and terms. The actor is intended for normal monitoring and analytics workloads, not abusive traffic. ### Who is it for #### Fleet and dispatch teams Use the actor to monitor diesel and regular gasoline averages in the states where your trucks operate. A common workflow is a scheduled morning run for selected states, followed by an alert when `dieselUsd` crosses an internal fuel-surcharge threshold. #### Logistics and freight analysts Archive daily state and metro averages to compare regional fuel costs with lane profitability, freight-rate changes, and cost-per-mile models. Analysts can load the dataset into BI tools and join it with route or shipment data by `stateCode`. #### Travel, mobility, and reimbursement teams Use state averages as an input for travel-cost calculators, mileage reimbursement estimates, car-rental planning, and customer-facing trip-budget tools. The `priceDate` and `scrapedAt` fields make it clear when each estimate was sourced. #### Developers and automation builders Call the actor from the Apify API, a webhook, or an MCP client when another system needs fresh structured AAA fuel-price averages without custom HTML parsing. #### Spreadsheet users Schedule the actor and export JSON, CSV, Excel, or Google Sheets-ready data instead of copying AAA tables by hand. ### API Usage You can run the actor from the Apify API after it is available in your account. #### Node.js API example ```js import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); const run = await client.actor('automation-lab/aaa-fuel-prices-scraper').call({ stateCodes: ['CA', 'TX'], mode: 'all', includeMetroAreas: true, includeHistoricalAverages: true, maxItems: 100, }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(items); ``` #### Python API example ```python from apify_client import ApifyClient import os client = ApifyClient(os.environ['APIFY_TOKEN']) run = client.actor('automation-lab/aaa-fuel-prices-scraper').call(run_input={ 'stateCodes': ['CA', 'TX'], 'mode': 'all', 'includeMetroAreas': True, 'includeHistoricalAverages': True, 'maxItems': 100, }) items = client.dataset(run['defaultDatasetId']).list_items().items print(items) ``` #### cURL API example ```bash curl -X POST 'https://api.apify.com/v2/acts/automation-lab~aaa-fuel-prices-scraper/runs?token=YOUR_APIFY_TOKEN' \ -H 'Content-Type: application/json' \ -d '{"stateCodes":["CA","TX"],"mode":"all","includeMetroAreas":true,"includeHistoricalAverages":true,"maxItems":100}' ``` ### MCP Use this actor from MCP-enabled tools through the Apify MCP HTTP server. Current Apify MCP URL for this actor: `https://mcp.apify.com?tools=automation-lab/aaa-fuel-prices-scraper` #### Claude Code MCP setup Add the Apify MCP HTTP server in Claude Code and use your Apify API token for authentication. Configure the server URL as: ```text https://mcp.apify.com?tools=automation-lab/aaa-fuel-prices-scraper ``` Example Claude Code CLI setup: ```bash claude mcp add apify-aaa-fuel-prices --url "https://mcp.apify.com?tools=automation-lab/aaa-fuel-prices-scraper" ``` Then ask Claude Code to run the actor with a JSON input such as selected `stateCodes`, `mode`, and `maxItems`. #### Claude Desktop, Cursor, and VS Code MCP setup In Claude Desktop, Cursor, or VS Code, add an MCP server that points to the same Apify HTTP endpoint: ```json { "mcpServers": { "apify-aaa-fuel-prices": { "url": "https://mcp.apify.com?tools=automation-lab/aaa-fuel-prices-scraper", "headers": { "Authorization": "Bearer YOUR_APIFY_TOKEN" } } } } ``` After saving the configuration, restart or reload the MCP client so the AAA Fuel Prices Scraper tool appears. Example prompts for MCP usage: - "Run the AAA Fuel Prices Scraper for CA and TX and summarize diesel averages." - "Get current AAA metro fuel prices for California with a max of 100 records." - "Compare regular gas averages for selected states using the latest AAA data." Use it when an agent needs fresh structured fuel-price averages for a state, metro area, or monitoring workflow. ### Legality The actor reads publicly available AAA Fuel Prices pages and stores the values displayed at run time. You are responsible for using the exported data in a lawful way and for respecting AAA's website terms and applicable rules for your use case. ### Related scrapers - [GlobalPetrolPrices Fuel Prices Scraper](https://apify.com/automation-lab/globalpetrolprices-fuel-prices-scraper) — collect country-level fuel price data for international comparison workflows. - [Autoscout24 Scraper](https://apify.com/automation-lab/autoscout24-scraper) — scrape vehicle marketplace listings for automotive market analysis. - [Google Autocomplete Scraper](https://apify.com/automation-lab/google-autocomplete-scraper) — collect autocomplete keyword ideas for fuel, travel, logistics, and automotive SEO research. Use this actor when you need AAA average price tables for the United States rather than individual station listings. ### Changelog Initial version: collect AAA national, state, historical, and metro fuel price averages. # Actor input Schema ## `stateCodes` (type: `array`): Optional two-letter state codes to scrape in detail. Leave empty to collect all state averages. ## `mode` (type: `string`): State averages is fastest. State details adds historical rows. All also collects metro-area averages. ## `includeMetroAreas` (type: `boolean`): Collect metro-area fuel price averages from each selected state page. ## `includeHistoricalAverages` (type: `boolean`): Collect yesterday, week-ago, month-ago, and year-ago comparison rows where AAA publishes them. ## `maxItems` (type: `integer`): Maximum number of dataset records to save. ## Actor input object example ```json { "stateCodes": [ "CA", "TX", "NY" ], "mode": "all", "includeMetroAreas": true, "includeHistoricalAverages": true, "maxItems": 20 } ``` # Actor output Schema ## `overview` (type: `string`): No description # 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 = { "stateCodes": [ "CA", "TX", "NY" ] }; // Run the Actor and wait for it to finish const run = await client.actor("automation-lab/aaa-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 = { "stateCodes": [ "CA", "TX", "NY", ] } # Run the Actor and wait for it to finish run = client.actor("automation-lab/aaa-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 '{ "stateCodes": [ "CA", "TX", "NY" ] }' | apify call automation-lab/aaa-fuel-prices-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=automation-lab/aaa-fuel-prices-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "AAA Fuel Prices Scraper", "description": "Scrape AAA fuel price averages for US states and metro areas.", "version": "0.1", "x-build-id": "v615ImuOOqIwwYOvt" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automation-lab~aaa-fuel-prices-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automation-lab-aaa-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/automation-lab~aaa-fuel-prices-scraper/runs": { "post": { "operationId": "runs-sync-automation-lab-aaa-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/automation-lab~aaa-fuel-prices-scraper/run-sync": { "post": { "operationId": "run-sync-automation-lab-aaa-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", "properties": { "stateCodes": { "title": "State codes", "type": "array", "description": "Optional two-letter state codes to scrape in detail. Leave empty to collect all state averages.", "items": { "type": "string" } }, "mode": { "title": "Scrape mode", "enum": [ "stateAverages", "stateDetails", "all" ], "type": "string", "description": "State averages is fastest. State details adds historical rows. All also collects metro-area averages.", "default": "all" }, "includeMetroAreas": { "title": "Include metro areas", "type": "boolean", "description": "Collect metro-area fuel price averages from each selected state page.", "default": true }, "includeHistoricalAverages": { "title": "Include historical averages", "type": "boolean", "description": "Collect yesterday, week-ago, month-ago, and year-ago comparison rows where AAA publishes them.", "default": true }, "maxItems": { "title": "Maximum records", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Maximum number of dataset records to save.", "default": 20 } } }, "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 } } } } } } } } } } ```