Keyword Suggestions API

Keyword Suggestions

主要特性

• 全文种子词扩展返回保留已提交种子词的搜索词，允许在短语之前、之后或中间增加词语，也允许词序变化。
• 关键词指标对象在每条记录的来源数据中保留可用的搜索量、CPC、付费竞争、月度历史和难度详情。
• 搜索意图信息展示每个匹配关键词可用的主要与次要意图信息，但不把分类解释为排名建议。
• 可控结果窗口接受 1 到 1,000 的结果上限和从 0 开始的行偏移量，用于获取更靠后的来源窗口。

参数

如何使用

提交一个种子 query、市场设置和受控结果窗口，异步任务完成后读取每条关键词建议。

1. 准备一个非空 query、location_code、language_code、1 到 1,000 的 results_limit，以及不小于 0 的 offset。
2. 向 /v1/seo/keyword-suggestions 发送 POST 请求并保存返回的 task_id。
3. 轮询 /v1/tasks/{task_id}，直到任务成功或返回失败。
4. 读取 data.results.items；has_more 为 true 时继续使用返回的 next_cursor。

curl -X POST "https://api.socq.ai/v1/seo/keyword-suggestions" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"keyword research","location_code":2840,"language_code":"en","results_limit":100}'

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

最佳使用场景

• 长尾 query 扩展： 结合一个种子短语和返回的关键词文本，采集保留原词的更长 query 变体。
• 内容提纲候选词研究： 结合匹配词与可用的搜索量、月度历史、难度和意图字段，整理可供审核的关键词集合。
• 付费搜索关键词比较： 比较不同措辞的可用 CPC 与付费竞争指标，再将候选词交给后续规划流程。

使用建议

• 需要紧密匹配的长尾变体时使用具体种子短语；如果返回词不必包含种子词，应选择语义相关关键词接口。
• 将 offset 作为记录数量而不是页码，并按计划跳过的来源窗口大小增加该值。
• 同时记录 query、location_code、language_code、results_limit 和 offset，因为后续匹配请求之间的来源排序可能变化。
• 先读取标准化的 keyword 和 search_intent，再到 extra.keyword_info 与 extra.keyword_properties 检查未提升的直接指标对象。
• 重复获取窗口时按关键词、市场和语言去重，并允许所有可选指标或嵌套对象缺失。

相关 API