Keyword Overview API

Keyword Overview

主要特性

• 已知关键词批量输入在同一个搜索市场和语言环境中评估 1 到 1,000 个已准备的关键词。
• 需求与付费搜索字段保留可用的搜索量、CPC、competition、competition_level、competition_index 和月度观察值，用于比较需求与付费市场。
• 自然难度与搜索意图将可用的关键词难度和搜索意图信息与需求字段关联到同一个搜索词，同时保持不同信号的独立含义。
• 完整概览行在 extra 中保留返回的 keyword_info、keyword_properties、搜索结果元数据和其他可用对象。

参数

如何使用

提交限定数量的已知关键词和代码形式的搜索市场设置，然后从异步结果记录中读取标准化字段和完整概览对象。

1. 准备 1 到 1,000 个非空的已知关键词，每项不超过 80 个字符。
2. 将 keywords、location_code 和 language_code POST 到 /v1/seo/keyword-overview，并保存返回的 task_id。
3. 轮询 /v1/tasks/{task_id}，直到任务成功或返回失败。
4. 读取 data.results.items；未提升的来源字段可从 extra.keyword_info 或 extra.keyword_properties 获取，has_more 为 true 时继续使用 next_cursor。

curl -X POST "https://api.socq.ai/v1/seo/keyword-overview" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keywords":["keyword research","seo tools"],"location_code":2840,"language_code":"en"}'

# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items，并在 has_more 为 true 时继续使用 next_cursor

最佳使用场景

• 关键词列表补充： 将返回的 keyword_info 和 keyword_properties 字段关联到已准备词表，形成统一研究记录。
• 需求与竞争比较： 比较搜索量、CPC、付费竞争和关键词难度，同时避免把付费与自然排名信号混为一谈。
• 意图与趋势分组： 结合搜索意图信息和月度搜索观察值，按可能的目的与需求变化整理已知关键词。

使用建议

• 提交前先对关键词去重，因为费用根据输入数量计算。
• 比较词表时保持 location_code 和 language_code 不变，以维持一致的搜索环境。
• 不要提交 results_limit，因为本批次由 keywords 数组控制，概览操作没有已记录的结果上限参数。
• 从 extra.keyword_info 和 extra.keyword_properties 读取完整概览，因为来源中的直接字段不一定全部提升到标准化顶层。
• 将缺失字段理解为没有可用数据，而不是数值 0；按 keyword 匹配返回记录，不要依赖数组位置。
• 将 CPC 和 competition 解释为付费搜索信号，将 keyword_difficulty 解释为自然排名竞争程度的估算。

相关 API