SERP 竞争域名（容旧版）

接口说明

注意：本接口文档对应的是旧版请求/响应结构（Legacy）。平台 API 已在 2022-03-19 更新了本平台 Labs 的结构，但该旧版接口仍持续容。如需使用新版结构，可参考对应新版文档。

该接口用于根据你提供的一组，找出在这些搜索结果中有排名的域名，并返回这些域名的：

SERP 排名
综合评分（rating）
预估流量（etv）
可见度（visibility）
覆盖数量等指标

请求方式：

POST https://api.seermartech.cn/v3/dataforseo_labs/serp_competitors/live

计费说明

该接口按请求计费。

原文未提供固定单价，因此无法直接换算为人民币参考价。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求要求

请求体使用 JSON（UTF-8 编码）
POST 请求体格式为 JSON 数组：[{ ... }]
任务参数放在数组中的对象
接口支持结果数量控制、过滤和排序
调用频率上限：每分钟最多 2000 次 API 调用

请求参数

字段名	类型	说明
`keywords`	array	填。数组，结果将基于该数组中的生成。要求：UTF-8 编码；会被转为小写；每个长度至少 3 个字符；最多可传 200 个。
`location_name`	string	若未传 `location_code`，则填。地区完整名称。在 `location_name` 和 `location_code` 中二选一。可通过 `/v3/dataforseo_labs/locations_and_languages` 获取可用地区。示例：`United Kingdom`
`location_code`	integer	若未传 `location_name`，则填。地区唯一标识。在 `location_name` 和 `location_code` 中二选一。可通过 `/v3/dataforseo_labs/locations_and_languages` 获取可用地区编码。示例：`2840`
`language_name`	string	若未传 `language_code`，则填。语言完整名称。在 `language_name` 和 `language_code` 中二选一。可通过 `/v3/dataforseo_labs/locations_and_languages` 获取可用语言。示例：`English`
`language_code`	string	若未传 `language_name`，则填。语言唯一标识。在 `language_name` 和 `language_code` 中二选一。可通过 `/v3/dataforseo_labs/locations_and_languages` 获取可用语言编码。示例：`en`
`include_subdomains`	boolean	可选。是否在搜索中子域名。若设为 `false`，则忽略子域名。默认值：`true`
`item_types`	array	可选。指定响应中的搜索结果类型。
`limit`	integer	可选。返回的最大域名数量。默认值：`100`；最大值：`1000`
`offset`	integer	可选。结果偏移量。默认值：`0`。例如传 `10` 表示跳过前 10 个域名，从后续结果开始返回。
`filters`	array	可选。结果过滤条件数组。最多可设置 8 个过滤条件。多个条件之间需使用逻辑运算符 `and` 或 `or` 连接。支持操作符：`<`, `<=`, `>`, `>=`, `=`, `<>`, `in`, `not_in`, `like`, `not_like`。 `like` 和 `not_like` 支持 `%` 通任意长度字符串。
`order_by`	array	可选。结果排序规则。可使用与 `filters` 相同的字段。排序方式支持：`asc`（升序）、`desc`（降序）。单次请求最多可设置 3 条排序规则。多条规则之间用逗号分隔。
`tag`	string	可选。自定义任务标识，最长 255 个字符。可用于在响应中识别任务，对应值会出现在响应的 `data` 对象中。

过滤与排序

`filters` 用法说明

filters 是一个数组，用于筛选返回的竞争域名。常见形式如下：

json

[
 ["relevant_serp_items", ">", 0],
 "or",
 ["median_position", "in", [1, 10]]
]

说明：

["relevant_serp_items", ">", 0]：保留 SERP素数大于 0 的域名
"or"：逻辑或
["median_position", "in", [1, 10]]：中位排名位于指定集合中的域名

`order_by` 用法说明

可按任意支持的结果字段排序，例如：

json

["visibility,desc", "etv,desc"]

表示：

按 visibility 降序
若相同，再按 etv 降序

响应结构

接口返回 JSON 编码数据，根节点 tasks 数组。

顶层字段

字段名	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	通用状态码。完整列表见 `/v3/appendix/errors`
`status_message`	string	通用状态信息
`time`	string	执行耗时，单位秒
`cost`	float	本次请求总费用，单位 USD
`tasks_count`	integer	`tasks` 数组中的任务数量
`tasks_error`	integer	返回错误的任务数量
`tasks`	array	任务数组

`tasks` 数组字段

字段名	类型	说明
`id`	string	任务唯一标识，UUID 格式
`status_code`	integer	任务状态码，范围通常为 `10000-60000`
`status_message`	string	任务状态信息
`time`	string	任务执行耗时，单位秒
`cost`	float	该任务费用，单位 USD
`result_count`	integer	`result` 数组中的数量
`path`	array	URL 路径
`data`	object	与请求中提交的参数一致
`result`	array	结果数组

`result` 数组字段

字段名	类型	说明
`seed_keywords`	string	。返回时会对 `%##` 编码进行解码，`+` 会被解码为空格
`location_code`	integer	请求中的地区编码；若无数据则为 `null`
`language_code`	string	请求中的语言编码；若无数据则为 `null`
`total_count`	integer	数据库中与请求的结果总量
`items_count`	integer	`items` 数组中返回的结果数量
`items`	array	检测到的 SERP 竞争域名及指标

`items` 数组字段

