Relevant Pages API

Relevant Pages

主要特性

• 域名级页面清单返回一个域名中在所选搜索索引里具有可衡量自然或付费相关性的页面绝对 URL。
• 自然排名分布保留各排名区间的自然关键词数量，以及可用的新增、上升、下降和丢失排名数量。
• 付费搜索覆盖为每个页面提供可用的付费关键词数量、排名区间、估算流量和付费流量成本。
• 完整页面指标对象在 extra 中保留自然、付费和其它可变页面级指标，同时标准化页面 URL 以便稳定识别。

参数

如何使用

提交一个格式正确的域名，设置市场和有界来源窗口，再从已完成的异步任务读取每条相关页面记录。

1. 选择一个去掉 https:// 和 www. 的域名、location_code、language_code、1 到 1,000 的 results_limit，以及不小于 0 的 offset。
2. 将请求体 POST 到 /v1/seo/relevant-pages，并保存返回的 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/relevant-pages" \
  -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 建立域名清单，只包含具有可衡量索引搜索相关性的页面。
• 自然搜索覆盖比较： 比较自然关键词数量、排名区间和变动字段，了解可见性如何分布在各页面。
• 付费搜索页面复核： 利用付费关键词数量、排名范围、估算流量和成本，比较返回页面的付费搜索覆盖。
• 页面可见性快照： 按 page_address 和市场保存重复记录，比较不同采集时间的排名分布和估算流量。

使用建议

• 提交前从 target 去掉 https:// 和 www.，因为该接口接收域名而不是完整页面 URL。
• 使用返回的 url 识别页面；text 只是同一 URL 的回退值，不包含页面正文。
• 比较重复结果窗口时固定 target、location_code、language_code、results_limit 和 offset。
• 将 offset 视为来源记录偏移量而不是页码，并与 task 结果的 next_cursor 分开保存。
• 从 extra.metrics 读取自然与付费指标，并允许嵌套指标组或单个字段缺失。
• 将 etv 和 estimated_paid_traffic_cost 解释为模型估算，不要当作私有分析数据或实际收入。

相关 API