Keywords-API

Die Keywords-API deckt drei Aufgaben ab: Keywords zu einem Projekt verwalten (CRUD), neue Ideen per Recherche-Endpoint generieren und bestehende Keywords mit der A→Z-Expansion auf hunderte Long-Tails fächern. Alle Endpoints liegen unter /v1/... und sind team-scoped via auth:sanctum.

Modul-Kontext: Keyword Explorer · Schritt-für-Schritt-Anleitung: Keyword-Recherche.

CRUD am Projekt

Keywords gehören immer zu einem Projekt. Listen + Anlegen passieren projekt-scoped, Löschen direkt über die ID.

TOKEN="$RANKION_API_TOKEN"
BASE="https://rankion.ai/api/v1"
PID=12

curl -X POST "$BASE/projects/$PID/keywords" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"keyword":"ai content tools","language":"en","country":"US"}'

Recherche

Der Research-Endpoint liefert verwandte Keyword-Ideen plus Such-Volumen, Difficulty und Intent-Klassifikation für einen Seed-Term.

curl -X POST "$BASE/keywords/research" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"seed":"ai writing","language":"en","country":"US","project_id":12}'

Antwort: Liste mit keyword, search_volume, kd_score, intent. Die Treffer werden — falls project_id angegeben — direkt am Projekt persistiert und sind dann via GET /v1/projects/{project}/keywords abrufbar.

Tieferer SERP-Drilldown (Volume-Trends, SERP-URLs, Related, Questions) läuft über POST /v1/explorer und GET /v1/explorer/{keyword} — siehe Keyword Explorer.

A→Z-Expansion (async)

Generiert systematisch Long-Tail-Variationen entlang Frage-Mustern, Modifiern und Alphabet-Suffixen. Läuft asynchron, weil ein einzelnes Seed-Keyword 200–500 Long-Tails erzeugen kann.

# Expansion starten
curl -X POST "$BASE/keywords/$KW/expand" \
  -H "Authorization: Bearer $TOKEN"

# Ergebnisse pollen (Job läuft 2–3 min)
curl "$BASE/keywords/$KW/expansions" \
  -H "Authorization: Bearer $TOKEN"

Antwort 202 Accepted:

{
  "keyword_id": 481,
  "status": "pending",
  "message": "Expansion dispatched"
}

Die expansions[] enthalten neben keyword und search_volume auch ein cluster_label — damit lassen sich verwandte Long-Tails zu Topic-Clustern gruppieren, die später als Briefing für Artikel-Generierung dienen (Artikel-API → POST /articles/{id}/generate).

Komplettes Beispiel: Seed → Cluster → Artikel-Briefs

PID=12

# 1) Seed recherchieren
curl -s -X POST "$BASE/keywords/research" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"seed":"ai content tools","project_id":'$PID'}'

# 2) Best-fit Keyword identifizieren (z.B. höchstes Volumen mit KD < 40)
KW=$(curl -s "$BASE/projects/$PID/keywords" \
  -H "Authorization: Bearer $TOKEN" \
  | jq -r '[.data[] | select(.kd_score < 40)] | sort_by(-.search_volume) | .[0].id')

# 3) A→Z-Expansion starten
curl -X POST "$BASE/keywords/$KW/expand" \
  -H "Authorization: Bearer $TOKEN"

# 4) Pollen, dann Cluster auswerten
sleep 120
curl -s "$BASE/keywords/$KW/expansions" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.data | group_by(.cluster_label) | map({cluster: .[0].cluster_label, count: length})'

Hinweise & Pitfalls

• Expand ist async. Auch wenn 202 zurückkommt — Long-Tails entstehen erst nach Job-Abschluss. Polling-Intervall: 30–60 s.
• Research persistiert nur bei project_id. Ohne project_id ist der Call ein One-Shot — die Ideen liegen in der Antwort, nicht in der DB.
• Expansion baut auf bestehendem Keyword auf. Erst CRUD/Research, dann Expand auf der zurückgegebenen ID.
• Kein Bulk-Delete. Mehrere Keywords parallel löschen erfordert mehrere DELETE-Calls.

Verwandt: Projekte-API · Credits · Keyword Explorer · Keyword-Recherche.