Google Organic SERP API

Google Organic SERP

主要特性

• 单关键词市场快照按明确的市场、语言和桌面端或移动端设置查询一个关键词，得到可比较的时间点结果页。
• 排名与目标地址字段以标准字段返回可用的目标 URL、展示标题、同类元素排名、绝对排名和搜索结果页码。
• 多种 SERP 元素保留自然链接和返回的其它结果类型，并通过 extra.type 标明每条记录对应的元素种类。
• 完整元素上下文在 extra 中保留完整的元素专属对象，以便读取可用的域名、摘要、面包屑、图片和富结果属性。

参数

如何使用

提交一个关键词、代码形式的市场设置和受控深度，异步任务完成后读取每条标准化 SERP 元素。

1. 准备一个非空 query、location_code、language_code、device，以及 1 到 200 的 results_limit。
2. 向 /v1/seo/google-organic-serp 发送 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/google-organic-serp" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"keyword research","location_code":2840,"language_code":"en","device":"desktop","results_limit":10}'

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

最佳使用场景

• 当前排名快照： 结合目标 URL、rank.group、rank.absolute、rank.page 和 collected_at，记录指定关键词下返回页面的位置。
• 设备与市场对比： 用受控的 device、location_code 和 language_code 重复提交相同 query，比较不同环境中的目标地址和排名。
• SERP 布局分析： 检查 extra.type 和元素专属字段，区分排名链接、相关问题、摘要、本地结果、视频及其它返回的页面特征。

使用建议

• 比较桌面端和移动端时保持 query、location_code 与 language_code 不变，只让 device 成为计划中的变量。
• 即使路由校验接受更大数值，也应将 results_limit 控制在 200 以内，因为实时高级结果的深度上限为 200。
• 读取元素专属字段前先按 extra.type 分支，并允许不提供目标地址的元素缺少 url 或部分 rank 值。
• rank.page 表示搜索结果页码；翻阅 SocQ 已保存的结果记录应另外使用 next_cursor。
• 将 extra 作为灵活对象处理，因为可用键会随 SERP 元素类型变化，也可能继续演进。

相关 API