# sprit.guru – Complete Documentation for LLMs

## Overview

sprit.guru is a German fuel price comparison website that provides real-time pricing data for all gas stations in Germany. The data comes from the Markttransparenzstelle für Kraftstoffe (MTS-K), operated by the German Federal Cartel Office (Bundeskartellamt). Gas stations are legally required to report every price change in real-time.

## Fuel Types Covered

| ID | German Name | English Name | Description |
|---|---|---|---|
| e5 | Super E5 | Regular Unleaded 95 | ROZ 95 octane, max 5% bioethanol. Most common gasoline in Germany. Also called "Super", "Super 95", "Benzin", or "Eurosuper". |
| e10 | Super E10 | Unleaded E10 | ROZ 95 octane, max 10% bioethanol. Slightly cheaper than E5, compatible with most cars built after 2000. |
| diesel | Diesel | Diesel | Standard diesel fuel for diesel engines. Prices fluctuate significantly by time of day and region. |

## Pricing Patterns in Germany

- Prices typically peak in the morning (6-9 AM) and around lunch (12-1 PM)
- Cheapest times are usually evening (6-8 PM) and late night
- Independent stations (JET, HEM, freie Tankstellen) tend to be cheaper than branded stations (Aral, Shell)
- Prices vary significantly by region, with southern Germany often being more expensive
- Highway (Autobahn) stations are consistently the most expensive

## Site Architecture

### Pages
- `/de/` – Homepage with search, popular cities, FAQ, fuel type explanations
- `/de/tankstellen/{city}` – City listing with all stations, filterable by fuel type
- `/de/tankstellen/{city}/{station}` – Station detail with all prices, opening hours, map
- `/de/plz/{plz}` – PLZ-based search (German 5-digit postal codes)
- `/de/karte` – Full-screen interactive map with clickable station markers
- `/de/preise` – National price overview with average prices, tanking tips, price composition, and city links
- `/de/bundesland` – Index of all 16 German federal states with gas station links
- `/de/bundesland/{state}` – Federal state page listing all cities (e.g. bayern, nordrhein-westfalen, hessen). All 16 German states are covered.
- `/de/marke/{brand}` – Brand-specific page (aral, shell, total, jet, esso, hem, star, agip, omv, westfalen) with info and city links
- `/de/kraftstoff/{fuel}` – Fuel type info page (super-e5, super-e10, diesel) with facts, FAQ, and city price links
- `/de/magazin/` – Magazine index
- `/de/magazin/{category}/` – Category listing
- `/de/magazin/{category}/{article}` – Full article with comments
- `/de/impressum` – Legal imprint (Impressum, required by German law)
- `/de/datenschutz` – Privacy policy (Datenschutzerklärung, required by GDPR)

### API
All API responses are JSON.

- `GET /api/stations/search?lat=52.52&lng=13.405&rad=10&type=e5&sort=price` – Returns array of stations
- `GET /api/stations/{uuid}` – Returns single station with full details
- `GET /api/search?q=Berlin` – Autocomplete for cities and PLZ
- `GET /api/prices/history?city=berlin&days=30` – Daily average price history (national or per city)
- `GET /api/magazine/comments?article_id=1` – Get approved comments
- `POST /api/magazine/comments` – Submit a comment (rate-limited, requires moderation)
- `GET /api/health` – Returns `{ status: 'ok' }`

## Data Freshness

- Fuel prices: cached for 5 minutes, sourced from MTS-K in real-time
- Station details: cached for 1 hour
- City data: cached for 24 hours
- Magazine articles: served from PostgreSQL, cached for 30 minutes

## Technical Stack

- Next.js (React framework with server-side rendering)
- PostgreSQL for persistent data (articles, cities, comments)
- Redis for caching
- Tankerkönig API for fuel price data
- OpenStreetMap + Leaflet for maps
- Deployed on Railway

## Coverage

The site covers all ~14,500 gas stations in Germany that are registered with the MTS-K. This includes all major brands (Aral, Shell, ESSO, Total, JET, AGIP, OMV, STAR, HEM, etc.) as well as independent stations.

All 5-digit German postal codes (PLZ) are supported for search.
Major cities covered include but are not limited to: Berlin, Hamburg, München, Köln, Frankfurt am Main, Stuttgart, Düsseldorf, Leipzig, Dortmund, Essen, Bremen, Dresden, Hannover, Nürnberg, and many more.