Keyword Difficulty API

Keyword Difficulty

主要特性

• 批量关键词输入在一个任务中评估 1 到 1,000 个非空关键词，并为整批关键词应用相同的搜索市场和语言设置。
• 标准化难度指标为每个有可用数据的关键词返回 metrics.keyword_difficulty，分数通常采用便于直接比较的 0–100 范围。
• 完整来源上下文在 extra 中保留完整返回行，便于客户端检查附加来源字段，同时不将其当作稳定的标准化结构。

参数

如何使用

提交限定数量的关键词列表和代码形式的搜索市场设置，然后从完成的异步任务中读取可用的标准化分数。

1. 准备 1 到 1,000 个非空关键词，每项不超过 80 个字符。
2. 将 keywords、location_code 和 language_code POST 到 /v1/seo/keyword-difficulty，并保存返回的 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-difficulty" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keywords":["keyword research","seo analytics"],"location_code":2840,"language_code":"en"}'

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

最佳使用场景

• 关键词列表排序： 比较已准备词表中的 metrics.keyword_difficulty，为内容规划或研究分流加入竞争程度信号。
• 难度区间分组： 按内部定义的分数区间整理返回结果，建立较低难度和较高难度的关键词研究队列。
• 搜索市场比较： 保持关键词列表一致并控制 location_code 和 language_code，比较不同搜索环境下的估算难度。

使用建议

• 提交前先对关键词去重，避免重复词产生重复的按输入计费。
• 比较同一研究集合中的分数时，保持 location_code 和 language_code 不变。
• 不要提交 results_limit，因为本批次由 keywords 数组控制，而不是由返回结果上限控制。
• 按 keyword 匹配输入和结果，不要依赖数组位置，因为没有可用数据的词可能不会返回记录。
• 划分难度区间时，应区分数值 0 与缺少 keyword_difficulty 字段这两种情况。

相关 API