# GasBuddy API: Gas Station Fuel Prices for US & Canada (`s-r/gasbuddy-fuel-prices`) Actor

Get live gas station prices from GasBuddy for the US and Canada: cash and credit prices per fuel grade, address, brand and rating. Search by ZIP, city or coordinates for price comparison, fleet and route planning.

- **URL**: https://apify.com/s-r/gasbuddy-fuel-prices.md
- **Developed by:** [SR](https://apify.com/s-r) (community)
- **Categories:** Travel, Developer tools, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$2.00 / 1,000 stations

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## GasBuddy API: Gas Station Fuel Prices for the US and Canada

This GasBuddy API alternative returns live gas station prices for the United States and Canada, one row per station. Give it a list of ZIP codes, Canadian postal codes, cities or coordinates and it returns the station, its address, brand and rating, and the cash and credit price per fuel grade, each with the time it was reported. Use it for price comparison, fleet and route planning, and fuel market analysis.

### What is the GasBuddy API alternative for?

GasBuddy publishes crowdsourced pump prices, but it offers no public API for them. This actor turns the same station data into a dataset you can call from code, schedule, or download as CSV, JSON or Excel. It is built for bulk work: you can submit hundreds of locations in one run instead of one search per run, and large inputs continue in bounded pages automatically.

Typical buyers are price-comparison sites, fleet and fuel-card teams, route and trip-planning apps, retail analysts who track fuel margins, and journalists or researchers following gas prices by region.

### GasBuddy API input

Provide `locations` as a list of search strings. Supported forms include the US ZIP code `77002`, the Canadian postal code `M5V 2T6`, and a city with its state or province such as `Houston, TX` or `Toronto, ON`. Use `coordinates` for a list of latitude and longitude strings such as `40.7506,-73.9972`. You can combine locations and coordinates in the same run. Repeated search values are processed once.

Choose `fuel_type` from regular, midgrade, premium, diesel, e85 and unl88. Regular is the default. This choice selects stations carrying that grade; the output includes reports for all available grades at those stations. UNL88 corresponds to E15 in the original station data. The numeric `fuel` alias accepts 1, 2, 3, 4, 5 and 12 respectively. An explicitly supplied `fuel_type` takes precedence.

Set `max_stations_per_location` to a value between 1 and 500. The default is 20. This limit applies separately to each search location and includes unpriced stations if you choose to include them. A case-insensitive `brand` name, such as Shell, Chevron, Costco or Esso, restricts the results to that brand. Unsupported brand names produce a clear input error.

`max_price_age_hours` limits how old each price report may be. Zero, the default, keeps all valid reports regardless of age. Cash and credit are checked individually: an old cash report can disappear while a recent credit report remains available for the same grade.

`include_nearby` defaults to true. When a ZIP or postal search contains fewer stations than requested, nearby results supplement it using the location's centre. Set this option to false when you need the strict postal search results. A postal search can include a station whose recorded postcode differs from the searched code because the source maintains its own search areas.

### GasBuddy API output

The default dataset contains one row per unique station per search location. A station found for two different locations appears once for each location, with `search_location` identifying the search that produced it.

Identity fields include `place_id` (the GasBuddy station id), `name`, `url`, `street`, `city`, `postal_code`, `state`, `country_code`, `lat` and `lng`. The `rating` and `reviews_count` fields contain the star rating and number of ratings; stations without a rating keep null values, which does not mean a score of zero. `brand`, `brand_id` and `brands` separate the fuel brand from any convenience-store brand.

The `prices` array holds each fuel grade with its cash price, credit price, report times and reporter nicknames. The flat `price_cash` and `price_credit` fields expose the requested grade for simple spreadsheet comparisons. Missing reports become null, and a source value of zero is never presented as free fuel. `fetched_at` records when the row was collected.

US prices use `USD/gallon`. Canadian prices use `CAD-cent/liter`: a Canadian amount is expressed in cents, not dollars per litre. Read `unit` alongside every price and do not combine the two countries' raw amounts without conversion.

Real example, a search for `77002` (selected fields of the first station, collected 2026-10-27):

```json
{
  "place_id": "34207",
  "name": "Chevron",
  "url": "https://www.gasbuddy.com/station/34207",
  "street": "2222 Louisiana St",
  "city": "Houston",
  "postal_code": "77002",
  "state": "TX",
  "country_code": "US",
  "lat": 29.749246571497,
  "lng": -95.375500917435,
  "rating": 3.6,
  "reviews_count": 70,
  "brand": "Chevron",
  "fuels": ["regular", "midgrade", "premium"],
  "price_cash": null,
  "price_credit": 3.85,
  "price_credit_posted_at": "2026-10-27T20:09:48.006Z",
  "unit": "USD/gallon",
  "currency": "USD",
  "has_price": true,
  "search_location": "77002"
}
```

Optional details include available fuel grades, distance in miles for coordinate searches, offers, active outage status and availability of GasBuddy payment.

### Use cases

- **Price comparison:** show the cheapest regular, diesel or premium near a visitor, with the age of each report visible.
- **Fleet and fuel-card planning:** pull diesel prices along planned routes and decide where to refuel.
- **Route and trip apps:** add station prices, ratings and coordinates to a map.
- **Market analysis:** schedule daily runs for a list of cities and track average prices by state, province or brand.
- **Brand monitoring:** filter on Shell, Costco, Esso or another brand to follow its price position.

### How it compares with other GasBuddy actors

Other GasBuddy actors on the Store mostly take one location per run or charge a start fee for every run. This one accepts many locations, coordinates and brand filters in a single run, keeps cash and credit prices separate instead of merging them, returns all fuel grades per station, and charges only for stations that carry at least one valid price report. Empty searches cost nothing.

### Pricing

Billing is based on delivered stations with at least one eligible cash or credit price report, across any available fuel grade. The `has_price` flag makes this condition explicit. A station does not need a price for the selected search grade if it has a valid price for another grade. The current amount per station is shown in the actor's Pricing tab. There is no separate start fee.

By default, stations without any eligible reports are omitted. Set `include_unpriced` to true to keep these diagnostic rows. Such rows have `has_price: false` and are not charged. Empty searches generate no station events. Runs on an unpaid Apify plan deliver at most ten rows; paid-plan runs follow the requested per-location limits.

### Coverage and limits

Reports are crowdsourced and can be incomplete, outdated or inconsistent. Use the report timestamps and the age filter to define which observations your application accepts. These records describe reported prices and do not guarantee the price at the pump when a driver arrives.

Text searches follow the source's price ordering, which can change between pages when stations share the same price. Results are deduplicated, but a large city search cannot guarantee exhaustive coverage. Coordinate and nearby searches follow distance ordering. When collection is incomplete, the run output includes a partial flag and an explanatory warning.

### FAQ

#### Can I retrieve both cash and credit prices?

Yes. Each fuel grade has separate cash and credit fields, reporting times and reporter names. Either can be null when there is no usable report. The actor does not substitute one payment method's price for another.

#### Why does my ZIP search return few or no stations?

Some postal areas contain no stations in the source's postal search. Nearby supplementation is enabled by default. Disable it only when strict postal membership matters more than finding nearby options. Unknown locations produce a not-found result without a station charge.

#### Are Canadian prices converted to dollars per litre?

No. They keep the source's Canadian cents-per-litre unit. Always inspect `unit`; the actor does not convert currency or volume.

#### Is this an official GasBuddy API?

No. GasBuddy does not offer a public API for station prices. This actor is an independent tool that collects the publicly shown station data and is not affiliated with GasBuddy.

#### Can I collect a single station by its identifier?

This version searches locations and coordinates. Station identifiers are returned as join keys, but direct station-id refresh is not a supported input. Use the address or coordinates for later searches.

# Actor input Schema

## `locations` (type: `array`):

US ZIP codes, Canadian postal codes, or cities with state/province.

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

Coordinates as lat,lng strings. May be combined with locations.

## `search` (type: `string`):

Alternative to locations; one search string or a list.

## `fuel_type` (type: `string`):

Fuel grade used to select stations. All available grades are returned.

## `fuel` (type: `integer`):

Numeric fuel alias: 1 regular, 2 midgrade, 3 premium, 4 diesel, 5 E85, 12 UNL88. fuel_type takes precedence when present. Allowed values: 1, 2, 3, 4, 5, 12.

## `brand` (type: `string`):

Case-insensitive brand name, for example Shell, Chevron, Costco or Esso.

## `max_price_age_hours` (type: `integer`):

Maximum report age per cash/credit price; zero disables age filtering.

## `max_stations_per_location` (type: `integer`):

Maximum delivered stations per search, including unpriced stations when requested.

## `include_nearby` (type: `boolean`):

Supplement ZIP/postal results with nearby stations, ordered by distance.

## `include_unpriced` (type: `boolean`):

Include stations without eligible price reports. These stations are not billable.

## `cursor` (type: `string`):

Opaque continuation from next_cursor. Keep all other input fields identical.

## Actor input object example

```json
{
  "locations": [
    "77002"
  ],
  "max_price_age_hours": 0,
  "max_stations_per_location": 20,
  "include_nearby": true,
  "include_unpriced": false
}
```

# Actor output Schema

## `results` (type: `string`):

Station rows with cash and credit price reports.

## `output` (type: `string`):

OUTPUT record with the run's counts and status flags.

## `errors` (type: `string`):

Failures with a code and a redacted message. Absent when the run had none.

# 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 = {
    "locations": [
        "77002"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("s-r/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 = { "locations": ["77002"] }

# Run the Actor and wait for it to finish
run = client.actor("s-r/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 '{
  "locations": [
    "77002"
  ]
}' |
apify call s-r/gasbuddy-fuel-prices --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,s-r/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/AXmjjiaX7eloPc699/builds/JYLXZ8VAeDdHDTdln/openapi.json