用 SemRush API 做关键词研究并产出选题与内容规划

当需要为某个主题或细分领域找关键词、评估搜索量与难度、划分搜索意图、搭建主题集群并排出内容优先级时使用。

适用场景

解决思路

1. 确认已配置 SEMRUSH_API_KEY（环境变量或 ~/.claude/.env.global），缺失则提示用户 export SEMRUSH_API_KEY=your_key_here 或写入 ~/.claude/.env.global。
2. 所有 API 调用通过 Bash 工具用 curl 发起，基础 URL 为 https://api.semrush.com/。
3. 用 phrase_all 端点查关键词概览：https://api.semrush.com/?type=phrase_all&key={KEY}&phrase={keyword}&database={db}&export_columns=Ph,Nq,Cp,Co,Nr,Td（Ph=关键词, Nq=搜索量, Cp=CPC, Co=竞争度, Nr=结果数, Td=趋势）。
4. 用 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。
5. 用 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。
6. 用 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（Po=排名, Tr=流量, Tc=流量成本）。
7. 用 phrase_kdi 端点查关键词难度：https://api.semrush.com/?type=phrase_kdi&key={KEY}&phrase={keyword}&database={db}&export_columns=Ph,Kd（Kd=难度 0-100）。
8. 数据库代码：us（默认）、uk、ca、au、de、fr、es、it、br、in、jp；未指定目标市场时先询问用户，默认 us。
9. 第一步理解需求：询问或推断细分主题、目标受众、商业模式（SaaS/电商/广告/联盟）、现有域名（有则拉取现有排名）、目标市场国家/语言、已知竞争对手。
10. 第二步种子词发现：基于需求生成 10-20 个种子词，用三种方法——A 从主题头脑风暴（核心产品/服务词、问题词如 how to fix/why is、受众词如职位与人群、同义词与替代词）；B 用 domain_organic 拉取 2-3 个竞争对手域名的关键词；C 对每个种子词用 phrase_related 和 phrase_questions 扩展。
11. 第三步逐个分析候选词，通过 API 收集：搜索量 Nq（phrase_all）、关键词难度 Kd（phrase_kdi）、CPC Cp（phrase_all）、竞争度 Co（phrase_all）、趋势 Td（phrase_all）、SERP 结果数 Nr（phrase_all）。
12. 第四步按搜索意图分类：Informational（how/what/why/guide/tutorial/tips，对应博客、指南、视频）、Navigational（品牌名、具体产品名、login，对应首页、产品页）、Commercial（best/review/comparison/vs/top/alternatives，对应对比、评测、清单）、Transactional（buy/price/discount/coupon/free trial/sign up，对应落地页、产品页）。
13. 意图判定规则：how to / what is / why = Informational；{brand}+{feature} = Navigational；best / top / vs / alternative / review = Commercial Investigation；buy / price / discount / free / download / sign up = Transactional；模糊时看 SERP，多数是博客=信息型，多数是产品页=交易型。
14. 第五步搭建主题集群（pillar-cluster 结构）：Pillar 页为宽泛主题词（量>5,000，KD 40-80）；Cluster head 为具体子主题（量 1,000-5,000，KD 20-50）；Supporting 为长尾变体（量 100-1,000，KD<30）；每个集群 3-8 个支持词；每个支持页都回链到 pillar 页。
15. 第六步用 KOB 分数排优先级：KOB Score = (Search Volume * CTR Estimate * Business Value) / Keyword Difficulty；CTR Estimate 位置1=0.30、位置2=0.15、位置3=0.10（默认用 0.15）；Business Value：3=直接变现词、2=考虑型词、1=认知型词；Keyword Difficulty 取 max(KD, 1) 避免除零。
16. KOB 优先级分层：>50 高优先（先做）；20-50 中优先（第 2-3 个月做）；5-20 低优先（稍后做）；<5 除非有战略意义否则降级。
17. 第七步找内容缺口：用 domain_organic 拉取每个竞争对手的前 100 个关键词，找出竞品有排名而用户没有的词，筛选 KOB>20 的，即为内容缺口机会。
18. 按固定格式输出报告：标题（主题/细分+日期+目标市场+关键词总数+总月搜索量）、Top 20 关键词表（关键词/搜索量/KD/CPC/意图/KOB）、主题集群（Pillar 及各 Cluster 的 head 词与支持词）、内容计划表（优先级/关键词/意图/内容类型/预估月流量=vol*0.15）、疑问关键词 FAQ 机会表、竞品内容缺口表、推荐下一步行动项。
19. 优化建议：批量调用 API 节省额度；始终检查趋势，搜索量下滑的词可能不值得做；CPC 高（$5+）通常代表强商业意图；低 KD 不一定好做，若前列全是 DR 80+ 站点，KD 20 对新站仍很难；本地业务在种子词后加城市/州；注意季节性词，在峰值前 2-3 个月规划内容；API 报错或无数据时明确告知用户具体问题，不要猜测。
20. 若配置了 DATAFORSEO_LOGIN 和 DATAFORSEO_PASSWORD，可用 DataForSEO 作为备选或交叉验证：搜索量端点 POST https://api.dataforseo.com/v3/keywords_data/google_ads/search_volume/live，用 Basic 认证（base64 编码 login:password），body 为 [{"keywords": [...], "location_code": 2840, "language_code": "en"}]，用 jq 提取 keyword/search_volume/competition/competition_index/cpc/monthly_searches。
21. DataForSEO 常用 location_code：2840=美国、2826=英国、2124=加拿大、2036=澳大利亚、2250=法国、2158=德国。
22. DataForSEO 关键词建议端点：POST https://api.dataforseo.com/v3/keywords_data/google_ads/keywords_for_keywords/live，body 含 keywords、location_code、language_code、sort_by=search_volume。
23. SemRush 与 DataForSEO 分工：SemRush 作为主源用于关键词难度、竞品分析和域名自然关键词；DataForSEO 用于批量搜索量查询（单次最多 700 词，大批量更省钱）、需要 Google Ads 口径数据时；两者数值差异大时交叉比对。
24. 若配置了 SERPAPI_API_KEY，用 SerpAPI 抓取 Google SERP 的 People Also Ask 和 related searches：GET https://serpapi.com/search.json?q={keyword}&api_key=${SERPAPI_API_KEY}&num=10，用 jq 提取 .related_questions[]（question/snippet/link/title）和 .related_searches[].query。
25. SerpAPI 数据用法：把 PAA 问题直接作为博客 H2/H3 或 FAQ schema；若某 PAA 答案的 snippet 很弱（短、含糊、来自低权重站）就是抢精选摘要的机会；把 related searches 加入关键词列表并用 SemRush/DataForSEO 查量；用 organic_results 验证搜索意图（前 10 全是博客就写博客，全是产品页则博客排不上）；按子主题对 PAA 和 related searches 分组以构建集群。
26. SerpAPI 额外参数：location=United+States、gl=us、hl=en、device=desktop 或 device=mobile（移动端 PAA 可能不同）；SerpAPI 按次计费，只对最高优先级关键词使用，不要批量跑。
27. 若配置了 SERPINGAPI_API_KEY，可用 Serping API（https://serpingapi.com，有免费额度）获取同样的 PAA 与 related searches：POST https://api.serpingapi.com/v1/search，header 含 X-API-Key: ${SERPINGAPI_API_KEY} 和 Content-Type: application/json，body 为 {"q": "{keyword}", "gl": "us", "hl": "en", "num": 10}。
28. Serping API 响应字段：peopleAlsoAsk（question/snippet/link/title）、relatedSearches（{query} 对象数组）、organic（position/title/link/snippet）、answerBox/knowledgeGraph（存在时）；用法与 SerpAPI 完全相同（FAQ 标题、缺口发现、关键词扩展、意图验证、集群构建）。
29. Serping API 额外参数：location（如 "Seattle, Washington, United States"）、page（从 1 开始）、tbs 时间过滤（qdr:d/qdr:w/qdr:m/qdr:y）；每个响应带 X-Quota-Remaining 可告知用户剩余额度；错误格式为 {"error": {"code", "message"}}，429 quota_exceeded 表示当月额度用尽，应报告而非重试。

适用边界 · 注意事项

• 没有 SemRush API key（且无 DataForSEO 等替代数据源）时无法执行核心流程。
• SerpAPI 按次计费，不适合对大量关键词做批量 PAA 抓取。
• Serping API 返回 429 quota_exceeded 表示当月额度已用尽，不应重试。