Ranked Keywords
排名关键词是通过匹配结果 URL 与域名、子域名或页面关联的搜索 query，包含同类元素排名、绝对排名和结果页码，以及可用的需求、难度、意图和流量信号。这些 query 与页面的关系可用于建立可见度清单、映射落地页、审核关键词机会，以及比较不同时点的网站目标快照。
主要特性
- 域名、子域名或页面范围按完整域名、子域名或单个完整页面 URL 所需的粒度解析一个格式正确的网站目标。
- 关键词与 URL 关系将每个返回关键词与其排名搜索结果元素中的匹配目标 URL 配对。
- 位置与关键词指标返回可用的同类元素排名、绝对排名和结果页码，以及搜索量、CPC、竞争、难度、月度历史和意图。
- 完整匹配元素在 extra 中保留 keyword_data 和 ranked_serp_element，供读取结果类型、估算流量和未提升的来源详情。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
target | 必填 | 必填的域名、子域名或页面目标。域名不带 https:// 与 www.，子域名不带协议，单页使用完整 URL。 |
location_code | 可选 | 正整数搜索市场代码；Playground 默认使用 2840。 |
location_name | 可选 | 可选的搜索市场名称，用于替代 location_code；填写后优先于 location_code。 |
language_code | 可选 | 长度为 2 到 10 个字符的搜索语言代码；Playground 默认使用 en。 |
language | 可选 | 可选的搜索语言名称，用于替代 language_code；填写后优先于 language_code。 |
results_limit | 可选 | 1 到 1,000 的排名关键词请求上限；实际返回可以更少。 |
offset | 可选 | 从 0 开始的来源记录跳过数量，跳过后再获取指定结果窗口。 |
如何使用
提交一个范围正确的网站目标、市场设置和受控结果窗口，异步任务完成后读取每条排名关键词。
- 准备一个 target、location_code、language_code、1 到 1,000 的 results_limit，以及不小于 0 的 offset。
- 向 /v1/seo/ranked-keywords 发送 POST 请求并保存返回的 task_id。
- 轮询 /v1/tasks/{task_id}，直到任务成功或返回失败。
- 读取 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
需要其他类型的 SEO 公开数据时，可以使用以下 API。
- Google Organic SERP API — 按一个 query 和市场获取实时 Google 结果页，返回标准化目标地址、排名、元素类型和完整结果详情。
- Keyword Difficulty API — 比较一批输入关键词的自然排名难度，为每个有可用数据的关键词返回标准化分数。
- Keyword Overview API — 为一批输入关键词补充可用的需求、付费竞争、难度、月度搜索和搜索意图信息。
- Keyword Search Volume API — 测量已知关键词可用的搜索量、CPC、付费竞争和月度搜索历史。
- Keywords for Site API — 根据一个网站生成相关关键词，并返回可用的需求指标、月度历史、市场上下文和完整来源记录。
- Keyword Suggestions API — 按一个种子 query 扩展包含原词的长尾词，并返回可用的需求指标、月度历史、意图信息和完整来源记录。
- Related Keywords API — 围绕一个种子 query 沿相关搜索路径查找关键词，并返回深度控制、可用关键词指标、意图信息和完整来源记录。
- Relevant Pages API — 为一个域名整理已被搜索索引收录的页面，并返回自然与付费排名分布、估算流量和成本信息。
- Search Intent API — 批量识别输入关键词的主要和次要搜索意图，并保留来源概率与完整记录。