API Competitor Analyses

L'API Competitor Analyses effectue une analyse complète de la concurrence pour un projet : identifier les concurrents top-10 SERP, clusteriser leur stratégie de contenu, repérer les gaps et re-ranker sur la base de métriques d'overlap SERP réelles. Tous les endpoints sont sous /v1/... et team-scoped.

Contexte du module : Competitor Analysis.

Endpoints

Démarrer une analyse

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"
  }'

Réponse 202 Accepted :

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

Le job tourne en async pendant 2 à 4 minutes — il collecte le SERP top-10 pour le seed + 20 mots-clés liés, scrape les domaines des principaux concurrents, clusterise leur contenu via embeddings et compare au projet.

Récupérer le détail

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

Forme de la réponse :

{
  "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 = à quel point un concurrent couvre largement le champ thématique (0–100). self_coverage: false marque les clusters dans lesquels ton projet est absent — leads directs pour des briefs de contenu.

Récupérer les gaps

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

Renvoie des lacunes de contenu priorisées :

{
  "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 est une heuristique combinant search_volume, difficulty et competitors_covering — les gaps high priority sont les quick wins typiques.

Exemple complet : analyse → gaps → brief d'article

PID=12

# 1) Dispatcher l'analyse
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) Poller jusqu'à completed (~3 min)
while [ "$(curl -s "$BASE/competitor-analyses/$ID" \
  -H "Authorization: Bearer $TOKEN" | jq -r .status)" != "completed" ]; do
  sleep 30
done

# 3) Récupérer les top-3 gaps high priority
GAPS=$(curl -s "$BASE/competitor-analyses/$ID/gaps" \
  -H "Authorization: Bearer $TOKEN" \
  | jq -c '[.data[] | select(.priority=="high")][:3]')

# 4) Créer un stub d'article pour chaque gap (<a href="/wiki/api/articles" class="wiki-link">API Articles</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

Si l'ordre basé sur le SERP ne colle pas à la logique business (par ex. tu veux trier par Domain Authority ou pertinence de marque), tu peux re-ranker les concurrents sans relancer l'analyse :

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"}'

Notes & pièges

• 20 crédits sont prélevés à l'avance. Sur un statut failed, les crédits sont remboursés via la logique de refund standard — voir Crédits.
• Async — 2 à 4 minutes. Ne polle pas en synchrone à intervalle < 10 s, l'endpoint ne renvoie un statut qu'à granularité grossière.
• seed_keyword est le levier. Trop générique (« software ») → concurrents thématiquement à côté. Spécifique (« b2b crm software for agencies ») → meilleurs résultats.
• Re-Rerank est non-destructif. L'ordre SERP original reste préservé dans le champ competitors_serp_order.

Voir aussi : API Projets · API Articles · Crédits · Competitor Analysis.