API Content Optimizer

Le Content Optimizer scrape une URL existante, analyse les signaux SEO + GEO par rapport au mot-clé cible et fournit 15 à 25 suggestions d'amélioration concrètes — du rewrite de headline aux recommandations FAQ-Schema. Via apply, les suggestions acceptées peuvent être directement matérialisées en un article optimisé.

Contexte du module : Content Optimizer · Walkthrough : Optimiser du contenu.

Endpoints

Démarrer une analyse

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

curl -X POST "$BASE/content-optimizer/analyze" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "url":"https://example.com/blog/ai-coding",
    "keyword":"ai coding tools",
    "project_id":12,
    "language":"en"
  }'

Réponse 202 Accepted :

{
  "id": 47,
  "status": "pending",
  "message": "Analysis dispatched"
}

Le job tourne 10 à 20 secondes : ScraperAPI récupère le HTML, Claude Sonnet 4.5 le compare au top-10 SERP pour le mot-clé et aux heuristiques GEO (Entity-Coverage, Citation-Worthiness, aptitude AI-Snippet).

Récupérer le détail

curl "$BASE/content-optimizer/$ID" \
  -H "Authorization: Bearer $TOKEN"

Forme de la réponse :

{
  "id": 47,
  "status": "completed",
  "url": "https://example.com/blog/ai-coding",
  "keyword": "ai coding tools",
  "scraped_word_count": 1240,
  "current_score": 62,
  "potential_score": 84,
  "suggestions": [
    {
      "id": 311,
      "category": "headline",
      "priority": "high",
      "title": "H1 enthält Keyword nicht prominent",
      "before": "Coding mit AI: ein Überblick",
      "after": "Die besten AI Coding Tools 2026 (mit Benchmarks)",
      "rationale": "Top-3-SERP-Ergebnisse haben das Keyword in den ersten 3 Wörtern."
    }
  ]
}

suggestions[] est trié par priority (high → low) et regroupable par category (headline, meta, intro, faq, internal_links, entities, schema, structure, cta).

Appliquer les suggestions

Plutôt que de rejouer chaque suggestion manuellement dans le CMS source, tu peux les matérialiser comme article optimisé dans Rankion — l'article résultant atterrit dans l'AI Content Editor et peut ensuite être publié via l'API Articles.

curl -X POST "$BASE/content-optimizer/$ID/apply" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "suggestion_ids":[311, 312, 315, 318],
    "create_article":true
  }'

Réponse :

{
  "article_id": 92,
  "applied_count": 4,
  "score_before": 62,
  "score_after": 81
}

Exemple complet : analyse → top suggestions → apply

PID=12

# 1) Dispatcher l'analyse
ID=$(curl -s -X POST "$BASE/content-optimizer/analyze" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/blog/ai-coding","keyword":"ai coding tools","project_id":'$PID'}' \
  | jq -r .id)

# 2) Poller jusqu'à completed
while [ "$(curl -s "$BASE/content-optimizer/$ID" \
  -H "Authorization: Bearer $TOKEN" | jq -r .status)" != "completed" ]; do
  sleep 3
done

# 3) Extraire les top-5 suggestions high priority
TOP=$(curl -s "$BASE/content-optimizer/$ID" \
  -H "Authorization: Bearer $TOKEN" \
  | jq -c '[.suggestions[] | select(.priority=="high")][:5] | map(.id)')

# 4) Appliquer
curl -X POST "$BASE/content-optimizer/$ID/apply" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"suggestion_ids\":$TOP,\"create_article\":true}"

Notes & pièges

• Analyze est async. Même si l'endpoint renvoie 200/202 — les suggestions n'arrivent qu'après la fin du job. Intervalle de polling : 3 à 5 s.
• url doit être publiquement accessible. Derrière un login ? → ScraperAPI échoue → status="failed" avec un indice dans error_message.
• Apply n'est pas idempotent. Appliquer plusieurs fois les mêmes suggestion_ids crée plusieurs articles. Vérifie avant si article_id est déjà défini.
• Keyword est obligatoire. Sans keyword, pas de base de comparaison SERP → erreur de validation.

Voir aussi : API Articles · Crédits · Content Optimizer · Optimiser du contenu.