Keywords

Keyword research is where most SEO work starts. Three endpoints cover it: ideas expands a seed into related keywords with full metrics, suggest collects what search engines autocomplete so you catch the long tail before it has volume, and metrics sizes any list of keywords you already hold.

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

POST/v1/keywords/suggest

Keyword suggestions

What search engines autocomplete for a keyword: the phrases people actually type, merged from Google, Bing and DuckDuckGo and deduplicated. There are no volumes here, which is the point: autocomplete surfaces long tail and question phrases that a volume index has not caught up with yet. Pass the results to Keyword metrics to size them.

Costs 0.6 credits, or 1.2 credits with expand, which turns one seed into a few hundred phrases.

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. Default US.
Name
language
Type
string
Description
ISO 639-1 code. Defaults to the main language of the country.
Name
expand
Type
boolean
Description
Also query the seed followed by every letter a to z and by common question and modifier words (how, what, why, best, vs, for, near me, free, cheap, review). Default false.

Response fields

Name
suggestions[].keyword
Type
string
Description
The suggested phrase.
Name
suggestions[].sources
Type
array
Description
Which engines returned it. A phrase all three agree on is a safe bet.
Name
questions
Type
array
Description
The subset that starts with a question word, ready for an FAQ or People Also Ask section.

Request

POST

/v1/keywords/suggest

curl -X POST https://suvjexogmfpvxjcktvuk.supabase.co/functions/v1/api/v1/keywords/suggest \
  -H "Authorization: Bearer $PENGU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword": "crm software", "country": "US", "expand": true}'

Response

{
  "data": {
    "keyword": "crm software",
    "country": "US",
    "language": "en",
    "expanded": true,
    "count": 310,
    "sources": ["google", "bing", "duckduckgo"],
    "suggestions": [
      { "keyword": "crm software examples", "sources": ["google", "bing", "duckduckgo"] },
      { "keyword": "crm software meaning", "sources": ["google", "bing", "duckduckgo"] },
      { "keyword": "crm software free", "sources": ["google", "bing"] },
      { "keyword": "crm software for small business", "sources": ["google"] },
      // ...
    ],
    "questions": [
      "what crm software does amazon use",
      "how crm software works",
      // ...
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 482,
    "request_id": "0b7e2d1c-5e6a-4d7f-8c9b-1a2b3c4d5e6f"
  }
}

POST/v1/keywords/metrics

Keyword metrics

Volume, CPC, competition, difficulty, intent and the 12 month trend for keywords you already have, up to 100 per call. This is the endpoint for a client's Search Console export, a competitor's page titles, or the output of Keyword suggestions. The fields are the same as in keywords/ideas, so the two tables join without translation.

Costs 4.2 credits for up to 20 keywords and 8.3 credits for 100. The exact price scales with the number of keywords and is quoted in GET /v1/tools.

Required attributes

Name
keywords
Type
array
Description
1 to 100 keywords. A comma or newline separated string is accepted too. Duplicates are removed before pricing.

Optional attributes

Name
country
Type
string
Description
ISO 3166-1 alpha-2 code. Default US.
Name
language
Type
string
Description
ISO 639-1 code. Defaults to the main language of the country.

Response fields

Name
keywords[]
Type
array
Description
One entry per keyword found, with volume, cpc, competition, difficulty, intent and trend_12m, exactly as in keywords/ideas.
Name
not_found
Type
array
Description
Keywords the index has no data for in that country. Zero-volume phrases end up here rather than as zeros.

Request

POST

/v1/keywords/metrics

curl -X POST https://suvjexogmfpvxjcktvuk.supabase.co/functions/v1/api/v1/keywords/metrics \
  -H "Authorization: Bearer $PENGU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["crm software", "best crm for small business", "hubspot alternatives"], "country": "US"}'

Response

{
  "data": {
    "country": "US",
    "language": "en",
    "count": 3,
    "keywords": [
      {
        "keyword": "crm software",
        "volume": 74000,
        "cpc": 14.2,
        "competition": "high",
        "difficulty": 78,
        "intent": "commercial",
        "trend_12m": [{ "month": "2025-09", "volume": 74000 }, /* ... */]
      },
      // ...
    ],
    "not_found": []
  },
  "meta": {
    "credits_charged": 2.5,
    "credits_remaining": 479.5,
    "request_id": "b3d9a1e0-7c2f-4e88-9a6d-2f1e0c9b8a77"
  }
}

POST/v1/keywords/trends

Trends

Relative search interest over time for up to five keywords, compared against each other on a 0 to 100 scale. Volume tells you how big a term is; this tells you whether it is growing.

Costs 3.8 credits per call, whether you compare one keyword or five.

Required attributes

Name
keywords
Type
array
Description
1 to 5 keywords. Interest is relative to the highest point reached by any of them, so adding a keyword rescales the whole chart.

Optional attributes

Name
country
Type
string
Description
ISO 3166-1 alpha-2 country code. Default US.
Name
language
Type
string
Description
ISO 639-1 language code. Defaults to the language of the country.
Name
time_range
Type
string
Description
past_7_days, past_30_days, past_90_days, past_12_months or past_5_years. Default past_12_months.
Name
type
Type
string
Description
web, news, youtube or images. Default web.

Response fields

Name
summary[].trend_pct
Type
number
Description
The second half of the window against the first, as a percentage. null when the first half is flat zero and a percentage would divide by nothing.
Name
summary[].peak
Type
integer
Description
The highest point that keyword reached in the window.
Name
series
Type
array
Description
One row per period. values follows the order of keywords, and an entry is null where there is no data rather than 0, because a missing week is not a crash.

Request

POST

/v1/keywords/trends

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

Response

{
  "data": {
    "keywords": ["running shoes", "trail shoes"],
    "country": "US",
    "language": "en",
    "time_range": "past_12_months",
    "type": "web",
    "checked_at": "2026-09-20T09:38:51.220Z",
    "summary": [
      { "keyword": "running shoes", "average": 74, "peak": 100, "trend_pct": -6 },
      { "keyword": "trail shoes", "average": 21, "peak": 34, "trend_pct": 18 }
    ],
    "series": [
      { "date_from": "2025-09-21", "date_to": "2025-09-27", "values": [71, 18] },
      { "date_from": "2025-09-28", "date_to": "2025-10-04", "values": [69, 19] }
    ]
  },
  "meta": {
    "credits_charged": 2.5,
    "credits_remaining": 2797.5,
    "request_id": "c47e1b90-2a83-4d6f-8e15-9b0c3a7d2f41"
  }
}