API de Keywords

La API de Keywords cubre tres tareas: gestionar keywords de un proyecto (CRUD), generar nuevas ideas con el endpoint de research y desplegar long-tails (cientos por keyword) con la expansión A→Z. Todos los endpoints viven bajo /v1/... y están scope al team mediante auth:sanctum.

Contexto del módulo: Keyword Explorer · guía paso a paso: Investigación de keywords.

CRUD por proyecto

Las keywords siempre pertenecen a un proyecto. Listar y crear se hacen scope al proyecto, eliminar directo por 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"}'

Research

El endpoint de research devuelve ideas de keywords relacionadas, junto con volumen de búsqueda, dificultad y clasificación de intención para un término semilla.

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

Respuesta: lista con keyword, search_volume, kd_score, intent. Si pasas project_id, los hits se persisten directamente en el proyecto y luego se consultan vía GET /v1/projects/{project}/keywords.

El drilldown más profundo de SERP (tendencias de volumen, URLs de SERP, related, questions) corre por POST /v1/explorer y GET /v1/explorer/{keyword} — ver Keyword Explorer.

Expansión A→Z (async)

Genera sistemáticamente variaciones long-tail siguiendo patrones de pregunta, modificadores y sufijos del alfabeto. Corre asíncronamente porque una sola keyword semilla puede producir 200–500 long-tails.

# Iniciar expansión
curl -X POST "$BASE/keywords/$KW/expand" \
  -H "Authorization: Bearer $TOKEN"

# Polling de resultados (el job tarda 2–3 min)
curl "$BASE/keywords/$KW/expansions" \
  -H "Authorization: Bearer $TOKEN"

Respuesta 202 Accepted:

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

Las expansions[] incluyen, además de keyword y search_volume, un cluster_label — con eso puedes agrupar long-tails relacionados en topic clusters que luego servirán como brief para la generación de artículos (API de Artículos → POST /articles/{id}/generate).

Ejemplo completo: Semilla → Cluster → Briefs de artículo

PID=12

# 1) Investigar la semilla
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) Identificar la keyword best-fit (p. ej. mayor volumen con 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) Iniciar expansión A→Z
curl -X POST "$BASE/keywords/$KW/expand" \
  -H "Authorization: Bearer $TOKEN"

# 4) Polling y luego analizar 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})'

Notas y pitfalls

• Expand es async. Aunque devuelva 202, los long-tails solo aparecen tras finalizar el job. Intervalo de polling: 30–60 s.
• Research solo persiste con project_id. Sin project_id, la llamada es one-shot — las ideas viven en la respuesta, no en la BD.
• La expansión parte de una keyword existente. Primero CRUD/Research, luego expand sobre el ID devuelto.
• No hay bulk-delete. Borrar varias keywords en paralelo requiere varias llamadas DELETE.

Relacionado: API de Proyectos · Créditos · Keyword Explorer · Investigación de keywords.