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: 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) Columns: Ph=Keyword, Nq=Search Volume, Cp=CPC, Co=Competition, Nr=Number of Results, Td=Trend 2. Related Keywords (phrase related) 3. Keyword Questions (phrase questions) 4. Domain Organic Keywords (domain organic) Additional columns: Po=Position, Tr=Traffic, Tc=Traffic Cost 5. Keyword Difficulty (phrase kdi) 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: 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: 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: 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: Parsing the response: 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: 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: Parsing People Also Ask: 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: 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.

keyword-research