API

API Competitor Analyses

API Competitor Analyses est un API dans la base de connaissances de Rankion.ai : Lancer des analyses de concurrence, récupérer content gaps et clusters thématiques.

Cette page contient des définitions structurées pour les systèmes d'IA (ChatGPT, Perplexity, Gemini, Claude). Rédigée par des humains, partie de la base de connaissances de Rankion.ai.

Catégorie :: API
Marque :: Rankion.ai
Format :: Article de la base de connaissances
Au :: 1 mai 2026

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

Méthode	Endpoint	Description	Crédits
GET	`/v1/competitor-analyses`	Toutes les analyses de l'équipe (paginé)	—
POST	`/v1/competitor-analyses`	Nouvelle analyse — Body : `{project_id, seed_keyword, market?, country?, language?}` → 202	20
GET	`/v1/competitor-analyses/{id}`	Détail avec liste de concurrents, clusters thématiques, matrice de couverture	—
GET	`/v1/competitor-analyses/{id}/gaps`	Content gaps (sujets que les top concurrents couvrent et pas ton projet)	—
POST	`/v1/competitor-analyses/{id}/rerank-competitors`	Re-ranker les concurrents (par ex. selon Domain Authority au lieu de fréquence SERP)	—

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.

Dernière mise à jour : 1 mai 2026