API de Competitor Analyses

La API de Competitor Analyses ejecuta un análisis completo de competencia para un proyecto: identifica los Top-10 competidores en SERP, clusteriza su estrategia de contenido, detecta gaps y reordena los resultados con base en métricas reales de overlap SERP. Todos los endpoints viven bajo /v1/... y están scope al team.

Contexto del módulo: Competitor Analysis.

Endpoints

Iniciar análisis

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

Response 202 Accepted:

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

El job corre asíncronamente 2–4 minutos — recolecta SERP Top-10 para la semilla + 20 keywords relacionadas, scrapea los dominios de los top competidores, los clusteriza vía embeddings y los compara con tu propio proyecto.

Obtener detalle

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

Forma de la response:

{
  "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 = qué tan exhaustivamente cubre un competidor el campo temático (0–100). self_coverage: false marca clusters donde tu proyecto está ausente — un lead directo para content briefs.

Obtener gaps

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

Devuelve lagunas de contenido priorizadas:

{
  "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 es una heurística sobre search_volume, difficulty y competitors_covering — los gaps high-priority son los típicos quick wins.

Ejemplo completo: Análisis → Gaps → Brief de artículo

PID=12

# 1) Dispatchar análisis
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) Polling hasta completed (~3 min)
while [ "$(curl -s "$BASE/competitor-analyses/$ID" \
  -H "Authorization: Bearer $TOKEN" | jq -r .status)" != "completed" ]; do
  sleep 30
done

# 3) 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) Crear un stub de artículo por cada gap (<a href="/wiki/api/articles" class="wiki-link">API de Artículos</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 la ordenación basada en SERP no encaja con la lógica de negocio (p. ej. quieres ordenar por Domain Authority o relevancia de marca), puedes reordenar los competidores sin volver a ejecutar el análisis:

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

Notas y pitfalls

• Los 20 créditos van por adelantado. En failed, los créditos se reembolsan vía la lógica normal de refund — ver Créditos.
• Async — 2–4 minutos. No hagas polling síncrono con intervalo < 10 s; el endpoint solo entrega status con granularidad gruesa.
• seed_keyword es la palanca. Demasiado genérica («software») → competidores poco relevantes temáticamente. Específica («b2b crm software for agencies») → mejores resultados.
• Re-Rerank no es destructivo. El orden SERP original se conserva en el campo competitors_serp_order.

Relacionado: API de Proyectos · API de Artículos · Créditos · Competitor Analysis.