{ "openapi": "3.0.1", "info": { "title": "GasBuddy Scraper: Fuel Prices, Stations & Reviews", "description": "Scrape GasBuddy station by station across the US and Canada. Returns brand, address, coordinates, phone, amenities, open status, ratings and reviews, plus the current cash and credit price for every fuel grade with who reported it and when. Incremental mode tracks price changes between runs.", "version": "1.1", "x-build-id": "mIq9hubTdQdyFWdCj" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/abotapi~gasbuddy-com-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-abotapi-gasbuddy-com-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/abotapi~gasbuddy-com-scraper/runs": { "post": { "operationId": "runs-sync-abotapi-gasbuddy-com-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/abotapi~gasbuddy-com-scraper/run-sync": { "post": { "operationId": "run-sync-abotapi-gasbuddy-com-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": "What do you want to scrape?", "enum": [ "search", "url" ], "type": "string", "description": "Search mode looks up stations around each location you list. URL mode reads the station links you paste. Fill in the section that matches your choice, then set the filters below. Precedence: the mode you pick decides which list is read (Locations in search mode, Station or search links in URL mode); the other list is ignored. Exception: when you give links or Stations and no location of any kind, the run uses URL mode whatever this field says. ZIP codes, Cities, Coordinates and Street addresses are merged into Locations; Stations are merged into the links. Filters apply to both modes.", "default": "search" }, "locations": { "title": "Locations", "type": "array", "description": "One entry per area. Use a postal code (78701), a city and state (Austin, TX), a state (Texas), or a coordinate pair written as latitude,longitude (30.2672,-97.7431). A coordinate pair is what makes this a radius search: only then does GasBuddy return a distance per station, which is what Max distance filters on. Search mode only.", "items": { "type": "string" } }, "urls": { "title": "Station or search links", "type": "array", "description": "Paste station addresses such as https://www.gasbuddy.com/station/29330, bare station ids such as 29330, a search address such as https://www.gasbuddy.com/home?search=78701, or a state or city price page such as https://www.gasbuddy.com/gasprices/texas/austin. Append &page=2 (or &cursor=50 for an exact row offset) to a search address to start the walk deeper, which is how a big sweep is split across runs. A pasted station is always returned, even when the filters below would have excluded it. URL mode only.", "default": [], "items": { "type": "string" } }, "zipCodes": { "title": "ZIP codes", "type": "array", "description": "Alias for postal codes in Locations. Added to the search list; search mode.", "items": { "type": "string" } }, "cityStates": { "title": "Cities (City, ST)", "type": "array", "description": "Alias for city-and-state entries such as Austin, TX in Locations. Search mode.", "items": { "type": "string" } }, "coordinates": { "title": "Coordinates", "type": "array", "description": "List of objects with latitude and longitude. Each pair becomes a radius search, so distance and Max distance work. Search mode.", "items": { "type": "object", "properties": { "latitude": { "title": "Latitude", "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude in decimal degrees (-90 to 90)." }, "longitude": { "title": "Longitude", "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude in decimal degrees (-180 to 180)." } }, "required": [ "latitude", "longitude" ] } }, "stations": { "title": "Stations (IDs or links)", "type": "array", "description": "Alias for station links or bare station ids in Station or search links. When no location of any kind is given the run uses link mode. With Locations also given and Mode left on search, the run stays in search mode: Stations are not looked up and the run log says so. With Mode set to URL, Stations are looked up and Locations are not read. Stations the site does not return are listed in the LOOKUP_STATUS record of the run's key-value store, not in the dataset.", "items": { "type": "string" } }, "streetAddresses": { "title": "Street addresses", "type": "array", "description": "Full street addresses. Each is searched and only stations whose street line matches are kept (when used on its own). Search mode.", "items": { "type": "string" } }, "brands": { "title": "Fuel brands", "type": "array", "description": "Return only stations of these brands, for example Shell or Costco. Names are checked against GasBuddy's own brand list, so a misspelled brand is reported by name instead of silently returning everything. Several brands return stations of ANY of them. Applies to a location search and to a pasted search link.", "items": { "type": "string" } }, "brandNames": { "title": "Brand names", "type": "array", "description": "Alias for Brands; merged with it.", "items": { "type": "string" } }, "fuelType": { "title": "Fuel grade", "enum": [ "regular", "midgrade", "premium", "diesel", "e85", "unl88" ], "type": "string", "description": "The grade GasBuddy ranks the area by. Every grade the station sells is still returned in the prices list; this decides which grade drives the ordering and which stations qualify.", "default": "regular" }, "maxPriceAgeHours": { "title": "Maximum price age (hours)", "enum": [ "0", "4", "8", "12", "24", "36", "48" ], "type": "string", "description": "Prices on GasBuddy are reported by its members. Set a window to keep only stations whose price was confirmed recently.", "default": "0" }, "maxReportAgeHours": { "title": "Maximum report age (hours, any value)", "minimum": 1, "type": "integer", "description": "Keep stations with at least one price reported within this many hours. Any whole number; also narrows the site-side price-age filter to the nearest step. Used when Maximum price age is Any age." }, "minPrice": { "title": "Minimum price", "minimum": 0, "type": "integer", "description": "Keep stations whose cheapest reported price is at least this much. Left empty means no lower bound." }, "maxPrice": { "title": "Maximum price", "minimum": 0, "type": "integer", "description": "Keep stations whose cheapest reported price is at most this much. Left empty means no upper bound." }, "minStarRating": { "title": "Minimum star rating", "minimum": 1, "maximum": 5, "type": "integer", "description": "Keep only stations rated at least this many stars by GasBuddy members. Left empty means any rating, including unrated stations." }, "amenities": { "title": "Required amenities", "uniqueItems": true, "type": "array", "description": "Keep only stations that have ALL of the amenities you pick. GasBuddy publishes no amenity filter of its own, so this is applied to the stations it returns.", "items": { "type": "string", "enum": [ "air", "atm", "beer", "c_store", "carwash", "cash_credit", "full_service", "has_diesel", "has_fuel", "has_power", "lotto", "membership_discount", "membership_pricing", "membership_required", "pay_at_pump", "payphone", "propane", "restaurant", "restrooms", "service_station", "truckstop", "wine" ], "enumTitles": [ "Air Pump", "ATM", "Beer", "C-Store", "Car Wash", "Offers Cash Discount", "Full Service", "Has Diesel", "Has Fuel", "Has Power", "Lotto", "Loyalty Discount", "Membership Pricing", "Membership Required", "Pay at Pump", "Payphone", "Propane", "Restaurant", "Restrooms", "Service Station", "Truck Stop", "Wine" ] } }, "openNowOnly": { "title": "Open right now only", "type": "boolean", "description": "Keep only stations GasBuddy currently reports as open.", "default": false }, "withPricesOnly": { "title": "Only stations with a reported price", "type": "boolean", "description": "Keep only stations that have at least one grade with a real reported price. Turn this on when an unpriced station is no use to you.", "default": false }, "maxDistanceMiles": { "title": "Max distance (miles)", "minimum": 1, "type": "integer", "description": "Keep only stations within this many miles of the point you searched. Only a coordinate entry (latitude,longitude) makes GasBuddy return a distance, so a station with no distance is kept rather than dropped." }, "fetchReviews": { "title": "Include member reviews", "type": "boolean", "description": "Add GasBuddy member reviews to each station. The first page of reviews comes back with the search itself and is never charged. Only asking for MORE rows than that page holds costs an extra request per station, and only that is charged.", "default": false }, "maxReviewsPerStation": { "title": "Max reviews per station", "minimum": 0, "maximum": 1000, "type": "integer", "description": "Upper bound on review rows per station (at most 1000). Up to 10 arrive free with the search; anything above that fetches extra pages and charges the review surcharge once for that station. 0 means no reviews.", "default": 10 }, "maxStations": { "title": "Max stations", "minimum": 0, "type": "integer", "description": "Stop after this many matching stations across all locations. 0 means no limit, which on a whole state can be thousands of billed rows.", "default": 20 }, "maxPages": { "title": "Max pages per location", "minimum": 0, "type": "integer", "description": "Stop each location after this many result pages. 0 means walk to the end of that area.", "default": 0 }, "proxy": { "title": "Proxy & connection", "type": "object", "description": "GasBuddy only answers from a North American exit, so keep the country set to US. A US exit reaches the Canadian stations too, with prices in CAD per litre, so there is no need to pick a Canadian exit (and the standard pool does not offer one on every plan). The default pool is enough; a residential pool is only ever used if you pick it here.", "default": { "useApifyProxy": true, "apifyProxyCountry": "US" } }, "resumeFromRunId": { "title": "Resume from a previous run", "type": "string", "description": "Continue ONE interrupted crawl: paste that run's id (or its dataset id) and stations it already returned are skipped. For recurring monitoring use Incremental mode below instead, which remembers the previous run by itself." }, "incrementalMode": { "title": "Incremental mode (track price changes between runs)", "type": "boolean", "description": "Run the same search on a schedule and get only what moved. Every station is labelled NEW, UPDATED, REAPPEARED or UNCHANGED, and changedFields names exactly what changed, which is how you build a price history over time. Unlike Resume from a previous run, this remembers the previous run itself.", "default": false }, "stateKey": { "title": "State key", "type": "string", "description": "Name this monitoring campaign so several schedules can track different searches without sharing a baseline. Left empty, a key is derived from the mode, locations, links and every filter." }, "emitUnchanged": { "title": "Also return unchanged stations", "type": "boolean", "description": "Incremental mode only. Returns stations whose prices did not move, labelled UNCHANGED. These are extra rows and they are billed like any other result.", "default": false }, "emitExpired": { "title": "Also return stations that disappeared", "type": "boolean", "description": "Incremental mode only. Returns a final row labelled EXPIRED for a station that is no longer found, but only after a run that completed a full scan. These are extra rows and they are billed like any other result.", "default": false }, "changeScope": { "title": "What counts as a change", "enum": [ "all", "priceAndStock" ], "type": "string", "description": "Incremental mode only. Any field: any non-ignored field that moves makes a station UPDATED. Prices only: only the lowest price, its fuel grade, the price unit and the per-grade cash price, credit price and member discount are compared, so a changed phone number, hours, amenities or rating never creates a billable row. A station that disappears from the results is not necessarily closed; there is no stock count for a gas station, the posted price is its availability signal.", "default": "all" }, "compactUpdates": { "title": "Compact updated rows", "type": "boolean", "description": "Incremental mode only. UPDATED and EXPIRED rows become slim: station id, link, name, current prices, priceChanges (old and new value per moved field) and variantChanges (per fuel grade: ADDED, REMOVED or CHANGED with old and new). NEW rows stay complete. A compact row has no reviews, so it carries no review charge.", "default": false }, "expireAfterMissedScans": { "title": "Expire after missed scans", "minimum": 1, "type": "integer", "description": "Incremental mode with Also return stations that disappeared only. A station is marked EXPIRED after this many consecutive complete scans no longer listed it (1 = the first one). EXPIRED means the site stopped listing the station in this search, not that it closed or has no fuel.", "default": 1 }, "ignoreFieldsForChanges": { "title": "Ignore fields when detecting changes (incremental mode only)", "type": "array", "description": "Incremental mode only. Field names that must never make a station UPDATED or appear in changedFields, kept in the output. Nested fields use a dotted path, for example prices.creditReportedBy. Already ignored by default: scrapedAt, distance, distanceMiles, searchLocation, searchTerm, priceTrend, offers, reviews, topSpotters.", "items": { "type": "string" } }, "mcpConnectors": { "title": "Pipe results into your apps (optional)", "type": "array", "description": "Optionally send the scraped results into the apps you already use, via Model Context Protocol (MCP) connectors. Authorize a connector once under Apify -> Settings -> Integrations, then select it here. The connector receives a condensed, human-readable summary per item (title + key fields), not the full JSON; the complete record stays in the dataset. Leave empty to skip. Supported: Notion (https://mcp.notion.com/mcp), Linear (https://mcp.linear.app/sse), Airtable (https://mcp.airtable.com/mcp), Apify (https://mcp.apify.com)." }, "notionParentPageUrl": { "title": "Notion parent page (Notion connector only)", "type": "string", "description": "URL (or id) of the Notion page under which item pages are created. Required to enable the Notion export; ignored by other connectors." }, "maxNotifyListings": { "title": "Max items to export per connector", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Cap on items written to each connector per run. Does not affect the dataset.", "default": 50 } } }, "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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }