Competitor-Analyses-API

Die Competitor-Analyses-API führt eine vollständige Konkurrenz-Analyse für ein Projekt durch: Top-10-SERP-Konkurrenten ermitteln, deren Content-Strategie clustern, Gaps identifizieren und Re-Ranking auf Basis tatsächlicher SERP-Overlap-Metriken. Alle Endpoints liegen unter /v1/... und sind team-scoped.

Modul-Kontext: Competitor Analysis.

Endpoints

Analyse starten

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

curl -X POST "$BASE/competitor-analyses" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "project_id":12,
    "seed_keyword":"crm software",
    "market":"global",
    "country":"US",
    "language":"en"
  }'

Response 202 Accepted:

{
  "id": 8,
  "status": "pending",
  "message": "Competitor analysis dispatched"
}

Der Job läuft asynchron 2–4 Minuten — er sammelt SERP-Top-10 für Seed + 20 verwandte Keywords, scrapet die Top-Konkurrenten-Domains, clustert deren Content per Embeddings und vergleicht gegen das eigene Projekt.

Detail abrufen

curl "$BASE/competitor-analyses/$ID" \
  -H "Authorization: Bearer $TOKEN"

Response-Shape:

{
  "id": 8,
  "project_id": 12,
  "status": "completed",
  "seed_keyword": "crm software",
  "competitors": [
    {
      "domain": "hubspot.com",
      "serp_appearances": 47,
      "avg_position": 2.4,
      "coverage_score": 88,
      "topic_clusters": ["crm-pricing","crm-onboarding","crm-integrations"]
    }
  ],
  "topic_clusters": [
    {
      "label": "crm-pricing",
      "keywords": ["crm pricing","cheap crm","free crm"],
      "competitors_covering": ["hubspot.com","salesforce.com"],
      "self_coverage": false
    }
  ],
  "credits_used": 20
}

coverage_score = wie umfassend ein Konkurrent das Themenfeld abdeckt (0–100). self_coverage: false markiert Cluster, in denen dein Projekt fehlt — direkter Lead für Content-Briefs.

Gaps abrufen

curl "$BASE/competitor-analyses/$ID/gaps" \
  -H "Authorization: Bearer $TOKEN"

Liefert priorisierte Content-Lücken:

{
  "data": [
    {
      "topic": "crm-pricing-comparison",
      "search_volume": 3400,
      "difficulty": 28,
      "competitors_covering": 7,
      "priority": "high",
      "suggested_brief": "Vergleichstabelle der Top-10 CRMs nach Pricing-Tier..."
    }
  ]
}

priority ist eine Heuristik aus search_volume, difficulty und competitors_covering — high-priority Gaps sind die typischen Quick-Wins.

Komplettes Beispiel: Analyse → Gaps → Artikel-Brief

PID=12

# 1) Analyse dispatchen
ID=$(curl -s -X POST "$BASE/competitor-analyses" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"project_id":'$PID',"seed_keyword":"crm software","language":"en"}' \
  | jq -r .id)

# 2) Pollen bis completed (~3 min)
while [ "$(curl -s "$BASE/competitor-analyses/$ID" \
  -H "Authorization: Bearer $TOKEN" | jq -r .status)" != "completed" ]; do
  sleep 30
done

# 3) Top-3 high-priority Gaps holen
GAPS=$(curl -s "$BASE/competitor-analyses/$ID/gaps" \
  -H "Authorization: Bearer $TOKEN" \
  | jq -c '[.data[] | select(.priority=="high")][:3]')

# 4) Für jeden Gap einen Artikel-Stub anlegen (<a href="/wiki/api/articles" class="wiki-link">Artikel-API</a>)
echo "$GAPS" | jq -c '.[]' | while read GAP; do
  TOPIC=$(echo "$GAP" | jq -r .topic)
  curl -X POST "$BASE/projects/$PID/articles" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d "{\"title\":\"$TOPIC\",\"status\":\"draft\"}"
done

Re-Rerank

Wenn die SERP-basierte Rangfolge nicht zur Geschäftslogik passt (z.B. du willst nach Domain-Authority oder Marken-Relevanz sortieren), kannst du die Konkurrenten neu rangieren ohne die Analyse erneut zu fahren:

curl -X POST "$BASE/competitor-analyses/$ID/rerank-competitors" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"sort_by":"domain_authority","direction":"desc"}'

Hinweise & Pitfalls

• 20 Credits sind upfront. Bei failed-Status werden Credits über die normale Refund-Logik zurückgebucht — siehe Credits.
• Async — 2–4 Minuten. Nicht synchron pollen mit < 10s Intervall, der Endpoint liefert Status nur grob-granular.
• seed_keyword ist der Hebel. Zu generisch ("software") → Konkurrenten nicht thematisch passend. Spezifisch ("b2b crm software for agencies") → bessere Ergebnisse.
• Re-Rerank ist non-destructive. Die Original-SERP-Rangfolge bleibt im Feld competitors_serp_order erhalten.

Verwandt: Projekte-API · Artikel-API · Credits · Competitor Analysis.