# GasBuddy Fuel Prices Scraper — Stations, All Grades, Batch (`memo23/gasbuddy-fuel-prices-scraper`) Actor Scrape live US gas-station fuel prices from GasBuddy — batch many ZIPs or cities in one run and get EVERY grade (Regular, Midgrade, Premium, Diesel) per station in a single pass, plus ratings, brands, offers, outage status, distance and per-price posted time. JSON, CSV or Excel. - **URL**: https://apify.com/memo23/gasbuddy-fuel-prices-scraper.md - **Developed by:** [Muhamed Didovic](https://apify.com/memo23) (community) - **Categories:** E-commerce, Automation, AI - **Stats:** 1 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $1.50 / 1,000 station results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. 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/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.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/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 ## GasBuddy Fuel Prices Scraper 🛢️⛽ Scrape **US gas-station fuel prices from GasBuddy** — batch many ZIP codes and cities in a single run, and get **every fuel grade at every station in one pass** (Regular, Midgrade, Premium, Diesel), each with cash & credit price, the time it was posted and the member who posted it. Plus full station enrichment: ratings, brands, Pay-with-GasBuddy availability, offers/discounts, emergency/outage status, distance and address. Built to be a **drop-in, richer, better-value replacement** for one-grade-per-run fuel-price scrapers. --- ### ✨ Why use this scraper (3 differentiators + transparent pricing) | | This actor | Typical competitor (e.g. `johnvc/fuelprices`) | |---|---|---| | **1. Batch multi-location** | Put **dozens of ZIPs/cities in one `search` array**, one run covers them all, stations de-duplicated by id across overlaps | Usually one location per run | | **2. Every fuel grade in one pass** | **All grades returned per station** in a single request — no need to re-run per grade | Often one grade per run | | **3. Full station enrichment** | ratings, ratingsCount, brands, payStatus, offers/discounts, emergency/outage status, distance, address, and **per-price posted time + posting member** | Usually just name/address + price | | **Pricing** | **Pay-per-result: $0.0015 per fully-enriched station row** — you pay only for stations you actually get | ~$0.001/row for a thinner schema | | **Output shape** | One **clean flat row per station** with a nested `prices` object keyed by grade | Varies | **Transparent, usage-based pricing:** `$0.07` per run start (this covers the live Cloudflare bypass — a managed CAPTCHA solve + residential proxy — that every run needs to reach GasBuddy's price data) + **`$0.0015` per station row**. No monthly rental, no per-grade multiplication. A 100-station run costs about **$0.22**; a big multi-city run amortizes the start fee to noise. The actor prints a **💰 cost preview** at the start of every run so you know the ceiling before it spends anything. --- ### 📥 Input | Field | Type | Description | |---|---|---| | `search` | array | US locations — **ZIP codes, city names, or "city, ST"**. One run covers every entry. Same field competitors use, so migration is drop-in. E.g. `["90210", "Austin, TX", "10001"]` | | `fuel` | select | Primary grade that drives the sort — `Regular` (default), `Midgrade`, `Premium`, `Diesel`. **Every grade is still returned per station** regardless of this. | | `lat` / `lng` | number | Optional coordinate search (provide both). | | `maxStationsPerSearch` | integer | Cap on stations per search location. Default `100`. | | `maxPages` | integer | Cap on cursor pages walked per location. Default `10`. | | `maxItems` | integer | Hard cap on total rows across all locations. Default `1000`. | | `maxRetries` | integer | Per-page retries on a Cloudflare challenge, each on a fresh proxy session. Default `5`. | | `proxy` | proxy | **Residential proxies are mandatory** (see below). Defaults to Apify Proxy `RESIDENTIAL`. | #### Example input ```json { "search": ["90210", "Austin, TX", "10001"], "fuel": "Regular", "maxStationsPerSearch": 50, "maxPages": 5, "maxItems": 500, "proxy": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] } } ```` *** ### 📤 Output One clean, flat row per station. Prices are nested under `prices`, keyed by grade. ```json { "searchTerm": "90210", "primaryFuel": "Regular", "stationId": "6258", "name": "76", "brand": "76", "brands": [{ "brandId": 15, "name": "76", "imageUrl": "https://images.gasbuddy.io/b/15.png", "brandingType": "fuel" }], "address": { "line1": "427 N Crescent Dr", "line2": "", "city": "Beverly Hills", "state": "CA", "postalCode": "90210-4815", "country": "US", "full": "427 N Crescent Dr, Beverly Hills, CA, 90210-4815" }, "distance": "0.4 mi", "starRating": 4.2, "ratingsCount": 74, "payAvailable": true, "offers": [{ "id": "…", "use": "…", "discounts": [{ "grades": ["regular_gas"], "pwgbDiscount": 0.25, "receiptDiscount": null }] }], "emergencyStatus": { "hasGas": null, "hasDiesel": null, "hasPower": null }, "hasActiveOutage": false, "enterprise": false, "fuels": ["regular_gas", "midgrade_gas", "premium_gas", "diesel"], "priceUnit": "dollars_per_gallon", "prices": { "Regular": { "fuelProduct": 1, "grade": "Regular", "cash": { "price": 4.99, "postedTime": "2026-07-20T15:03:00Z", "member": "fuelfan22" }, "credit": { "price": 5.09, "postedTime": "…", "member": "…" }, "discount": null }, "Premium": { "fuelProduct": 3, "grade": "Premium", "cash": { "price": 5.49, "postedTime": "…", "member": "…" }, "credit": null, "discount": null }, "Diesel": { "fuelProduct": 4, "grade": "Diesel", "cash": { "price": 5.29, "postedTime": "…", "member": "…" }, "credit": null, "discount": null } }, "searchCentroid": { "displayName": "90210", "latitude": 34.09, "longitude": -118.41, "regionCode": "CA", "countryCode": "US" }, "stationUrl": "https://www.gasbuddy.com/station/6258", "scrapedAt": "2026-07-20T15:04:11.000Z" } ``` Export as **JSON, CSV, or Excel** from the run's dataset. *** ### ⚙️ How it works ![How it works — GasBuddy Fuel Prices Scraper: search → Cloudflare bypass & GraphQL fetch → one enriched station row per station](https://raw.githubusercontent.com/muhamed-didovic/muhamed-didovic.github.io/main/assets/how-it-works-gasbuddy@2x.png) GasBuddy serves all of its station + price data from a single GraphQL operation (`LocationBySearchTerm`). The whole domain is behind a **Cloudflare interactive challenge**, and the `/graphql` price endpoint adds a second **Fastly edge gate** that requires a per-page CSRF token. This actor clears both — pure HTTP, no headless browser: it solves the Cloudflare challenge to mint a `cf_clearance` cookie, pins the residential exit IP so the cleared session stays valid, scrapes the page's `gbcsrf` token, and calls the GraphQL endpoint with the exact headers the web app uses — then paginates through `stations.cursor.next`. Stations are de-duplicated by id across overlapping searches. **Residential proxies are mandatory.** If a session is blocked it is rotated and retried automatically (`maxRetries`); a systemically blocked run **fails loudly** rather than silently returning zero rows, so you are never billed for a dead run. *** ### ❓ FAQ **Which fuel grades are included?** Regular (87), Midgrade (89), Premium (91–93) and Diesel — **all of them, per station, in one pass**. The `fuel` input only sets the sort key. **Do I really get cash *and* credit prices?** Yes — each grade in `prices` carries a `cash` and a `credit` entry (when the station reports both), each with the posted time and the GasBuddy member who posted it. **Can I scrape many cities at once?** Yes — that's the point. Put every ZIP/city in the `search` array; one run covers them all and de-duplicates stations by id. **How much does it cost?** `$0.07` per run (covers the per-run Cloudflare bypass) + `$0.0015` per station row. A cost preview is logged at the start of every run, so you always see the ceiling before it spends. **Do I need my own proxies?** No — the actor defaults to Apify `RESIDENTIAL`. Residential is required; datacenter IPs will be challenged. **Why did my run return 0 rows?** Either the ZIP has no GasBuddy coverage (finishes SUCCEEDED with a notice) or every session was blocked by Cloudflare (fails loudly — retry with residential proxies). *** ### 🔎 SEO keywords gas prices scraper, fuel price api, gasbuddy scraper, gas station data, fuel prices scraper, gas price api, gasoline prices scraper, diesel price scraper, us gas prices, station level fuel prices, gasbuddy data extraction, gas price monitoring, fuel price tracker, cheapest gas near me data, gas station locator api *** ### ⚠️ Disclaimer This actor is an **independent tool and is not affiliated with, endorsed by, or sponsored by GasBuddy** or any of its brands. "GasBuddy" and all brand names are trademarks of their respective owners. Fuel-price data on GasBuddy is crowd-sourced and may be delayed or inaccurate; verify prices at the pump. Use this actor in compliance with applicable laws, GasBuddy's terms, and only for data you are permitted to collect. You are responsible for how you use the collected data. # Actor input Schema ## `search` (type: `array`): US locations to scrape — ZIP codes, city names, or 'city, ST'. One run covers every entry (batch). Same field the competitor uses, so migration is drop-in. Examples: 90210, "Austin, TX", "Chicago". ## `fuel` (type: `string`): Which grade drives GasBuddy's sort and the 'primary' price. Note: every grade a station reports is ALWAYS returned in the `prices` object regardless of this setting — this only picks the sort key. No need to run once per grade. ## `lat` (type: `number`): Optional latitude to search by coordinate instead of / in addition to a text search. Provide both lat and lng. ## `lng` (type: `number`): Optional longitude to search by coordinate. Provide both lat and lng. ## `maxStationsPerSearch` (type: `integer`): Upper bound on stations collected for each search location (across cursor pages). ## `maxPages` (type: `integer`): Cap on how many cursor pages to walk per search location. GasBuddy returns stations by proximity; more pages = wider radius. ## `maxItems` (type: `integer`): Hard cap on total dataset rows (stations) across all locations. ## `maxRetries` (type: `integer`): How many times to retry a blocked/failed page, each on a fresh residential proxy session, before giving up on that page. ## `proxy` (type: `object`): Residential proxies are MANDATORY for GasBuddy (the whole domain is behind a Cloudflare interactive challenge). Defaults to Apify Proxy with the RESIDENTIAL group. Leave as-is unless you have your own residential pool. ## Actor input object example ```json { "search": [ "90210", "Austin, TX", "10001" ], "fuel": "Regular", "maxStationsPerSearch": 100, "maxPages": 10, "maxItems": 1000, "maxRetries": 5, "proxy": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } ``` # 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 = { "search": [ "90210", "Austin, TX", "10001" ], "proxy": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }; // Run the Actor and wait for it to finish const run = await client.actor("memo23/gasbuddy-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 = { "search": [ "90210", "Austin, TX", "10001", ], "proxy": { "useApifyProxy": True, "apifyProxyGroups": ["RESIDENTIAL"], }, } # Run the Actor and wait for it to finish run = client.actor("memo23/gasbuddy-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 '{ "search": [ "90210", "Austin, TX", "10001" ], "proxy": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }' | apify call memo23/gasbuddy-fuel-prices-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=memo23/gasbuddy-fuel-prices-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "GasBuddy Fuel Prices Scraper — Stations, All Grades, Batch", "description": "Scrape live US gas-station fuel prices from GasBuddy — batch many ZIPs or cities in one run and get EVERY grade (Regular, Midgrade, Premium, Diesel) per station in a single pass, plus ratings, brands, offers, outage status, distance and per-price posted time. JSON, CSV or Excel.", "version": "0.0", "x-build-id": "3XrIha0coIMnPIKKH" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/memo23~gasbuddy-fuel-prices-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-memo23-gasbuddy-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/memo23~gasbuddy-fuel-prices-scraper/runs": { "post": { "operationId": "runs-sync-memo23-gasbuddy-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/memo23~gasbuddy-fuel-prices-scraper/run-sync": { "post": { "operationId": "run-sync-memo23-gasbuddy-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": { "search": { "title": "Search locations (ZIP / city / \"city, ST\")", "type": "array", "description": "US locations to scrape — ZIP codes, city names, or 'city, ST'. One run covers every entry (batch). Same field the competitor uses, so migration is drop-in. Examples: 90210, \"Austin, TX\", \"Chicago\".", "items": { "type": "string" } }, "fuel": { "title": "Primary fuel grade", "enum": [ "Regular", "Midgrade", "Premium", "Diesel" ], "type": "string", "description": "Which grade drives GasBuddy's sort and the 'primary' price. Note: every grade a station reports is ALWAYS returned in the `prices` object regardless of this setting — this only picks the sort key. No need to run once per grade.", "default": "Regular" }, "lat": { "title": "Latitude", "type": "number", "description": "Optional latitude to search by coordinate instead of / in addition to a text search. Provide both lat and lng." }, "lng": { "title": "Longitude", "type": "number", "description": "Optional longitude to search by coordinate. Provide both lat and lng." }, "maxStationsPerSearch": { "title": "Max stations per search location", "minimum": 1, "type": "integer", "description": "Upper bound on stations collected for each search location (across cursor pages).", "default": 100 }, "maxPages": { "title": "Max pages per search (cursor pagination)", "minimum": 1, "type": "integer", "description": "Cap on how many cursor pages to walk per search location. GasBuddy returns stations by proximity; more pages = wider radius.", "default": 10 }, "maxItems": { "title": "Maximum items to scrape", "minimum": 1, "type": "integer", "description": "Hard cap on total dataset rows (stations) across all locations.", "default": 1000 }, "maxRetries": { "title": "Max retries per page (on Cloudflare challenge)", "minimum": 0, "type": "integer", "description": "How many times to retry a blocked/failed page, each on a fresh residential proxy session, before giving up on that page.", "default": 5 }, "proxy": { "title": "Proxy configuration", "type": "object", "description": "Residential proxies are MANDATORY for GasBuddy (the whole domain is behind a Cloudflare interactive challenge). Defaults to Apify Proxy with the RESIDENTIAL group. Leave as-is unless you have your own residential pool.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } } }, "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 } } } } } } } } } } ```