Competitor Analyses API

The competitor analyses API runs a full competitor analysis for a project: identify the top-10 SERP competitors, cluster their content strategy, identify gaps, and re-rank based on actual SERP overlap metrics. All endpoints live under /v1/... and are team-scoped.

Module context: Competitor Analysis.

Endpoints

Start an analysis

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

The job runs asynchronously for 2–4 minutes — it collects the SERP top-10 for seed + 20 related keywords, scrapes the top competitor domains, clusters their content via embeddings, and compares against your own project.

Fetch detail

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

Response shape:

{
  "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 = how comprehensively a competitor covers the topic (0–100). self_coverage: false marks clusters where your project is missing — direct lead for content briefs.

Fetch gaps

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

Returns prioritized content gaps:

{
  "data": [
    {
      "topic": "crm-pricing-comparison",
      "search_volume": 3400,
      "difficulty": 28,
      "competitors_covering": 7,
      "priority": "high",
      "suggested_brief": "Comparison table of the top-10 CRMs by pricing tier..."
    }
  ]
}

priority is a heuristic combining search_volume, difficulty, and competitors_covering — high-priority gaps are the typical quick wins.

Complete example: analysis → gaps → article brief

PID=12

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

# 3) Fetch top-3 high-priority gaps
GAPS=$(curl -s "$BASE/competitor-analyses/$ID/gaps" \
  -H "Authorization: Bearer $TOKEN" \
  | jq -c '[.data[] | select(.priority=="high")][:3]')

# 4) Create an article stub for each gap (<a href="/wiki/api/articles" class="wiki-link">Articles API</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-rank

If the SERP-based ranking does not match your business logic (e.g. you want to sort by domain authority or brand relevance), you can re-rank the competitors without rerunning the analysis:

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 & pitfalls

• 20 credits are charged upfront. On failed status, credits are refunded via the standard refund logic — see Credits.
• Async — 2–4 minutes. Do not poll synchronously below a 10 s interval; the endpoint only returns coarse-grained status.
• seed_keyword is the lever. Too generic ("software") → competitors not thematically relevant. Specific ("b2b crm software for agencies") → better results.
• Re-rank is non-destructive. The original SERP ranking is preserved in the competitors_serp_order field.

Related: Projects API · Articles API · Credits · Competitor Analysis.