gas-price-alert

通过每日通知查找和监控天然气价格。在搜索特定区域最便宜的汽油、跟踪 Costco 和其他折扣加油站或设置每日汽油价格警报时使用。支持具有可配置半径和燃料类型的任何美国位置。

# 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)**

```bash
# 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:

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

To use a different location:

```bash
python3 scripts/gas_alternative.py --lat <latitude> --lon <longitude> --radius <miles>
```

**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

```bash
# 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:

```json
{
  "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:

```json
{
  "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

```bash
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:

```bash
pip install requests geopy
```

For Playwright-based GasBuddy scraping (optional):

```bash
pip install playwright
playwright install
```

---

## 中文说明

# Gas Price Alert

## 概述

自动搜索您所在区域最便宜的汽油价格，重点关注 Costco 和其他折扣加油站。在指定半径内获取每日通知，列出最佳选择。

## 快速开始

1. **配置位置** - 设置您的城市/坐标和搜索半径
2. **运行搜索** - 查找加油站和估算价格
3. **安排每日警报** - 在早晨收到包含最便宜选项的通知
4. **关注 Costco** - Costco 的汽油价格通常比市场平均价低 $0.15-0.25

## 工作流程

### 步骤 1：配置您的位置

**选项 A：使用邮政编码（推荐）**

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

**选项 B：使用坐标**

默认位置已预先配置为俄亥俄州哥伦布市：

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

要使用其他位置：

```bash
python3 scripts/gas_alternative.py --lat <latitude> --lon <longitude> --radius <miles>
```

**常见的美国城市：**
- 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

### 步骤 2：搜索加油站

```bash
# 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
```

**参数：**
- `--zip`: 邮政编码（覆盖 lat/lon，例如 `--zip 43215`）
- `--lat`: 纬度（默认值：39.9612 - Columbus, OH）
- `--lon`: 经度（默认值：-82.9988 - Columbus, OH）
- `--radius`: 搜索半径，单位为英里（默认值：20）
- `--fuel`: 燃料类型 - 87、89、91、diesel（默认值：87）
- `--base-price`: 用于估算的基准价格（默认值：2.89）
- `--output`: 输出文件（默认值：gas_prices.json）
- `--summary`: 将人类可读的摘要打印到 stdout

### 步骤 3：设置每日警报

使用 OpenClaw cron 接收每日早晨通知：

```json
{
  "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"
}
```

这将在每天东部时间上午 8 点运行。

### 步骤 4：接收通知

代理将：
1. 搜索您所在区域的加油站
2. 识别 Costco 和折扣加油站
3. 生成包含最便宜选项的摘要
4. 通过 Telegram 发送摘要

**示例通知：**

```
⛽ 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.
```

## 输出格式

每个加油站包含：

```json
{
  "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.)",
  "