Aautoranko
Menu

API reference

Keyword research

AI-estimated keyword ideas and metrics (search volume, competition, difficulty and cost per click) to help you choose topics. The numbers are model estimates, not Google Ads data: use them to compare and prioritize.

1 endpointBase URL https://autoranko.com/api/public/v1Every request needs a bearer token

Research keywords

POSThttps://autoranko.com/api/public/v1/sites/{id}/keywords

Runs AI keyword research for the site. In ideas mode (the default) it expands your seed keywords into related long-tail keywords, a mix of informational and commercial searches. In metrics mode it estimates metrics for exactly the keywords you send. Each keyword comes with estimated monthly volume, competition, difficulty and cost per click.

All numbers are AI estimates (the response always has estimated: true): good for comparing and prioritizing keywords, not exact traffic data. Occasionally the list comes back empty or a metric is missing; retry if you need it. The request is synchronous and can take up to 2 minutes. Each request counts as one AI call in the site's monthly usage (ai_calls_used).

Allow at least 120 seconds before your HTTP client times out.

Request

Path parameters
Body parametersapplication/json
  • keywordsarray of stringsRequired
    Seed keywords (ideas) or the exact keywords to evaluate (metrics), as a JSON array of strings. Empty strings are dropped and only the first 20 are used; extra items are ignored, not rejected.
    Max items
    20
    Example
    ["emergency plumber"]
  • modestringOptional
    ideas expands the seeds into related keywords; metrics estimates metrics for exactly the keywords sent. Any other value runs ideas. The legacy name action is accepted as an alias.

    One ofideasmetrics

    Default
    ideas
    Example
    ideas
curl -X POST https://autoranko.com/api/public/v1/sites/1/keywords \
  -H "Authorization: Bearer $AUTORANKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "ideas",
    "keywords": [
      "emergency plumber"
    ]
  }'

Response

200OKKeywords with AI-estimated metrics.

Response bodyapplication/json
  • keywordsarray of objects
    Keywords with estimated metrics.
    keywords items(6)Keyword
    • keywordstring
      The keyword.
    • volumeintegerOptional
      Estimated monthly searches.
    • competitionstringOptional
      Estimated advertiser competition.

      One ofLOWMEDIUMHIGH

    • competition_indexintegerOptional
      Competition on a 0–100 scale.
    • difficultyintegerOptional
      Estimated difficulty of ranking on page one, 0–100.
    • cpcnumberOptional
      Estimated cost per click, in USD.
  • estimatedboolean
    Always true: every metric is an AI estimate.

Examples

POST/sites/1/keywords

Request body
{
  "mode": "ideas",
  "keywords": [
    "emergency plumber"
  ]
}
Response · 200 OK
{
  "keywords": [
    {
      "keyword": "emergency plumber near me",
      "volume": 14800,
      "competition": "HIGH",
      "competition_index": 92,
      "difficulty": 78,
      "cpc": 38.45
    },
    {
      "keyword": "24 hour emergency plumber",
      "volume": 5400,
      "competition": "HIGH",
      "competition_index": 89,
      "difficulty": 74,
      "cpc": 42.18
    },
    {
      "keyword": "emergency plumber cost",
      "volume": 1900,
      "competition": "MEDIUM",
      "competition_index": 67,
      "difficulty": 61,
      "cpc": 18.72
    },
    {
      "keyword": "emergency plumber for burst pipe",
      "volume": 880,
      "competition": "MEDIUM",
      "competition_index": 63,
      "difficulty": 55,
      "cpc": 29.64
    }
  ],
  "estimated": true
}

Errors

ErrorWhen
400invalid_bodyThe body isn't valid JSON (Invalid JSON body.).
400invalid_bodykeywords is missing, empty or contains only empty strings (keywords array is required.).
401missing_tokenThe Authorization: Bearer … header is missing.
401invalid_tokenThe token is malformed, unknown or revoked.
404not_foundNo site with this id belongs to your account (Site not found.).
429rate_limitedThe token made more than 120 requests in the last 60 seconds.
502upstream_errorThe AI provider returned an error or timed out (Keyword research failed, please retry.).

API version v1. Every path on this page is relative to https://autoranko.com/api/public/v1.