Keyword Suggestions
关键词建议是包含种子词或短语的长尾搜索词，可以在原词之前、之后或中间增加其它词语，其记录还可包含需求、成本、竞争、月度历史和意图信号。这些匹配词与指标可用于扩展 query、研究内容提纲、分析付费搜索，以及在受控条件下比较不同措辞。
主要特性
- 全文种子词扩展返回保留已提交种子词的搜索词，允许在短语之前、之后或中间增加词语，也允许词序变化。
- 关键词指标对象在每条记录的来源数据中保留可用的搜索量、CPC、付费竞争、月度历史和难度详情。
- 搜索意图信息展示每个匹配关键词可用的主要与次要意图信息，但不把分类解释为排名建议。
- 可控结果窗口接受 1 到 1,000 的结果上限和从 0 开始的行偏移量，用于获取更靠后的来源窗口。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
query | 必填 | 必填的非空种子关键词或短语；一个任务接受一个 query。 |
location_code | 可选 | 正整数搜索市场代码；Playground 默认使用 2840。 |
language_code | 可选 | 搜索语言代码；Playground 默认使用 en。 |
results_limit | 可选 | 1 到 1,000 的关键词建议请求上限；实际返回可以更少。 |
offset | 可选 | 从 0 开始的来源记录跳过数量，跳过后再获取指定结果窗口。 |
如何使用
提交一个种子 query、市场设置和受控结果窗口，异步任务完成后读取每条关键词建议。
- 准备一个非空 query、location_code、language_code、1 到 1,000 的 results_limit，以及不小于 0 的 offset。
- 向 /v1/seo/keyword-suggestions 发送 POST 请求并保存返回的 task_id。
- 轮询 /v1/tasks/{task_id}，直到任务成功或返回失败。
- 读取 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,"offset":0}'
# 轮询 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
需要其他类型的 SEO 公开数据时，可以使用以下 API。
- Keyword Difficulty API — 比较一批输入关键词的自然排名难度，为每个有可用数据的关键词返回标准化分数。
- Keyword Overview API — 为一批输入关键词补充可用的需求、付费竞争、难度、月度搜索和搜索意图信息。
- Keyword Search Volume API — 测量已知关键词可用的搜索量、CPC、付费竞争和月度搜索历史。
- Related Keywords API — 围绕一个种子 query 沿相关搜索路径查找关键词，并返回深度控制、可用关键词指标、意图信息和完整来源记录。