Gas Price Alert

Overview

Automatically search for the cheapest gas prices in your area, with a focus on Costco and other discount stations. Get daily notifications with the best options within a specified radius.

Quick Start

1. Configure location - Set your city/coordinates and search radius
2. Run search - Find gas stations and estimated prices
3. Schedule daily alerts - Get morning notifications with cheapest options
4. Focus on Costco - Costco typically has gas $0.15-0.25 below market average

Workflow

Step 1: Configure Your Location

Option A: Use ZIP code (recommended)

# Search by ZIP code
python3 scripts/gas_alternative.py --zip 43215 --radius 20 --fuel 87 --summary

Option B: Use coordinates

Default locations are pre-configured for Columbus, Ohio:

# Columbus, OH (downtown)
lat: 39.9612
lon: -82.9988
radius: 20 miles

To use a different location:

python3 scripts/gas_alternative.py --lat \x3Clatitude> --lon \x3Clongitude> --radius \x3Cmiles>

Common US cities:

• Columbus, OH: 39.9612, -82.9988
• Chicago, IL: 41.8781, -87.6298
• New York, NY: 40.7128, -74.0060
• Los Angeles, CA: 34.0522, -118.2437
• Miami, FL: 25.7617, -80.1918

Step 2: Search for Gas Stations

# Search with summary output
python3 scripts/gas_alternative.py --lat 39.9612 --lon -82.9988 --radius 20 --fuel 87 --summary

# Save to file
python3 scripts/gas_alternative.py --lat 39.9612 --lon -82.9988 --radius 20 --fuel 87 --output gas_prices.json

Parameters:

• --zip: ZIP code (overrides lat/lon, e.g., --zip 43215)
• --lat: Latitude (default: 39.9612 - Columbus, OH)
• --lon: Longitude (default: -82.9988 - Columbus, OH)
• --radius: Search radius in miles (default: 20)
• --fuel: Fuel type - 87, 89, 91, diesel (default: 87)
• --base-price: Base price for estimation (default: 2.89)
• --output: Output file (default: gas_prices.json)
• --summary: Print human-readable summary to stdout

Step 3: Set Up Daily Alerts

Use OpenClaw cron to receive daily morning notifications:

{
  "name": "Gas price alert",
  "schedule": {
    "kind": "cron",
    "expr": "0 8 * * *",
    "tz": "America/New_York"
  },
  "payload": {
    "kind": "agentTurn",
    "message": "Get me gas prices for Columbus, OH this morning. Focus on Costco and show the cheapest 87 octane within 20 miles of downtown."
  },
  "sessionTarget": "main"
}

This runs every day at 8 AM Eastern Time.

Step 4: Receive Notifications

The agent will:

1. Search for gas stations in your area
2. Identify Costco and discount stations
3. Generate a summary with the cheapest options
4. Send the summary via Telegram

Example notification:

⛽ Gas Prices (87 Octane) - Columbus, OH

🏠 Costco (Typically Cheapest)
• Costco Gas
  💰 $2.69 (est.)
  📍 5000 Morse Rd, Columbus, OH 43213 (7.9 miles from downtown)

💡 Tip: Costco typically has gas $0.15-0.25 below market average.

Output Format

Each station includes:

{
  "source": "osm",
  "name": "Costco Gas",
  "brand": "Costco",
  "address": "5000 Morse Rd, Columbus, OH 43213",
  "lat": 39.9667,
  "lon": -82.8500,
  "distance": 7.9,
  "fuel_type": "87",
  "price": 2.69,
  "price_text": "$2.69 (est.)",
  "is_costco": true,
  "scraped_at": "2026-02-10T21:00:00.000Z"
}

How It Works

1. OpenStreetMap/Overpass API - Finds all gas stations in the area
2. Costco database - Known Costco locations are matched and prioritized
3. Price estimation - Costco prices estimated $0.15-0.25 below market average
4. Distance calculation - Uses geodesic distance for accurate mileage
5. Smart filtering - Removes duplicates and sorts by relevance

Limitations

• Real-time prices: Currently uses estimated prices for Costco. For exact prices, check GasBuddy.com or station apps.
• Coverage: Relies on OpenStreetMap data completeness
• Estimation accuracy: Costco prices estimated based on typical discount patterns

For Real-Time Prices

To get actual real-time prices:

1. GasBuddy.com - Check manually or use their commercial API
2. Station apps - Costco, Kroger, Shell, etc., have apps with current prices
3. AAA - Provides average prices by region
4. Waze - Community-sourced price updates

Troubleshooting

No stations found

• Increase the --radius parameter
• Verify coordinates are correct
• Check if the area has good OpenStreetMap coverage

Incorrect prices

• Prices for non-Costco stations are estimated as "N/A"
• Costco prices are estimates based on typical discount patterns
• For exact prices, use GasBuddy or the station's app

Geopy not installed

pip install geopy

Resources

scripts/gas_alternative.py

Main script for searching gas stations using OpenStreetMap and Overpass API.

Features:

• Finds all gas stations within radius
• Identifies Costco locations
• Estimates Costco prices
• Calculates distances
• Generates human-readable summaries

scripts/gasbuddy_search.py

Alternative script for GasBuddy integration (requires Playwright or API key).

Use when:

• You have a GasBuddy API key
• You need real-time prices
• You're willing to use Playwright for JavaScript rendering

references/locations.md

Coordinates and configurations for common US cities.

Dependencies

Install required packages:

pip install requests geopy

For Playwright-based GasBuddy scraping (optional):

pip install playwright
playwright install