Skip to content
SEO API

Keyword Clustering

Group a keyword's universe into topic clusters by SERP overlap.

Start free Try it
POST /api/v1/keywords/clustering$0.25 / requestAuth: X-API-Key header
seonio / rest apiFrom the API docs
RequestPOST /api/v1/keywords/clustering
curl -X POST https://seonio.com/api/v1/keywords/clustering \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $SEONIO_API_KEY" \
  -d '{"country": "us", "keyword": "keyword research"}'
Response200 OK
{
  "keyword": "keyword research",
  "country": "us",
  "clusters": [
    {
      "name": "keyword research",
      "volume": 673000,
      "size": 3,
      "keywords": [
        {
          "text": "keyword research",
          "volume": 550000
        },
        {
          "text": "keyword research tool",
          "volume": 90500
        },
        {
          "text": "free keyword research",
          "volume": 33100
        }
      ],
      "shared_urls": [
        "https://ahrefs.com/keyword-generator",
        "https://moz.com/explorer"
      ]
    },
    {
      "name": "long tail keywords",
      "volume": 41200,
      "size": 2,
      "keywords": [
        {
          "text": "long tail keywords",
          "volume": 27100
        },
        {
          "text": "long tail keyword research",
          "volume": 14100
        }
      ],
      "shared_urls": [
        "https://backlinko.com/long-tail-keywords"
      ]
    }
  ],
  "uncategorized": [
    {
      "text": "keyword research course",
      "volume": 880
    },
    {
      "text": "keyword research for etsy",
      "volume": 720
    }
  ]
}
Contract

What to send and what comes back

Give a seed keyword and get back topic clusters: we expand it into its suggestion universe, fetch the Google SERP used for each, and group keywords that share ranking pages. Ideal for content planning, silo/hub-and-spoke architecture and pillar pages.

Request body

Request body
FieldTypeRequiredDescription
keyword string required The seed keyword to cluster, e.g. "keyword research".
country string optional Two-letter ISO country code for the SERPs (default "us").
50 supported countries
dzAlgeriaarArgentinaauAustraliaatAustriabdBangladeshbeBelgiumbrBrazilbgBulgariacaCanadaczCzechiadkDenmarkegEgyptfiFinlandfrFrancedeGermanyghGhanagrGreecehuHungaryinIndiaidIndonesiaieIrelanditItalyjpJapankeKenyamyMalaysiamxMexicomaMorocconlNetherlandsnzNew ZealandngNigerianoNorwaypkPakistanphPhilippinesplPolandptPortugalroRomaniasaSaudi ArabiarsSerbiasgSingaporezaSouth AfricaesSpainlkSri LankaseSwedenchSwitzerlandthThailandtrTurkiyeaeUnited Arab EmiratesgbUnited Kingdom (also uk, returned as gb)usUnited StatesvnVietnam

Response

Response fields
FieldTypeDescription
keyword string The seed keyword that was clustered.
country string The country the SERPs were fetched for.
clusters[] object[] Topic clusters, largest by volume first. Empty when no topic cluster formed.
clusters[].name string The cluster's head keyword (its highest-volume member).
clusters[].volume integer Combined monthly search volume of the cluster.
clusters[].size integer Number of keywords in the cluster.
clusters[].keywords[] object[] The member keywords, each as { text, volume }.
clusters[].shared_urls[] string[] Pages that rank across the cluster's members (the SERP overlap that grouped them).
uncategorized[] object[] Keywords no topic cluster took, each as { text, volume }, highest volume first. Not a cluster; often empty.
Code

Copy, paste, add your key

The same request in cURL, Python and Node.js.

cURL
curl -X POST https://seonio.com/api/v1/keywords/clustering \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"country": "us", "keyword": "keyword research"}'
Python
import requests

resp = requests.post(
    "https://seonio.com/api/v1/keywords/clustering",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"country": "us", "keyword": "keyword research"},
)
print(resp.json())
Node.js
const resp = await fetch("https://seonio.com/api/v1/keywords/clustering", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY",
  },
  body: JSON.stringify({"country": "us", "keyword": "keyword research"}),
});
console.log(await resp.json());
Playground

Run a real request

Send this request from your browser with your API key, or leave the key empty to see the sample response.

A successful run costs $0.25 / request. With no key, you see the sample response and nothing is charged.

POST /api/v1/keywords/clusteringSample response
{
  "clusters": [
    {
      "keywords": [
        {
          "text": "keyword research",
          "volume": 550000
        },
        {
          "text": "keyword research tool",
          "volume": 90500
        },
        {
          "text": "free keyword research",
          "volume": 33100
        }
      ],
      "name": "keyword research",
      "shared_urls": [
        "https://ahrefs.com/keyword-generator",
        "https://moz.com/explorer"
      ],
      "size": 3,
      "volume": 673000
    },
    {
      "keywords": [
        {
          "text": "long tail keywords",
          "volume": 27100
        },
        {
          "text": "long tail keyword research",
          "volume": 14100
        }
      ],
      "name": "long tail keywords",
      "shared_urls": [
        "https://backlinko.com/long-tail-keywords"
      ],
      "size": 2,
      "volume": 41200
    }
  ],
  "country": "us",
  "keyword": "keyword research",
  "uncategorized": [
    {
      "text": "keyword research course",
      "volume": 880
    },
    {
      "text": "keyword research for etsy",
      "volume": 720
    }
  ]
}
Use cases

What developers build with it

  • Building topic clusters and content silos from one seed keyword.
  • Planning pillar pages and their supporting articles.
  • Mapping a keyword universe to information architecture.
Status codes

The same contract on every endpoint

Error responses are JSON with a "detail" field. It is a message string unless the row above says otherwise.

Status codes
CodeWhen
200Success. The lookup completed and was charged, even if the response is empty. /keywords/global charges only the keywords it looked up.
401Missing or unknown API key.
402Not enough balance. "detail" is an object with "error", "message", "balance_required" and "balance_available". Requests still running hold their price until they finish, so a retry can succeed once they do.
403The account is not verified yet, or it is locked.
422Invalid request (wrong shape or types, a keyword over 200 characters, a URL the page checker cannot audit, a domain that does not exist, or a bare public suffix such as co.uk that groups many websites) — never charged. "detail" is usually a list of validation errors; an answer that retrying cannot change (such as a domain without a DNS record) is a message string with an X-Outcome header naming it: missing, unsupported, too_large or refused_input.
429Rate limit exceeded, never charged. Requests per second per account by plan: 5 on a free account, 10 on Starter, 15 on Pro and 20 on Business; retry after the Retry-After header. Also the page checker's provider limit.
503A data provider failed or timed out (X-Outcome: temporary). Nothing was charged; retry after the seconds in the Retry-After header.
FAQ

Questions, answered

Simple answers for developers using the API.

Every endpoint has a published USD price or formula. Requests draw from the same testing, included and Extra Usage balance as website and MCP actions: testing first, then included usage, then Extra Usage expiring soonest.

API actions require a verified account with a free $1 balance or an active subscription balance. Create and manage API keys from your account, then send the key in the X-API-Key header.

Yes. Your account shows API usage and remaining balance, so you can track costs while building and running automated workflows.

REST API and MCP requests per second depend on your plan: 5 on a free account, 10 on Starter, 15 on Pro and 20 on Business. Website data requests from the same account count toward the same second. Requests above the limit return HTTP 429 with a Retry-After header and are not charged; wait a second and retry.

Free $1 to test · No card required

Turn search insights into measurable growth

Start your SEO research in seconds.

Get started for free See pricing
SEO researchREST APIMCP