Keywords

Keyword research is where most SEO work starts. This endpoint takes a seed keyword and returns related ideas with the numbers you need to pick a target: monthly search volume, CPC, competition, keyword difficulty, search intent and the last twelve months of volume so you can see whether interest is growing.

POST/v1/keywords/ideas

Keyword ideas

Returns keyword ideas around a seed keyword. The seed's own metrics come back under seed, so one call is enough to size a topic and its long tail.

Costs 2.5 credits per call, regardless of limit.

Required attributes

Name
keyword
Type
string
Description
The seed keyword, 1 to 200 characters.

Optional attributes

Name
country
Type
string
Description
ISO 3166-1 alpha-2 code such as US, ES or MX. Default US. See Countries and languages.
Name
language
Type
string
Description
ISO 639-1 code such as en or es. Defaults to the main language of the country, so ES means Spanish unless you say otherwise.
Name
limit
Type
integer
Description
How many ideas to return, 10 to 100. Default 20. Capped by your plan's result limit.

Response fields

Name
keywords[].volume
Type
integer
Description
Average monthly searches in the chosen country.
Name
keywords[].cpc
Type
number
Description
Average cost per click in USD.
Name
keywords[].competition
Type
string
Description
low, medium or high paid competition.
Name
keywords[].difficulty
Type
integer
Description
Keyword difficulty from 0 to 100. Higher is harder to rank for.
Name
keywords[].intent
Type
string
Description
informational, navigational, commercial or transactional.
Name
keywords[].trend_12m
Type
array
Description
Monthly volume for the last twelve months, oldest first.

Request

POST

/v1/keywords/ideas

curl -X POST https://suvjexogmfpvxjcktvuk.supabase.co/functions/v1/api/v1/keywords/ideas \
  -H "Authorization: Bearer $PENGU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword": "running shoes", "country": "US", "limit": 20}'

Response

{
  "data": {
    "seed": {
      "keyword": "running shoes",
      "volume": 301000,
      "cpc": 1.17,
      "competition": "high",
      "difficulty": 43,
      "intent": "transactional",
      "trend_12m": [
        {
          "month": "2025-08",
          "volume": 550000
        },
        {
          "month": "2025-09",
          "volume": 550000
        },
        // ...
      ]
    },
    "country": "US",
    "language": "en",
    "count": 10,
    "keywords": [
      {
        "keyword": "sneaker running shoes",
        "volume": 301000,
        "cpc": 1.17,
        "competition": "high",
        "difficulty": 7,
        "intent": "transactional",
        "trend_12m": [
          {
            "month": "2025-08",
            "volume": 550000
          },
          {
            "month": "2025-09",
            "volume": 550000
          },
          // ...
        ]
      },
      {
        "keyword": "running on shoes",
        "volume": 301000,
        "cpc": 1.17,
        "competition": "high",
        "difficulty": 43,
        "intent": "informational",
        "trend_12m": [
          {
            "month": "2025-08",
            "volume": 550000
          },
          {
            "month": "2025-09",
            "volume": 550000
          },
          // ...
        ]
      },
      // ...
    ]
  },
  "meta": {
    "credits_charged": 2.5,
    "credits_remaining": 483.5,
    "request_id": "e701ba5b-5985-43e2-9720-5c3f342dd64f"
  }
}