# GasBuddy Fuel Prices Scraper (`maximedupre/gasbuddy-fuel-prices`) Actor

Collect public US GasBuddy station prices by ZIP, city and state, or exact coordinates. Get reported fuel grades, cash and credit observations, station details, and report times in structured rows.

- **URL**: https://apify.com/maximedupre/gasbuddy-fuel-prices.md
- **Developed by:** [Maxime Dupré](https://apify.com/maximedupre) (community)
- **Categories:** Business, Automation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$1.35 / 1,000 fuel prices

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 web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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 for local station research

Fuel buyers, fleet teams, and data builders can search public US GasBuddy station data by ZIP or postal code, city and state, or exact coordinates. Get station identity, address, source link, reported prices for every grade GasBuddy reports, cash and credit observations, report times, ratings, offers, payment methods, status, and extraction time in structured dataset rows. Use the rows to compare local prices, map fueling options, or feed a price workflow without copying pages by hand.

**Use cases**

- Find nearby station listings with **[Gas Prices Near Me](https://apify.com/maximedupre/gasbuddy-fuel-prices/examples/gas-prices-near-me)**.
- Review state-specific results with **[Gas Prices In California](https://apify.com/maximedupre/gasbuddy-fuel-prices/examples/gas-prices-in-california)**.
- Check diesel prices around a location with **[Diesel Prices Near Me](https://apify.com/maximedupre/gasbuddy-fuel-prices/examples/diesel-prices-near-me)**.
- Compare Shell station prices with **[Shell Gas Prices Near Me](https://apify.com/maximedupre/gasbuddy-fuel-prices/examples/shell-gas-prices-near-me)**.
- Compare Costco station prices with **[Costco Gas Prices Near Me](https://apify.com/maximedupre/gasbuddy-fuel-prices/examples/costco-gas-prices-near-me)**.
- Compare Kroger station prices with **[Kroger Gas Prices Near Me](https://apify.com/maximedupre/gasbuddy-fuel-prices/examples/kroger-gas-prices-near-me)**.
- Compare Walmart station prices with **[Walmart Gas Prices Near Me](https://apify.com/maximedupre/gasbuddy-fuel-prices/examples/walmart-gas-prices-near-me)**.
- Compare Wawa station prices with **[Wawa Gas Prices Near Me](https://apify.com/maximedupre/gasbuddy-fuel-prices/examples/wawa-gas-prices-near-me)**.
- Compare Sheetz station prices with **[Sheetz Gas Prices Near Me](https://apify.com/maximedupre/gasbuddy-fuel-prices/examples/sheetz-gas-prices-near-me)**.

#### 🧾 Station prices and source details

**What you get**

The Actor saves one row for each discovered station. A row keeps the station link, address, search location, reported fuel prices, and source details that GasBuddy reports. Optional values stay absent when the source does not report them.

**Why it helps**

You can compare cash and credit prices, review report times, and keep station context in one dataset. This cuts down on manual page copying while leaving the source values visible for your own checks.

#### 🔎 Search stations by place

**How to run**

1. Choose one target type: ZIP or postal codes, city and state, or exact coordinates.
2. Add one or more values to the matching field. A run uses one target type at a time.
3. Optionally choose a fuel product to focus the search.
4. Optionally set a maximum report age or add brand names.
5. Start the run and open the default dataset.

**Result behavior**

- Each saved row is the first eligible match for a station. If another submitted location finds that station later, the later match is ignored.
- The fuel product focus guides the search. A station row still includes every fuel grade that GasBuddy reports for that station.
- Cash and credit observations are kept separately, with source report times and contributors when available.

**Coverage**

GasBuddy data is crowd-sourced. Reports may be old, missing, or different from the price at the pump. The Actor does not promise a current pump price, every grade at every station, or a fixed number of rows. It covers the supported public US GasBuddy search surface.

#### ⚙️ Input

Choose one value for `target`, then fill in the matching location field. Values in the other location groups are ignored.

**Input fields**

| Field | Type | What it does |
| --- | --- | --- |
| `target` | string | Required. Chooses `zip`, `cityState`, or `coordinates` for the run. |
| `zipCodes` | array of strings | One or more U.S. ZIP or ZIP+4 values, one per line. GasBuddy must resolve each value as a location. |
| `cityStates` | array of strings | One or more city and state values, such as `Austin, TX`, one per line. |
| `coordinates` | array of objects | One or more exact search locations. Each object needs a latitude and longitude. |
| `coordinates[].latitude` | number | Latitude for a search location, from -90 to 90. |
| `coordinates[].longitude` | number | Longitude for a search location, from -180 to 180. |
| `fuelType` | string | Optional focus: `regular`, `midgrade`, `premium`, `diesel`, `e85`, or `unleaded88`. Other reported grades still remain in the row. |
| `maxReportAgeHours` | integer | Optional age filter for cash and credit observations. A station is excluded only when neither payment type has an observation within the limit. |
| `brandNames` | array of strings | Optional brand filter. Add one or more brand names, one per line. |

**Example input**

This is copied from the successful current beta default-input run.

```json
{
  "target": "zip",
  "zipCodes": [
    "78701"
  ]
}
```

#### 🧾 Output

**Run output**

| Field | Type | What it does |
| --- | --- | --- |
| `datasetUrl` | string | Links to all station results in the default dataset view. |

The default dataset contains one station row per saved match. The table below covers the complete public dataset shape. Fields marked optional are omitted when the source does not provide them.

**Station row fields**

| Field | Type | What it does |
| --- | --- | --- |
| `stationId` | string | Stable GasBuddy station ID. |
| `stationName` | string | Station name reported by GasBuddy. |
| `brand` | string, optional | Station brand when reported. |
| `address` | object | Station street address. |
| `address.street` | string | Street address. |
| `address.city` | string | Station city. |
| `address.state` | string | Station state. |
| `address.postalCode` | string | Station postal code. |
| `stationUrl` | string | Canonical public GasBuddy station page. |
| `searchLocation` | object | The submitted location value that found the station. |
| `searchLocation.type` | string | Search type: `zip`, `cityState`, or `coordinates`. |
| `searchLocation.value` | string | Submitted ZIP, city and state value, or coordinate pair. |
| `distanceMiles` | number, optional | Distance from the search location in miles when GasBuddy reports it. |
| `stationCoordinates` | object, optional | Station latitude and longitude when reported. |
| `stationCoordinates.latitude` | number | Station latitude. |
| `stationCoordinates.longitude` | number | Station longitude. |
| `prices` | array of objects | Fuel grade price records reported for the station. |
| `prices[].fuelType` | string | Fuel grade, such as `regular`, `midgrade`, `premium`, `diesel`, `e85`, or `unleaded88`. |
| `prices[].cash` | object, optional | Cash price observation for the grade when reported. |
| `prices[].cash.price` | number | Source-reported cash price in US dollars per gallon. |
| `prices[].cash.reportedAt` | string, optional | Source-reported time for the cash price. |
| `prices[].cash.contributor` | string, optional | Source-reported contributor for the cash price. |
| `prices[].credit` | object, optional | Credit price observation for the grade when reported. |
| `prices[].credit.price` | number | Source-reported credit price in US dollars per gallon. |
| `prices[].credit.reportedAt` | string, optional | Source-reported time for the credit price. |
| `prices[].credit.contributor` | string, optional | Source-reported contributor for the credit price. |
| `rating` | object, optional | Station rating when reported. |
| `rating.score` | number, optional | Station rating score when reported. |
| `rating.count` | integer, optional | Number of ratings used for the score when reported. |
| `offers` | array of objects | Offers and discounts reported for the station. |
| `offers[].name` | string, optional | Offer name. |
| `offers[].details` | string, optional | Offer details. |
| `offers[].discount` | string, optional | Discount wording reported by GasBuddy. |
| `paymentMethods` | array of strings, optional | Payment methods reported as available at the station. |
| `status` | object, optional | Outage and emergency status when reported. |
| `status.outage` | string, optional | Outage status reported by GasBuddy. |
| `status.emergency` | string, optional | Emergency status reported by GasBuddy. |
| `extractedAt` | string | Time when the station row was extracted. |

**Example station row**

This is a complete genuine row from the current beta coordinate run. Optional fields that the source did not return are not added.

```json
{
  "stationId": "38761",
  "stationName": "Valero",
  "address": {
    "street": "8538 Research Blvd",
    "city": "Austin",
    "state": "TX",
    "postalCode": "78758"
  },
  "stationUrl": "https://www.gasbuddy.com/station/38761",
  "searchLocation": {
    "type": "coordinates",
    "value": "30.2672,-97.7431"
  },
  "prices": [
    {
      "fuelType": "regular",
      "cash": {
        "price": 3.69,
        "reportedAt": "2026-08-13T14:38:14.517Z",
        "contributor": "Valerie0520"
      },
      "credit": {
        "price": 3.69,
        "reportedAt": "2026-08-13T14:38:14.517Z",
        "contributor": "Valerie0520"
      }
    },
    {
      "fuelType": "midgrade",
      "cash": {
        "price": 4.09,
        "reportedAt": "2026-08-13T14:38:14.537Z",
        "contributor": "Valerie0520"
      },
      "credit": {
        "price": 4.09,
        "reportedAt": "2026-08-13T14:38:14.553Z",
        "contributor": "Valerie0520"
      }
    },
    {
      "fuelType": "premium",
      "cash": {
        "price": 4.99,
        "reportedAt": "2026-08-13T14:38:14.568Z",
        "contributor": "Valerie0520"
      },
      "credit": {
        "price": 4.99,
        "reportedAt": "2026-08-13T14:38:14.621Z",
        "contributor": "Valerie0520"
      }
    },
    {
      "fuelType": "diesel",
      "cash": {
        "price": 5.09,
        "reportedAt": "2026-08-13T14:38:14.636Z",
        "contributor": "Valerie0520"
      },
      "credit": {
        "price": 5.09,
        "reportedAt": "2026-08-13T14:38:14.652Z",
        "contributor": "Valerie0520"
      }
    }
  ],
  "extractedAt": "2026-08-13T18:28:28.019Z",
  "brand": "Valero",
  "stationCoordinates": {
    "latitude": 30.359933972689,
    "longitude": -97.717123031616
  },
  "rating": {
    "score": 3,
    "count": 47
  },
  "offers": [
    {
      "name": "Flash Deal: Save 2¢ per gallon",
      "details": "gasbuddy, strike, sort",
      "discount": "Flash Deal: Save 2¢ per gallon"
    }
  ],
  "paymentMethods": [
    "pay_with_gasbuddy"
  ]
}
```

#### 💳 Pricing

**How charging works**

One event is charged for each station fuel-price row saved to the dataset. The current event price is shown in the Store pricing panel before you run. A row can contain several fuel grades and cash or credit observations.

#### 🔌 Integrations

**Dataset and workflow access**

Open the default Apify dataset to review the rows. Use the Apify API, schedules, or available dataset integrations to move repeated station searches into your workflow.

**Video guide**

https://www.youtube.com/watch?v=bNACk1\_S\_6w\&list=PLObrtcm1Kw6MUrlLNDbK9QRg8VDJg0gOW\&index=4

#### ❓ FAQ

##### Can I search a city such as Woodlake, Virginia?

Yes. Choose City and state and enter a value such as `Woodlake, VA`. Results depend on public GasBuddy coverage and the reports available for that location.

##### Can I submit several locations in one run?

Yes. Choose one target type, then add multiple ZIP codes, city and state values, or coordinate items to its matching field. Values in the other location groups are ignored.

##### Does the fuel product focus hide other grades?

No. It focuses the search, but each station row still includes every fuel grade that GasBuddy reports for that station.

##### Can I keep only recent price reports?

Yes. Set `maxReportAgeHours`. Cash and credit observations are checked separately, and a station is excluded only when neither payment type has an observation within the limit.

##### Why is a price or station field missing?

GasBuddy may not report every grade, payment type, rating, offer, or status for every station. The Actor keeps available source values and does not invent missing ones.

##### What happens when two locations find the same station?

The first eligible match is saved. A later match for the same station is ignored, so the saved row keeps the first search location that found it.

##### Does the Actor guarantee a current pump price or a result count?

No. GasBuddy prices are crowd-sourced and can change after a report. Public coverage, missing grades, and your filters can also change the number of rows.

##### Do I need a GasBuddy login or API key?

No. The Actor uses public station-search data and does not require a GasBuddy login or private API key.

##### Which fuel products can I choose?

You can focus on Regular, Midgrade, Premium, Diesel, E85, or Unleaded 88. The row can still include other grades that GasBuddy reports.

### 📝 Changelog

**0.0: Initial release**

### 🆘 Support

For issues, questions, or feature requests, [file a ticket](https://console.apify.com/actors/maximedupre~gasbuddy-fuel-prices/issues) and I'll fix or implement it in less than 24h 🫡

### 🔗 Related Actors

- [Google Maps List Scraper: 30+ Fields Per Place](https://apify.com/maximedupre/google-maps-shared-list-scraper): Add public addresses, coordinates, ratings, and other place details to station-area research.
- [Google Maps Phone Number Scraper](https://apify.com/maximedupre/google-maps-phone-number-scraper): Find public business phone numbers and map context around a local fuel market.
- [Yellow Pages Scraper](https://apify.com/maximedupre/yellowpages-scraper): Find public US business listings, hours, ratings, and contact details near a location.
- [GasBuddy Fuel Prices Scraper — Stations, All Grades, Batch](https://apify.com/memo23/gasbuddy-fuel-prices-scraper): Compare another GasBuddy workflow that batches ZIP codes or cities and returns all grades per station.
- [GasBuddy Fuel Prices Scraper](https://apify.com/automation-lab/gasbuddy-fuel-prices-scraper): Compare another GasBuddy station-price workflow that accepts ZIPs, cities, and coordinates.

**Made with ❤️ by Maxime Dupré**

# Actor input Schema

## `target` (type: `string`):

Choose one location type for this run. Enter one or more values in that type's options.

## `zipCodes` (type: `array`):

Enter one or more U.S. ZIP codes or ZIP+4 values that GasBuddy can resolve, one per line. GasBuddy rejects non-geographic or ambiguous values, including 78706. Choose City and state or Exact coordinates for another location format.

## `cityStates` (type: `array`):

Enter one or more city and state values, such as Austin, TX. Use one value per line. GasBuddy uses each value as a location search.

## `coordinates` (type: `array`):

Enter one or more exact locations. Each item must include a latitude and longitude.

## `fuelType` (type: `string`):

Optionally choose one fuel product to focus on. Each station result still includes all fuel grades that GasBuddy reports.

## `maxReportAgeHours` (type: `integer`):

Keep cash or credit observations no older than this many hours. A station is excluded only when neither payment type has an observation within the limit.

## `brandNames` (type: `array`):

Optionally keep stations from these brands. Enter one or more brand names, one per line.

## Actor input object example

```json
{
  "target": "zip",
  "zipCodes": [
    "78701"
  ]
}
```

# Actor output Schema

## `datasetUrl` (type: `string`):

Link to all station results in the default dataset view.

# 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 = {
    "target": "zip",
    "zipCodes": [
        "78701"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("maximedupre/gasbuddy-fuel-prices").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 = {
    "target": "zip",
    "zipCodes": ["78701"],
}

# Run the Actor and wait for it to finish
run = client.actor("maximedupre/gasbuddy-fuel-prices").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 '{
  "target": "zip",
  "zipCodes": [
    "78701"
  ]
}' |
apify call maximedupre/gasbuddy-fuel-prices --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,maximedupre/gasbuddy-fuel-prices"
        }
    }
}

```

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/FsAq0O8b2gQvtZHNi/builds/0BSBCYusaAbL3VXcK/openapi.json