fuel-prices

name	fuel-prices
description	Monitor fuel prices in Germany using Tankerkönig API. Use when user asks about fuel/gas prices, wants to find cheap stations nearby, or needs refueling recommendations.

Fuel Price Skill ⛽

Monitor fuel prices in Germany using the free Tankerkönig API.

1. Quick Price Check

Get current prices near a location:

cd fuel-skill
TANKERKOENIG_API_KEY=xxx npx ts-node fuel-monitor.ts check

Or via curl:

curl -s "https://creativecommons.tankerkoenig.de/json/list.php?lat=LAT&lng=LNG&rad=5&sort=price&type=diesel&apikey=API_KEY"

Fuel Types

• diesel — Diesel
• e5 — Super E5
• e10 — Super E10

2. Script Usage

# Check current prices (saves to history)
npx ts-node fuel-monitor.ts check

# View price history
npx ts-node fuel-monitor.ts history

# Analyze patterns (best/worst days)
npx ts-node fuel-monitor.ts analyze

Configuration

Edit CONFIG in fuel-monitor.ts:

const CONFIG = {
  lat: 48.137,        // Your latitude
  lng: 11.575,        // Your longitude
  radius: 5,          // Search radius in km
  fuelType: 'diesel', // diesel, e5, or e10
  apiKey: process.env.TANKERKOENIG_API_KEY,
};

3. Output Format

⛽✅ **Diesel now: €1.639**
📍 JET — Hauptstraße 42, München (2.4 km)
📊 Area average: €1.672

Price 3.3¢ below weekly average (€1.672)

👉 Recommend filling up today!

Recommendations

Symbol	Meaning	Condition
⛽✅	Fill up	Price ≥3¢ below weekly avg
⏳	Wait	Price ≥3¢ above weekly avg
➖	Neutral	Price near average

4. API Reference

Tankerkönig API (free, CC BY 4.0):

Base: https://creativecommons.tankerkoenig.de/json

GET /list.php?lat=X&lng=Y&rad=R&type=TYPE&sort=price&apikey=KEY

Get API key: https://creativecommons.tankerkoenig.de/

5. Heartbeat Integration

Add to HEARTBEAT.md:

### ⛽ Fuel Prices (morning)
- Check prices in the morning
- Show cheapest + nearby option
- Recommend if price is below average
- Calculate cost for typical fill (e.g., 40L)

Example morning output:

⛽ Diesel
- **V-Markt** — €1.638 ✓ (2.4 km, open)
- Jet — €1.649 (1.2 km)
- Average ~€1.68

40L = €65.52 — Good price, fill up today!

6. Requirements

npm install
# or
npm install typescript ts-node @types/node

Environment:

export TANKERKOENIG_API_KEY=your-api-key

Files

• fuel-monitor.ts — Main script
• price-history.json — Local price history (auto-created)
• package.json — Dependencies

Tips

• Prices often lowest on Monday/Tuesday
• Prices often highest on Friday/weekend
• Check before holidays (prices spike)
• Evening prices sometimes lower than morning