字段名	类型	说明
`domain`	string	检测到的竞争域名
`avg_position`	integer / float	指定下该域名的平均排名，即 `keywords_positions` 中位置值的算术平均数
`median_position`	integer	指定下该域名的中位排名
`rating`	integer	域名在指定上的相对评分，表示“理论最佳排名”与“排名”之间的差值，计算方式为 `sum(100 - keywords_positions)`
`etv`	float	预估流量（Estimated Traffic Volume）。表示这些每月可能为该网站带来的预估流量，计算基于搜索量与对应排名 CTR 的乘积求和
`keywords_count`	integer	该域名在指定集合中有排名的数量
`visibility`	float	SERP 可见度。1-10 位分别按 1 到 0.1 计；11-20 位固定为 0.05；20-100 位记为 0
`relevant_serp_items`	integer	与该域名的 SERP素数量
`keywords_positions`	object	该域名在各下对应的排名位置

指标说明

`rating`

表示域名针对指定集合的相对可见性强弱，计算为：

sum(100 - keywords_positions)

排名越靠前，rating 通常越高。

`etv`

表示指定为该网站带来的预估月流量。计算基于：

搜索量
当前 SERP 排名位置对应的 CTR

`visibility`

表示域名在 SERP 中的可见度：

排名 1-10：分别赋值 1 到 0.1
排名 11-20：固定为 0.05
排名 21-100：记为 0

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/dataforseo_labs/serp_competitors/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "keywords": ["phone", "watch"],
 "language_name": "English",
 "location_code": 2840,
 "include_subdomains": false,
 "limit": 3,
 "filters": [
 ["relevant_serp_items", ">", 0],
 "or",
 ["median_position", "in", [1, 10]]
 ]
 }
]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/serp_competitors/live"
payload = [
 {
 "keywords": ["phone", "watch"],
 "location_name": "United States",
 "language_name": "English",
 "filters": [
 ["relevant_serp_items", ">", 0],
 "or",
 ["median_position", "in", [1, 10]]
 ]
 }
]
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json)

TypeScript

typescript

import axios from "axios";

const postArray = [
 {
 keywords: ["phone", "watch"],
 language_name: "English",
 location_code: 2840,
 filters: [
 ["relevant_serp_items", ">", 0],
 "or",
 ["median_position", "in", [1, 10]]
 ]
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/dataforseo_labs/serp_competitors/live",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: postArray
})
 .then((response) => {
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应示例

json

{
 "version": "0.1.20200317",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.2667 sec.",
 "cost": 0.0103,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "dataforseo_labs",
 "function": "serp_competitors",
 "keywords": ["phone", "watch"],
 "language_name": "English",
 "location_code": 2840,
 "include_subdomains": false,
 "limit": 3
 },
 "result": [
 {
 "location_code": 2840,
 "language_code": "en",
 "total_count": 98,
 "items_count": 3,
 "items": [
 {
 "domain": "example.com",
 "avg_position": 12.5,
 "median_position": 11,
 "rating": 176,
 "etv": 0.12,
 "keywords_count": 2,
 "visibility": 0.35,
 "relevant_serp_items": 4,
 "keywords_positions": {
 "phone": [8, 15],
 "watch": [10, 17]
 }
 },
 {
 "domain": "google.com",
 "avg_position": 20.5,
 "median_position": 20,
 "rating": 159,
 "etv": 0.094,
 "keywords_count": 1,
 "visibility": 0.05,
 "relevant_serp_items": 2,
 "keywords_positions": {
 "reuse iphone": [20, 21]
 }
 },
 {
 "domain": "ifixit.com",
 "avg_position": 31.5,
 "median_position": 29,
 "rating": 137,
 "etv": 0.084,
 "keywords_count": 1,
 "visibility": null,
 "relevant_serp_items": 2,
 "keywords_positions": {
 "reuse iphone": [29, 34]
 }
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理

建议对以下层级分别进行状态判断：

顶层 status_code
tasks[].status_code
业务结果是否为空，如 items_count = 0

完整错误码与状态说明可参考：

/v3/appendix/errors

常见处理建议：

20000：请求成功
非成功状态码：记录 status_message 与请求参数，便于排查
若 tasks_error > 0：说明部分任务失败，应逐个检查 tasks 节点
若 result 为空：通常表示当前集合下没有可返回的竞争域名数据

使用建议

当较多时，优使用 limit 和 offset 分页获取结果
结合 filters 过滤低域名，可减少无效数据
若分析主域竞争格局，建议将 include_subdomains 设为 false
若要识别所有品牌站点、社区站点、子站参与竞争的，可保留默认 true

实用场景

识别自然搜索竞争对手：一组核心，快速找出真实参与排名的域名，帮助明确 SEO 竞争盘面。
评估竞品强度：结合 rating、visibility、avg_position 等指标，对不同竞争网站的 SERP 优势进行量化比较。
筛选高威胁竞争域名：通过 filters 过滤出排名靠前、覆盖多的域名，制定重点盯防名单。
挖掘流量分流网站：使用 etv 查看哪些站点从目标中获得更多预估流量，为竞品研究和策略提供依据。
区分主域与子域竞争格局：通过 include_subdomains 控制是否纳子域名，判断流量是否集中在主站还是分散在博客、帮助中心、商城等子站。

SERP 竞争域名（容旧版） ​

接口说明 ​

计费说明 ​

请求要求 ​

请求参数 ​

过滤与排序 ​

filters 用法说明 ​

order_by 用法说明 ​

响应结构 ​

顶层字段 ​

tasks 数组字段 ​

result 数组字段 ​

items 数组字段 ​

指标说明 ​

rating ​

etv ​

visibility ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

状态码与错误处理 ​

使用建议 ​

实用场景 ​

SERP 竞争域名（容旧版）

接口说明

计费说明

请求要求

请求参数

过滤与排序

`filters` 用法说明

`order_by` 用法说明

响应结构

顶层字段

`tasks` 数组字段

`result` 数组字段

`items` 数组字段

指标说明

`rating`

`etv`

`visibility`

请求示例

cURL

Python

TypeScript

响应示例

状态码与错误处理

使用建议

实用场景