Ranked Keywords API

Ranked Keywords

主要特性

• 域名、子域名或页面范围按完整域名、子域名或单个完整页面 URL 所需的粒度解析一个格式正确的网站目标。
• 关键词与 URL 关系将每个返回关键词与其排名搜索结果元素中的匹配目标 URL 配对。
• 位置与关键词指标返回可用的同类元素排名、绝对排名和结果页码，以及搜索量、CPC、竞争、难度、月度历史和意图。
• 完整匹配元素在 extra 中保留 keyword_data 和 ranked_serp_element，供读取结果类型、估算流量和未提升的来源详情。

参数

如何使用

提交一个范围正确的网站目标、市场设置和受控结果窗口，异步任务完成后读取每条排名关键词。

1. 准备一个 target、location_code、language_code、1 到 1,000 的 results_limit，以及不小于 0 的 offset。
2. 向 /v1/seo/ranked-keywords 发送 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/ranked-keywords" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target":"microsoft.com","location_code":2840,"language_code":"en","results_limit":5}'

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

最佳使用场景

• 自然搜索可见度清单： 利用返回的关键词文本和匹配 URL，整理域名或子域名在所选搜索市场中的出现情况。
• 落地页排名映射： 结合每个关键词、目标 URL 和 rank 对象，确认每个返回位置关联的页面。
• 关键词机会审核： 比较位置与可用的搜索量、CPC、竞争、难度和意图字段，整理待审核队列。
• 可见度快照比较： 保存重复任务的匹配 target、collected_at、关键词、URL 和排名，比较分别采集的网站目标快照。

使用建议

• 域名 target 应移除 https:// 和 www.，子域名 target 应移除协议，以便按预期范围解释目标。
• 需要页面级结果时使用完整页面 URL；不带协议的页面路径可能被解释为整个域名。
• 按计划跳过的来源记录数增加 offset，并在获取连续窗口时保持 target、市场、语言和上限不变。
• 将 rank.page 作为搜索结果页码；来源窗口使用 offset，翻阅 SocQ 已存结果则另外使用 next_cursor。
• 先读取标准化位置和关键词指标，再到 extra.ranked_serp_element 检查未提升的模型 etv 和其它来源字段。
• 通过重复任务建立历史比较，并按关键词、匹配 URL、市场和语言去重，因为来源排序可能变化。

相关 API