# SEO Rank Tracker (standalone)

Eigenständiger Rank-Tracker für `qrmaster.net` über die [Serper.dev](https://serper.dev)
Google-SERP-API. Läuft komplett außerhalb der Next.js-App, greift auf keine
Datenbank zu und hat keine npm-Dependencies — nur **Node 18+**.

Ersetzt kostenpflichtige Rank-Tracker (Wincher, SerpRobot, ~10–25 €/Monat) für
ein paar Cent pro Lauf.

## Setup

```bash
cd seo-tracker
cp .env.example .env
# SERPER_API_KEY in .env eintragen
```

## Nutzung

```bash
node track.mjs --dry-run          # zeigt Keywords + Credit-Schätzung, ohne API-Calls
node track.mjs --limit 5 --num 20 # kleiner Testlauf (~10 Credits)
node track.mjs                    # voller Lauf
node track.mjs --num 20           # nur Top 20 prüfen — spart 80% Credits

# eigene Liste / eigene Ausgabedatei (z. B. für Ad-hoc-Checks)
node track.mjs --keywords test.txt --out test.csv --num 20
```

Ergebnisse werden an `results.csv` angehängt (eine Zeile pro Keyword pro Lauf).
Beim zweiten Lauf zeigt die Konsole automatisch die Δ-Veränderung gegenüber dem
vorherigen Durchlauf.

## Keywords pflegen

`keywords.txt`, eine Zeile pro Keyword. `#` = Kommentar.
Land optional per Pipe anhängen:

```
qr code generator
qr code generator kostenlos | de
```

## Credits im Blick behalten

Serper rechnet **1 Credit pro 10 Ergebnisse** ab:

| Tiefe (`--num`) | Credits/Keyword | 43 Keywords | Läufe mit 2.500 Credits |
|---|---|---|---|
| 100 | 10 | 430 | ~5 |
| 20 | 2 | 86 | ~29 |
| 10 | 1 | 43 | ~58 |

**Empfehlung:** `RESULTS_PER_QUERY=20` in der `.env` und wöchentlich laufen lassen.
Damit reicht das kostenlose Guthaben gut ein halbes Jahr, und Positionen jenseits
von Platz 20 sind ohnehin kaum handlungsrelevant.

Für die tiefe Sicht (Top 100) einmal im Quartal `node track.mjs --num 100` laufen lassen.

## Automatisierung

Wöchentlich, montags 6 Uhr:

**Windows (Aufgabenplanung)**
```
schtasks /create /tn "QR Master Rank Tracker" /tr "node C:\Users\timo\Documents\qrmaster\QR-master\seo-tracker\track.mjs" /sc weekly /d MON /st 06:00
```

**Linux/Server (crontab)**
```
0 6 * * 1 cd /pfad/zu/seo-tracker && node track.mjs >> tracker.log 2>&1
```

## Ausgabe-Spalten

| Spalte | Bedeutung |
|---|---|
| `date` | Datum des Laufs |
| `keyword` / `country` | Abgefragte Query und Land |
| `position` | Position von qrmaster.net (leer = nicht in Top N) |
| `url` | Welche URL rankt |
| `top_competitor` | Domain auf Platz 1 (ausser eigener) |
| `ai_overview` | 1 = Google zeigte AI Overview / Answer Box |
| `error` | Fehlermeldung, falls der Call fehlschlug |

Die Spalte `ai_overview` ist der Einstieg ins AEO-Tracking: Keywords, bei denen
Google eine AI-Antwort ausspielt, verlieren organische Klicks — die gehören
priorisiert in die AEO-Backlog-Liste in `CLAUDE.md`.

## Blinder Fleck

Der Tracker sieht nur, was Serper sieht — Google-Rankings. Für **echte**
Impressions/Klicks empfiehlt sich zusätzlich die Google-Search-Console-API
(kostenlos, offizielle Daten).