keyword-research

name	keyword-research
description	Perform keyword research using the SemRush API. Use when the user says "find keywords", "keyword research", "what should I rank for", "keyword ideas", "search volume", "keyword difficulty", "topic clusters", "content gaps", or asks about SEO keywords for a topic or niche.

Keyword Research Skill

You are an expert SEO keyword researcher. Use the SemRush API to find, analyze, and organize keywords into actionable strategies.

Prerequisites

This skill requires SEMRUSH_API_KEY. Check for it in environment variables or in ~/.claude/.env.global. If not found, inform the user:

This skill requires a SemRush API key. Set it via:
  export SEMRUSH_API_KEY=your_key_here
Or add it to ~/.claude/.env.global

SemRush API Endpoints

Use curl via the Bash tool for all API calls. The base URL is https://api.semrush.com/.

Core Endpoints

1. Keyword Overview (phrase_all)

https://api.semrush.com/?type=phrase_all&key={KEY}&phrase={keyword}&database={db}&export_columns=Ph,Nq,Cp,Co,Nr,Td

Columns: Ph=Keyword, Nq=Search Volume, Cp=CPC, Co=Competition, Nr=Number of Results, Td=Trend

2. Related Keywords (phrase_related)

https://api.semrush.com/?type=phrase_related&key={KEY}&phrase={keyword}&database={db}&export_columns=Ph,Nq,Cp,Co,Nr,Td&display_limit=50

3. Keyword Questions (phrase_questions)

https://api.semrush.com/?type=phrase_questions&key={KEY}&phrase={keyword}&database={db}&export_columns=Ph,Nq,Cp,Co,Nr,Td&display_limit=50

4. Domain Organic Keywords (domain_organic)

https://api.semrush.com/?type=domain_organic&key={KEY}&domain={domain}&database={db}&export_columns=Ph,Po,Nq,Cp,Co,Tr,Tc,Nr,Td&display_limit=100

Additional columns: Po=Position, Tr=Traffic, Tc=Traffic Cost

5. Keyword Difficulty (phrase_kdi)

https://api.semrush.com/?type=phrase_kdi&key={KEY}&phrase={keyword}&database={db}&export_columns=Ph,Kd

Columns: Kd=Keyword Difficulty (0-100)

Database Codes

• us (United States - default)
• uk (United Kingdom)
• ca (Canada)
• au (Australia)
• de, fr, es, it, br, in, jp

Ask the user for target market if not specified. Default to us.

Research Process

Step 1: Understand the Brief

Ask or infer:

• Niche/Topic: What is the site about?
• Target audience: Who are they trying to reach?
• Business model: How do they monetize? (SaaS, ecommerce, ads, affiliate)
• Current domain: If they have one, pull existing rankings
• Target market: Which country/language?
• Competitors: Known competitors to analyze

Step 2: Seed Keyword Discovery

Generate 10-20 seed keywords based on the brief. Use three methods:

Method A: Brainstorm seeds from the topic

• Core product/service terms
• Problem terms ("how to fix...", "why is...")
• Audience terms (job titles, demographics)
• Alternative terms and synonyms

Method B: Pull competitor keywords using domain_organic for 2-3 competitor domains

Method C: Expand seeds using phrase_related and phrase_questions for each seed

Step 3: Analyze Each Keyword

For every keyword candidate, collect via API:

Metric	Source	What it tells you
Search Volume (Nq)	phrase_all	Monthly searches
Keyword Difficulty (Kd)	phrase_kdi	How hard to rank (0-100)
CPC (Cp)	phrase_all	Commercial value indicator
Competition (Co)	phrase_all	PPC competition (0-1)
Trend (Td)	phrase_all	12-month trend data
SERP Results (Nr)	phrase_all	Total competing pages

Step 4: Classify by Search Intent

Categorize every keyword into one of four intents:

Intent	Signals	Examples	Content Type
Informational	how, what, why, guide, tutorial, tips	"how to start a blog"	Blog post, guide, video
Navigational	brand names, specific product names, login	"semrush login"	Homepage, product page
Commercial	best, review, comparison, vs, top, alternatives	"best SEO tools 2025"	Comparison, review, listicle
Transactional	buy, price, discount, coupon, free trial, sign up	"semrush pricing"	Landing page, product page

Intent classification rules:

• "how to" / "what is" / "why" = Informational
• "{brand} + {feature}" = Navigational
• "best" / "top" / "vs" / "alternative" / "review" = Commercial Investigation
• "buy" / "price" / "discount" / "free" / "download" / "sign up" = Transactional
• If ambiguous, check the SERP: majority blog posts = informational, majority product pages = transactional

Step 5: Build Topic Clusters

Organize keywords into pillar-cluster structure:

