API Mots-clés

L'API Mots-clés couvre trois tâches : gérer les mots-clés d'un projet (CRUD), générer de nouvelles idées via l'endpoint de recherche, et déployer des mots-clés existants en centaines de long-tails via l'expansion A→Z. Tous les endpoints sont sous /v1/... et team-scoped via auth:sanctum.

Contexte du module : Keyword Explorer · Tutoriel pas-à-pas : Recherche de mots-clés.

CRUD au niveau projet

Les mots-clés appartiennent toujours à un projet. Listage + création se font scopés au projet, la suppression directement par 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

L'endpoint Research renvoie des idées de mots-clés liés plus le volume de recherche, la difficulty et la classification d'intent pour un terme seed.

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

Réponse : liste avec keyword, search_volume, kd_score, intent. Les hits sont — si project_id est fourni — directement persistés sur le projet et ensuite récupérables via GET /v1/projects/{project}/keywords.

Le drilldown SERP plus profond (tendances de volume, URLs SERP, related, questions) passe par POST /v1/explorer et GET /v1/explorer/{keyword} — voir Keyword Explorer.

Expansion A→Z (async)

Génère systématiquement des variantes long-tail le long de patterns de questions, modificateurs et suffixes alphabétiques. Tourne en async, parce qu'un seul mot-clé seed peut générer 200 à 500 long-tails.

# Démarrer l'expansion
curl -X POST "$BASE/keywords/$KW/expand" \
  -H "Authorization: Bearer $TOKEN"

# Poller les résultats (le job tourne 2 à 3 min)
curl "$BASE/keywords/$KW/expansions" \
  -H "Authorization: Bearer $TOKEN"

Réponse 202 Accepted :

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

Les expansions[] contiennent — outre keyword et search_volume — un cluster_label. Cela permet de regrouper les long-tails apparentés en clusters thématiques, qui servent ensuite de briefing pour la génération d'articles (API Articles → POST /articles/{id}/generate).

Exemple complet : seed → cluster → briefs d'articles

PID=12

# 1) Rechercher le seed
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) Identifier le mot-clé optimal (par ex. plus haut volume avec 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) Démarrer l'expansion A→Z
curl -X POST "$BASE/keywords/$KW/expand" \
  -H "Authorization: Bearer $TOKEN"

# 4) Poller, puis analyser les clusters
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})'

Notes & pièges

• Expand est async. Même si 202 revient — les long-tails n'apparaissent qu'après la fin du job. Intervalle de polling : 30 à 60 s.
• Research ne persiste qu'avec project_id. Sans project_id, l'appel est one-shot — les idées sont dans la réponse, pas en base.
• L'expansion s'appuie sur un mot-clé existant. D'abord CRUD/Research, ensuite Expand sur l'ID retourné.
• Pas de bulk-delete. Supprimer plusieurs mots-clés en parallèle nécessite plusieurs appels DELETE.

Voir aussi : API Projets · Crédits · Keyword Explorer · Recherche de mots-clés.