SEO API

Keyword Suggestions

Up to 100 related keyword ideas — each with full metrics — from one seed keyword.

Start free Try it

POST /api/v1/keywords/suggestions$0.02 / requestAuth: X-API-Key header

seonio / rest apiFrom the API docs

RequestPOST /api/v1/keywords/suggestions

curl -X POST https://seonio.com/api/v1/keywords/suggestions \
  -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",
  "keywords": [
    {
      "text": "keyword research tool",
      "volume": 90500,
      "cpc": 512,
      "low_cpc": 210,
      "high_cpc": 940,
      "competition": 71,
      "difficulty": 84,
      "intent": "commercial",
      "monthly_trend": [
        {
          "month": "2026-08",
          "value": 90500
        },
        {
          "month": "2026-07",
          "value": 74000
        },
        {
          "month": "2026-06",
          "value": 74000
        }
      ]
    },
    {
      "text": "free keyword research",
      "volume": 33100,
      "cpc": 388,
      "low_cpc": 150,
      "high_cpc": 720,
      "competition": 64,
      "difficulty": 66,
      "intent": "commercial",
      "monthly_trend": [
        {
          "month": "2026-08",
          "value": 33100
        },
        {
          "month": "2026-07",
          "value": 27100
        },
        {
          "month": "2026-06",
          "value": 27100
        }
      ]
    }
  ]
}

Contract

What to send and what comes back

Give a seed keyword and get back up to 100 related suggestions, each with search volume, CPC range, competition, difficulty, intent and a 12-month trend. Ideal for keyword expansion, content ideation and building topic lists.

Request body

Request body
Field	Type	Required	Description
`keyword`	string	required	The seed keyword to expand, e.g. "keyword research".
`country`	string	optional	Two-letter ISO country code (default "us"). 50 supported countries `dz`Algeria`ar`Argentina`au`Australia`at`Austria`bd`Bangladesh`be`Belgium`br`Brazil`bg`Bulgaria`ca`Canada`cz`Czechia`dk`Denmark`eg`Egypt`fi`Finland`fr`France`de`Germany`gh`Ghana`gr`Greece`hu`Hungary`in`India`id`Indonesia`ie`Ireland`it`Italy`jp`Japan`ke`Kenya`my`Malaysia`mx`Mexico`ma`Morocco`nl`Netherlands`nz`New Zealand`ng`Nigeria`no`Norway`pk`Pakistan`ph`Philippines`pl`Poland`pt`Portugal`ro`Romania`sa`Saudi Arabia`rs`Serbia`sg`Singapore`za`South Africa`es`Spain`lk`Sri Lanka`se`Sweden`ch`Switzerland`th`Thailand`tr`Turkiye`ae`United Arab Emirates`gb`United Kingdom (also `uk`, returned as gb)`us`United States`vn`Vietnam

Response

Response fields
Field	Type	Description
`keyword`	string	The seed keyword that was expanded.
`country`	string	The country the metrics were resolved for.
`keywords[].text`	string	The suggested keyword.
`keywords[].volume`	integer	Average monthly search volume.
`keywords[].cpc`	integer \| null	Average cost per click in US cents; null when the keyword's metrics came from Google Ads keyword ideas, which have no average (low_cpc and high_cpc are still set).
`keywords[].low_cpc`	integer	Google Ads' low top-of-page bid in US cents.
`keywords[].high_cpc`	integer	Google Ads' high top-of-page bid in US cents.
`keywords[].competition`	integer	Competition score (0–100).
`keywords[].difficulty`	integer \| null	Keyword difficulty (0–100); null when the keyword's metrics came from Google Ads keyword ideas, which have no difficulty.
`keywords[].intent`	string	Search intent (informational, navigational, commercial, transactional, unclear), or null when not classified yet: each call classifies up to 100 more, highest volume first.
`keywords[].monthly_trend`	object[]	The last 12 months of search volume, newest to oldest, each as { month: YYYY-MM, value }, labelled with the Google Ads month each value belongs to (the newest is usually two months back). Empty when Google has no monthly data. Until October 2026 these months were mislabeled; the values were right.

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/suggestions \
  -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/suggestions",
    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/suggestions", {
  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.

API key

JSON body

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

POST /api/v1/keywords/suggestionsSample response

{
  "country": "us",
  "keyword": "keyword research",
  "keywords": [
    {
      "competition": 71,
      "cpc": 512,
      "difficulty": 84,
      "high_cpc": 940,
      "intent": "commercial",
      "low_cpc": 210,
      "monthly_trend": [
        {
          "month": "2026-08",
          "value": 90500
        },
        {
          "month": "2026-07",
          "value": 74000
        },
        {
          "month": "2026-06",
          "value": 74000
        }
      ],
      "text": "keyword research tool",
      "volume": 90500
    },
    {
      "competition": 64,
      "cpc": 388,
      "difficulty": 66,
      "high_cpc": 720,
      "intent": "commercial",
      "low_cpc": 150,
      "monthly_trend": [
        {
          "month": "2026-08",
          "value": 33100
        },
        {
          "month": "2026-07",
          "value": 27100
        },
        {
          "month": "2026-06",
          "value": 27100
        }
      ],
      "text": "free keyword research",
      "volume": 33100
    }
  ]
}

Use cases

What developers build with it

Expanding a seed keyword into a full research list.
Content ideation and editorial calendars.
Finding long-tail variations with demand and intent.

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
Code	When
`200`	Success. The lookup completed and was charged, even if the response is empty. /keywords/global charges only the keywords it looked up.
`401`	Missing or unknown API key.
`402`	Not 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.
`403`	The account is not verified yet, or it is locked.
`422`	Invalid 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.
`429`	Rate 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.
`503`	A data provider failed or timed out (X-Outcome: temporary). Nothing was charged; retry after the seconds in the Retry-After header.

Related endpoints

More endpoints to use with the same API key. Every one draws on the same balance.

All 21 endpoints

$0.001 / keyword

Keyword Research

Volume, CPC, competition and a 12-month trend for up to 100 keywords in one call.

View docs

$0.005 / request

Keyword Difficulty

Country-specific ranking difficulty.

View docs

$0.001 / keyword

Keyword Intent

Search-intent classification for up to 100 keywords.

View docs

$0.01 / request

Keyword Demographics

Age and gender demand distribution.

View docs

$0.25 / request

Keyword Clustering

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

View docs

$0.01 / request + $0.001 / started 10 keywords

Keyword Metrics by Country

Localized metrics for up to 500 keywords in one country.

View docs

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