Pillar Page: [Broad topic keyword - high volume, high difficulty]
  |
  +-- Cluster 1: [Subtopic keyword group]
  |     +-- Supporting keyword 1
  |     +-- Supporting keyword 2
  |     +-- Question keyword 1
  |
  +-- Cluster 2: [Subtopic keyword group]
  |     +-- Supporting keyword 1
  |     +-- Supporting keyword 2
  |
  +-- Cluster 3: ...

Clustering rules:

• Pillar: Volume > 5,000, KD 40-80, broad topic
• Cluster head: Volume 1,000-5,000, KD 20-50, specific subtopic
• Supporting: Volume 100-1,000, KD < 30, long-tail variations
• Each cluster should have 3-8 supporting keywords
• Every supporting page links back to the pillar page

Step 6: Prioritize with the KOB Score

Calculate the Keyword Opposition to Benefit (KOB) score for prioritization:

KOB Score = (Search Volume * CTR Estimate * Business Value) / Keyword Difficulty

Where:
- CTR Estimate: Position 1 = 0.30, Pos 2 = 0.15, Pos 3 = 0.10 (use 0.15 as default)
- Business Value: 3 = direct revenue keyword, 2 = consideration keyword, 1 = awareness keyword
- Keyword Difficulty: 1-100 from SemRush (use max(KD, 1) to avoid division by zero)

Priority tiers:

• KOB > 50: High priority - target first
• KOB 20-50: Medium priority - target in months 2-3
• KOB 5-20: Low priority - target later
• KOB < 5: Deprioritize unless strategically important

Step 7: Find Content Gaps

Compare the user's domain against competitors:

1. Pull top 100 keywords for each competitor via domain_organic
2. Identify keywords where competitors rank but user does not
3. Filter for keywords with KOB > 20
4. These are content gap opportunities

Output Format

Present results in this structure:

# Keyword Research Report: {Topic/Niche}
**Date:** {date}
**Target Market:** {country}
**Total Keywords Found:** {count}
**Total Monthly Search Volume:** {sum}

## Top 20 Keywords by KOB Score

| # | Keyword | Volume | KD | CPC | Intent | KOB Score |
|---|---------|--------|-----|-----|--------|-----------|
| 1 | {keyword} | {vol} | {kd} | ${cpc} | {intent} | {kob} |
| ... | ... | ... | ... | ... | ... | ... |

## Topic Clusters

### Pillar: {Pillar keyword} (Volume: {vol}, KD: {kd})

| Cluster | Head Keyword | Volume | KD | Supporting Keywords |
|---------|-------------|--------|-----|---------------------|
| {name} | {keyword} | {vol} | {kd} | kw1, kw2, kw3 |

### Content Plan

| Priority | Keyword | Intent | Content Type | Est. Monthly Traffic |
|----------|---------|--------|-------------|---------------------|
| 1 | {keyword} | {intent} | {type} | {vol * 0.15} |
| ... | ... | ... | ... | ... |

## Question Keywords (FAQ Opportunities)

| Question | Volume | KD | Suggested Content |
|----------|--------|-----|-------------------|
| {question} | {vol} | {kd} | {content type} |

## Content Gaps vs. Competitors

| Keyword | Volume | KD | Competitor Ranking | Opportunity |
|---------|--------|-----|--------------------|-------------|
| {keyword} | {vol} | {kd} | {competitor}: #{pos} | {content type} |

## Recommended Next Steps

1. {Specific action item with keyword target}
2. ...

Tips for Better Results

• Batch API calls to conserve API credits. Query related keywords in groups.
• Always check trends. A keyword with declining volume may not be worth targeting.
• CPC indicates money intent. High CPC keywords ($5+) usually have strong commercial intent even if not obvious.
• Low KD is not always easy. If all top results are from DR 80+ sites, a KD of 20 may still be hard for a new site.
• Local vs. national. For local businesses, append city/state to seed keywords.
• Seasonal keywords. Note if trends show seasonality; plan content 2-3 months before peak.
• If the API returns an error or no data, inform the user of the specific issue rather than guessing.

Supplementary API Integrations

These APIs complement SemRush and can be used as alternatives or for additional data points. They are not required if SemRush is available.

DataForSEO (Alternative/Complement to SemRush)

If DATAFORSEO_LOGIN and DATAFORSEO_PASSWORD are available, use DataForSEO for keyword search volume and related data. This is especially useful as a fallback when SemRush credits are limited or for cross-referencing data.

Search Volume Endpoint:

# Get keyword search volume data from DataForSEO
curl -s -X POST "https://api.dataforseo.com/v3/keywords_data/google_ads/search_volume/live" \
  -H "Authorization: Basic $(echo -n "${DATAFORSEO_LOGIN}:${DATAFORSEO_PASSWORD}" | base64)" \
  -H "Content-Type: application/json" \
  -d '[{"keywords": ["keyword1", "keyword2", "keyword3"], "location_code": 2840, "language_code": "en"}]'

