# FuelPrices | Pay Per Result, Easy to Use, No Cookies (`johnvc/fuelprices`) Actor

Get live fuel prices, diesel, and gas price data. Pay only for the results you need - no subscriptions, no commitments. Perfect for tracking local fuel costs, building comparison apps, or analyzing price trends.\
Pay per usage: no setup, no minimums, no subscriptions.

- **URL**: https://apify.com/johnvc/fuelprices.md
- **Developed by:** [John](https://apify.com/johnvc) (community)
- **Categories:** News, E-commerce, Travel
- **Stats:** 131 total users, 28 monthly users, 99.8% runs succeeded, 14 bookmarks
- **User rating**: 3.69 out of 5 stars

## Pricing

$1.00 / 1,000 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.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

## Fuel Price Scraper

**Real-time gas station prices and details by ZIP, city, or place name.**

Get current fuel prices and station metadata in real time for any US location. Designed for quick setup, robust scraping, and clean outputs for analysis or downstream automation.

The coverage of this app is mostly in the United States, but does include some international locations such as Canada.

#### What this Actor does
- **Scrapes live prices** for a location and fuel type
- **Returns clean station data** (name, address, distance, ratings, cash/credit prices, timestamps)
- **Exports CSV automatically** with an optional custom filename

Common use cases:
- **Price monitoring** across cities/ZIP codes
- **Competitive analysis** for fuel retail
- **Data pipelines** feeding dashboards or alerts

#### Features
- **Simple input**: just provide `search` (ZIP/city).  This is the only mandatory input required.
- **Fuel selection**: `fuel` numeric code (see Inputs).  This is optional, but the default will be "1" (Regular Gasoline).
- **Freshness control**: `maxAge` in days.  This is optional, but the default will be "0" (any age).
- **Localized badges/text**: `lang`.  Currently only `en` is supported.
- **CSV export**: set `output_file`, or we generate a timestamped name. `output_file` must be a filename ending in `.csv` (no directory paths).

#### Quick start

Find this Actor on the [Apify Store](https://apify.com/johnvc/fuelprices?fpr=9n7kx3).

In Python, [see our quickstart tutorial here.](https://github.com/johnisanerd/Apify-Fuel-Prices-Scraper)

1) Add the Actor to your Apify account and open it.
2) Provide minimal input and run.

Example minimal input:
```json
{
  "search": "11507"
}
````

Example with options:

```json
{
  "search": "New York, NY",
  "fuel": 1,
  "lang": "en",
  "maxAge": 0,
  "output_file": "stations_nyc.csv"
}
```

Example using GPS coordinates (copy-paste from Google Maps):

```json
{
  "search": "36.0816642, -115.0534345",
  "fuel": 4
}
```

#### Input parameters

- **search** (string, required): Location query — accepts ZIP code, city name, or GPS coordinates copy-pasted directly from Google Maps (e.g., `"11507"`, `"Los Angeles"`, `"36.0816642, -115.0534345"`). Coordinates resolve to the nearest named area — for example, `36.0816642, -115.0534345` returns stations near Henderson, Nevada.
- **fuel** (integer, optional, default: 1): Fuel type code. Supported values are:
  - `1` = [Regular](https://en.wikipedia.org/wiki/Gasoline)
  - `2` = [Midgrade](https://en.wikipedia.org/wiki/Octane_rating)
  - `3` = [Premium](https://en.wikipedia.org/wiki/Octane_rating)
  - `4` = [Diesel](https://en.wikipedia.org/wiki/Diesel_fuel)
  - `5` = [E85](https://en.wikipedia.org/wiki/E85)
  - `12` = [Unleaded 88](https://en.wikipedia.org/wiki/Gasoline)
- **lang** (string, optional, default: "en"): Language code for localized fields. Current allowed value: `en`.
- **maxAge** (integer, optional, default: 0): Maximum age of price data in days. Use 0 for the freshest data available.
- **output\_file** (string, optional): Custom CSV filename. Must match `^[^/\\]+\\.csv$` (filename only, `.csv` extension required). If omitted, a timestamped filename is auto-generated (e.g., `gas_stations_11507_2025-08-19_11-01-12_1.csv`).

#### Local testing

- Run the shell-based test suite from the repository root:
  - `./test_actor.sh`
- The script runs valid and invalid input scenarios, covers all supported `fuel` values, and writes failure/warning details to:
  - `test_actor.log`

#### Output

Results are stored in the Actor dataset and a CSV file is written to the run storage. The dataset schema includes the following key fields:

- `id`, `name`, `distance`, `priceUnit`, `ratingsCount`, `starRating`
- Address: `address_line1`, `address_line2`, `address_locality`, `address_region`, `address_postalCode`
- Prices: `price_cash`, `price_cash_postedTime`, `price_credit`, `price_credit_postedTime`

Sample dataset item:

```json
{
  "id": 123456,
  "name": "USA",
  "distance": 1.2,
  "priceUnit": "USD/GAL",
  "ratingsCount": 65,
  "starRating": 4.5,
  "address_line1": "222-33 Braddock Ave",
  "address_line2": null,
  "address_locality": "Queens Village",
  "address_region": "NY",
  "address_postalCode": "11428",
  "price_cash": 2.85,
  "price_cash_postedTime": "2025-08-19T10:58:00Z",
  "price_credit": 2.95,
  "price_credit_postedTime": "2025-08-19T10:58:00Z"
}
```

CSV export

- A CSV is always written. Control the name via `output_file`, otherwise a timestamped default is used.
- Columns include: `id,name,distance,priceUnit,ratingsCount,starRating,address_line1,address_line2,address_locality,address_region,address_postalCode,price_credit,price_credit_postedTime,price_cash,price_cash_postedTime`.

#### Pricing

This Actor uses **pay-per-result** billing — you only pay for the station records returned.

| What | Cost |
|------|------|
| Per station result | $0.001 |
| 1,000 results | $1.00 |
| Typical run (15–25 stations) | ~$0.02 |

Billing is automatic — Apify charges per item pushed to the dataset. There is no charge for setup or for runs that return no results.

#### MCP / AI Integration

This Actor works well with **Claude Code** and any MCP-compatible client via the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp). An AI agent only needs to pass one parameter — `search` (a ZIP code, city name, or GPS coordinates) — and gets back structured JSON with station names, addresses, cash and credit prices, distance, and ratings. The output is ready for immediate use in pipelines, dashboards, or further analysis without any transformation.

**How to connect via MCP:**

1. Add the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp) to your MCP client (Claude Code, Cursor, or any compatible tool).
2. Search for this Actor by name and add it to your toolset.
3. Call it with a `search` value — ZIP code, city, or GPS coordinates — and get structured station data back instantly.

You can test MCP connectivity with the [Tester MCP Client](https://apify.com/jiri.spilka/tester-mcp?fpr=9n7kx3) Actor on Apify.

**Watch: How to set up and use Apify Actors with MCP**

[![How to set up and use Apify Actors with MCP](https://img.youtube.com/vi/4nxStxC1BJM/0.jpg)](https://www.youtube.com/watch?v=4nxStxC1BJM)

#### FAQ

**No results returned?**
The search location was not recognized or has no data available. Try a ZIP code instead of a city name — ZIP codes resolve more reliably. Check the run log for a warning message showing which search term returned no data.

**What countries are supported?**
Primarily the United States. Some Canadian locations are covered but availability varies by area.

**How fresh is the price data?**
Prices are crowd-reported and updated frequently. Use the `maxAge` parameter to filter out stations that haven't reported prices within a certain number of days (e.g., `maxAge: 3` returns only stations with prices from the last 3 days).

**What fuel types are supported?**
Regular (1), Midgrade (2), Premium (3), Diesel (4), E85 (5), and Unleaded 88 (12).

#### Support

- First, check your run logs in the **Apify Console** for diagnostics.
- If you need help, open a discussion and we will try to respond as quickly as possible.  Please include your run ID so we can quickly review the issue.

#### Roadmap

1. Brand filtering:  Search by brand or filter by brand name.
2. More fuel types and payment filters:  Add more fuel types and payment filters.
3. Price freshness filters by hours:  Add a freshness filter by hours.
4. Alerts and notifications:  Add alerts and notifications.
5. Search by distance:  Search by distance.
6. Business metadata:  Business metadata.

- category (e.g., gas station vs. convenience store)
- website URL, phone number
- opening hours
- neighborhood field
- Geo data
- latitude/longitude fields
- operational status and ads
- "temporarily closed" / "permanently closed"
- "is advertisement" flag
- reviews and media
- review distribution (1–5 stars breakdown)
- individual reviews
- station images

7. Output formats:  explicitly export Excel (XLSX) or HTML; we write CSV and dataset items (JSON via Apify dataset export)
8. Provenance: explicit "scrape timestamp" and "search query used" fields in each record (only price postedTime from source, not scrape time)

#### n8n integration

Available as an n8n community node, **[n8n-nodes-fuel-prices-api](https://www.npmjs.com/package/n8n-nodes-fuel-prices-api)**. In n8n, open Settings, Community Nodes, install `n8n-nodes-fuel-prices-api`, then use the Fuel Prices node in any workflow (it also works as an AI Agent tool).

Last Updated: 2026.06.15

# Actor input Schema

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

ZIP code, city name, or latitude/longitude coordinates (e.g., '11507', 'New York', '36.0816642, -115.0534345'). Coverage is primarily the United States, with some Canadian locations.

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

Fuel type to search for. 1=Regular (default), 2=Midgrade, 3=Premium, 4=Diesel, 5=E85, 12=Unleaded88.

## `lang` (type: `string`):

Language code for the search results. Currently only English is supported.

## `maxAge` (type: `integer`):

Maximum age of gas station data in days. Use 0 for no age restriction (all stations returned regardless of when prices were last reported). Higher values limit results to stations with prices reported within that many days.

## `output_file` (type: `string`):

Optional: Custom name for the output CSV file. If not provided, a timestamped filename will be automatically generated (e.g., gas\_stations\_11507\_2025-08-19\_11-01-12\_1.csv).

## Actor input object example

```json
{
  "search": "11507",
  "fuel": 1,
  "lang": "en",
  "maxAge": 0
}
```

# Actor output Schema

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

Backward-compatible alias for the overview dataset items endpoint

## `allResults` (type: `string`):

Backward-compatible alias for all raw dataset items

## `datasetItemsOverview` (type: `string`):

Dataset items transformed by the overview dataset schema view

## `datasetItemsRaw` (type: `string`):

All dataset items without a schema view transformation

## `dataset` (type: `string`):

Default dataset metadata endpoint

# 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 = {
    "search": "11507",
    "fuel": 1,
    "lang": "en"
};

// Run the Actor and wait for it to finish
const run = await client.actor("johnvc/fuelprices").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 = {
    "search": "11507",
    "fuel": 1,
    "lang": "en",
}

# Run the Actor and wait for it to finish
run = client.actor("johnvc/fuelprices").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": "11507",
  "fuel": 1,
  "lang": "en"
}' |
apify call johnvc/fuelprices --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=johnvc/fuelprices",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "FuelPrices | Pay Per Result, Easy to Use, No Cookies",
        "description": "Get live fuel prices, diesel, and gas price data. Pay only for the results you need - no subscriptions, no commitments. Perfect for tracking local fuel costs, building comparison apps, or analyzing price trends.  \nPay per usage: no setup, no minimums, no subscriptions.",
        "version": "0.0",
        "x-build-id": "jCEN8zkNIZeQ1rHgr"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/johnvc~fuelprices/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-johnvc-fuelprices",
                "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/johnvc~fuelprices/runs": {
            "post": {
                "operationId": "runs-sync-johnvc-fuelprices",
                "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/johnvc~fuelprices/run-sync": {
            "post": {
                "operationId": "run-sync-johnvc-fuelprices",
                "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": [
                    "search"
                ],
                "properties": {
                    "search": {
                        "title": "Search Location",
                        "minLength": 1,
                        "type": "string",
                        "description": "ZIP code, city name, or latitude/longitude coordinates (e.g., '11507', 'New York', '36.0816642, -115.0534345'). Coverage is primarily the United States, with some Canadian locations."
                    },
                    "fuel": {
                        "title": "Fuel Type",
                        "type": "integer",
                        "description": "Fuel type to search for. 1=Regular (default), 2=Midgrade, 3=Premium, 4=Diesel, 5=E85, 12=Unleaded88.",
                        "default": 1
                    },
                    "lang": {
                        "title": "Language",
                        "enum": [
                            "en"
                        ],
                        "type": "string",
                        "description": "Language code for the search results. Currently only English is supported.",
                        "default": "en"
                    },
                    "maxAge": {
                        "title": "Maximum Data Age",
                        "minimum": 0,
                        "type": "integer",
                        "description": "Maximum age of gas station data in days. Use 0 for no age restriction (all stations returned regardless of when prices were last reported). Higher values limit results to stations with prices reported within that many days.",
                        "default": 0
                    },
                    "output_file": {
                        "title": "Output CSV Filename",
                        "pattern": "^[^/\\\\]+\\.csv$",
                        "type": "string",
                        "description": "Optional: Custom name for the output CSV file. If not provided, a timestamped filename will be automatically generated (e.g., gas_stations_11507_2025-08-19_11-01-12_1.csv)."
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```