Parsing the response:

# Extract keyword metrics from DataForSEO response
curl -s -X POST "https://api.dataforseo.com/v3/keywords_data/google_ads/search_volume/live" \
  -H "Authorization: Basic $(echo -n "${DATAFORSEO_LOGIN}:${DATAFORSEO_PASSWORD}" | base64)" \
  -H "Content-Type: application/json" \
  -d '[{"keywords": ["keyword1", "keyword2"], "location_code": 2840, "language_code": "en"}]' | \
  jq '.tasks[0].result[] | {
    keyword: .keyword,
    search_volume: .search_volume,
    competition: .competition,
    competition_index: .competition_index,
    cpc: .cpc,
    monthly_searches: .monthly_searches
  }'

Key fields:

• search_volume - Average monthly search volume
• competition - Competition level: "LOW", "MEDIUM", or "HIGH"
• competition_index - Numeric competition score (0-100)
• cpc - Cost per click in USD
• monthly_searches - Array of 12 monthly volume data points (useful for identifying seasonal trends)

Common location codes:

• 2840 - United States
• 2826 - United Kingdom
• 2124 - Canada
• 2036 - Australia
• 2250 - France
• 2158 - Germany

Keyword Suggestions Endpoint:

# Get keyword suggestions (similar to SemRush phrase_related)
curl -s -X POST "https://api.dataforseo.com/v3/keywords_data/google_ads/keywords_for_keywords/live" \
  -H "Authorization: Basic $(echo -n "${DATAFORSEO_LOGIN}:${DATAFORSEO_PASSWORD}" | base64)" \
  -H "Content-Type: application/json" \
  -d '[{"keywords": ["seed keyword"], "location_code": 2840, "language_code": "en", "sort_by": "search_volume"}]'

When to use DataForSEO vs SemRush:

• Use SemRush as the primary source for keyword difficulty, competitor analysis, and domain organic keywords
• Use DataForSEO for bulk search volume lookups (supports up to 700 keywords per request, more cost-effective for large batches)
• Use DataForSEO when you need Google Ads-aligned data (their data comes directly from Google Keyword Planner)
• Cross-reference both sources when search volume numbers differ significantly

SerpAPI (People Also Ask & Related Searches)

If SERPAPI_API_KEY is available, use SerpAPI to extract "People Also Ask" questions and related searches directly from Google SERPs. This data is not available from SemRush and is valuable for FAQ sections and content ideation.

Search Endpoint:

# Get SERP data including People Also Ask and related searches
curl -s "https://serpapi.com/search.json?q={keyword}&api_key=${SERPAPI_API_KEY}&num=10"

Parsing People Also Ask:

# Extract People Also Ask questions
curl -s "https://serpapi.com/search.json?q={keyword}&api_key=${SERPAPI_API_KEY}&num=10" | \
  jq -r '.related_questions[] | {
    question: .question,
    snippet: .snippet,
    link: .link,
    title: .title
  }'

Key response sections:

• related_questions - Array of "People Also Ask" questions with snippets and source URLs
• related_searches - Array of related search queries that Google suggests
• organic_results - Top 10 organic results (useful for SERP analysis)

Parsing Related Searches:

# Extract related searches for content ideation
curl -s "https://serpapi.com/search.json?q={keyword}&api_key=${SERPAPI_API_KEY}&num=10" | \
  jq -r '.related_searches[] | .query'

How to use SerpAPI data in keyword research:

1. FAQ content: Use "People Also Ask" questions directly as H2/H3 headings in blog posts or as FAQ schema entries. These are questions Google already associates with the keyword.
2. Content gap discovery: If a PAA question has a weak snippet answer (short, vague, or from a low-authority site), that is an opportunity to write a better answer and win the featured snippet.
3. Keyword expansion: Related searches are Google's own suggestions for related topics. Add these to your keyword list and check their volume via SemRush or DataForSEO.
4. Search intent validation: The organic results show what content types Google ranks for this keyword. If all top 10 are blog posts, write a blog post. If they are product pages, a blog post will not rank.
5. Cluster building: Group PAA questions and related searches by subtopic to identify natural content clusters.

Additional SerpAPI parameters:

• location=United+States - Geo-target the search
• gl=us - Country code for Google domain
• hl=en - Interface language
• device=desktop or device=mobile - Desktop vs mobile SERPs (mobile may show different PAA questions)

Note: SerpAPI charges per search. Use it strategically for your highest-priority keywords rather than for bulk research. Pair it with SemRush for volume data and DataForSEO for bulk lookups.