SERP 竞争对手

POST /v3/dataforseo_labs/google/serp_competitors/live

本接口使用 POST 方法，路径为：

/v3/dataforseo_labs/google/serp_competitors/live

根据指定、地区和语言，返回在搜索结果中排名的竞争域名，以及各域名的平均排名、排名中位数、预估流量、可见度等指标。

接口说明

请求方法：POST
请求地址：https://api.seermartech.cn/v3/dataforseo_labs/google/serp_competitors/live
请求格式：JSON，UTF-8 编码
请求体格式：JSON 数组 [{ ... }]
单次 Live API 请求最多 1 个任务平台限流以认证说明中的 30/60/120 次/分钟规则为准
同时发送的请求数最多为 30
支持设置返回数量、筛选条件和排序规则

每次请求按调用计费。参考价约 ¥0.0760 / 次（以示例任务对应的计费为参考），扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

请求体中的每个对象代表一个任务。

参数	类型	填	说明
`keywords`	array	是	用于查找竞争域名的数组。使用 UTF-8 编码，并会被转换为小写。最多可指定 200 个。
`location_name`	string	条件填	地区的完整名称。未指定 `location_code` 时填。在 `location_name` 与 `location_code` 中二选一。示例：`United Kingdom`。
`location_code`	integer	条件填	地区的唯一标识。未指定 `location_name` 时填。在 `location_name` 与 `location_code` 中二选一。示例：`2840`。
`language_name`	string	条件填	语言的完整名称。未指定 `language_code` 时填。在 `language_name` 与 `language_code` 中二选一。示例：`English`。
`language_code`	string	条件填	语言的唯一标识。未指定 `language_name` 时填。在 `language_name` 与 `language_code` 中二选一。示例：`en`。
`include_subdomains`	boolean	否	是否在搜索中子域名。设置为 `false` 时忽略子域名。默认值：`true`。
`item_types`	array	否	要纳统计的搜索结果类型。未指定时不限制结果类型。
`limit`	integer	否	最多返回的域名数量。默认值：`100`，最大值：`1000`。
`offset`	integer	否	返回结果的偏移量。默认值：`0`。例如设置为 `10` 时，跳过结果数组中的前 10 个域名。
`filters`	array	否	结果筛选条件。最多可同时设置 8 个过滤条件，并使用 `and` 或 `or` 连接。
`order_by`	array	否	结果排序规则。最多设置 3 条排序规则。
`tag`	string	否	用户自定义任务标识，最多 255 个字符。该值会原样返回在响应的 `data` 对象中。

`keywords` 使用限制

最多提交 200 个。
使用 UTF-8 编码。
会转换为小写格式。
数组中的每个应为字符串。

`location_name` 与 `location_code`

可以调用以下接口获取可用的地区及标识：

https://api.seermartech.cn/v3/dataforseo_labs/locations_and_languages

`language_name` 与 `language_code`

同样可以通过以下接口获取可用的语言及标识：

https://api.seermartech.cn/v3/dataforseo_labs/locations_and_languages

过滤条件

filters 支持以下运算符：

运算符	说明
`regex`	匹正则表达式
`not_regex`	不匹正则表达式
`<`	小于
`<=`	小于或等于
`>`	大于
`>=`	大于或等于
`=`	等于
`<>`	不等于
`in`	位于指定集合中
`not_in`	不位于指定集合中
`match`	匹
`not_match`	不匹
`ilike`	不区分大小写的模糊匹
`not_ilike`	不区分大小写且不匹
`like`	区分大小写的模糊匹
`not_like`	区分大小写且不匹

like、not_like、ilike 和 not_ilike 支持使用 % 匹零个或多个字符。

过滤条件示例：

json

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

更多过滤规则请参考：

/v3/dataforseo_labs/filters

排序规则

order_by 使用以下格式：

json

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

asc：升序
desc：降序
使用逗号分隔字段名和排序方向。
多条排序规则之间使用逗号分隔。
单次请求最多设置 3 条排序规则。

请求示例

cURL

bash

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

Python

python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/google/serp_competitors/live"

headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
}

post_data = [
    {
        "keywords": [
            "phone",
            "watch",
        ],
        "location_name": "United States",
        "language_name": "English",
        "filters": [
            ["relevant_serp_items", ">", 0],
            "or",
            ["median_position", "in", [1, 10]],
        ],
        "limit": 5,
    }
]

response = requests.post(url, headers=headers, json=post_data)
result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败，状态码：%s，信息：%s"
        % (result.get("status_code"), result.get("status_message"))
    )

TypeScript

typescript

import axios from "axios";

const postData = [
  {
    keywords: ["phone", "watch"],
    location_name: "United States",
    language_name: "English",
    filters: [
      ["relevant_serp_items", ">", 0],
      "or",
      ["median_position", "in", [1, 10]],
    ],
    limit: 5,
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/dataforseo_labs/google/serp_competitors/live",
    postData,
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    // 处理接口返回结果
    console.log(response.data);
  })
  .catch((error) => {
    // 处理请求错误
    console.error(error.response?.data || error.message);
  });

响应结构

接口返回 JSON 数据，顶层 tasks 数组。

顶层字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	请求整体状态码。
`status_message`	string	请求整体状态信息。
`time`	string	请求执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务总数。
`tasks_error`	integer	`tasks` 数组中返回错误的任务数量。
`tasks`	array	任务结果数组。

`tasks` 字段

字段	类型	说明
`id`	string	任务唯一标识，UUID 格式。
`status_code`	integer	任务状态码，通常位于 `10000` 至 `60000` 范围。
`status_message`	string	任务状态信息。
`time`	string	任务执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量。
`path`	array	请求路径。
`data`	object	创建任务时提交的参数。
`result`	array	任务结果数组。

`result` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型，例如 `google`。
`seed_keywords`	array	请求中指定的。返回时会对编码后的字符进行解码，`+` 会解码为空格。
`location_code`	integer	请求中的地区代码。无数据时返回 `null`。
`language_code`	string	请求中的语言代码。无数据时返回 `null`。
`total_count`	integer	数据库中与请求条件的结果总数。
`items_count`	integer	`items` 数组中返回的结果数量。
`items`	array	检测到的 SERP 竞争域名及数据。

`items` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型。
`domain`	string	检测到的 SERP 竞争域名。
`avg_position`	integer	域名在指定下的平均排名，即 `keywords_positions` 中排名值的算术平均数。
`median_position`	integer	域名在指定下的排名中位数，即 `keywords_positions` 中排名值的中位数。
`rating`	integer	域名排名与理论最高排名之间的相对指标，用于表示域名在指定 SERP 中的相对可见程度。计算方式为 `sum(100 - keywords_positions)`。
`etv`	float	预估流量。表示指定预计每月为网站带来的流量，基于搜索量与在相应 SERP 排名位置的点击率计算。
`keywords_count`	integer	域名在 SERP 中存在排名的指定数量。
`visibility`	float	SERP 可见度。用于衡量网站在指定下的搜索结果可见程度。
`relevant_serp_items`	integer	与该域名的 SERP素数量。
`keywords_positions`	object	排名对象，记录该域名针对各指定的 SERP 排名。

`visibility` 计算规则

排名第 1 至第 10 位的可见度指数依次为 1 至 0.1。
排名第 11 至第 20 位的，可见度指数固定为 0.05。
排名第 20 至第 100 位的，可见度指数为 0。

响应示例

json

{
  "version": "0.1.20220216",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0779 sec.",
  "cost": 0.0756,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0600 sec.",
      "cost": 0.0756,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "google",
        "serp_competitors",
        "live"
      ],
      "data": {
        "api": "dataforseo_labs",
        "function": "serp_competitors",
        "se_type": "google",
        "keywords": [
          "phone"
        ],
        "language_name": "English",
        "location_code": 2840,
        "item_types": [
          "organic"
        ],
        "limit": 5
      },
      "result": [
        {
          "se_type": "google",
          "seed_keywords": [
            "phone"
          ],
          "location_code": 2840,
          "language_code": "en",
          "total_count": 86,
          "items_count": 5,
          "items": [
            {
              "se_type": "google",
              "domain": "www.example.com",
              "avg_position": 1,
              "median_position": 1,
              "rating": 99,
              "etv": 78500.2,
              "keywords_count": 1,
              "visibility": 1,
              "relevant_serp_items": 1,
              "keywords_positions": {
                "phone": [
                  1
                ]
              }
            },
            {
              "se_type": "google",
              "domain": "www.phone.com",
              "avg_position": 2,
              "median_position": 2,
              "rating": 98,
              "etv": 59616,
              "keywords_count": 1,
              "visibility": 0.9,
              "relevant_serp_items": 1,
              "keywords_positions": {
                "phone": [
                  2
                ]
              }
            },
            {
              "se_type": "google",
              "domain": "www.t-mobile.com",
              "avg_position": 3,
              "median_position": 3,
              "rating": 97,
              "etv": 35806.4,
              "keywords_count": 1,
              "visibility": 0.8,
              "relevant_serp_items": 1,
              "keywords_positions": {
                "phone": [
                  3
                ]
              }
            },
            {
              "se_type": "google",
              "domain": "www.cnet.com",
              "avg_position": 4,
              "median_position": 4,
              "rating": 96,
              "etv": 24251.2,
              "keywords_count": 1,
              "visibility": 0.7,
              "relevant_serp_items": 1,
              "keywords_positions": {
                "phone": [
                  4
                ]
              }
            },
            {
              "se_type": "google",
              "domain": "www.pcmag.com",
              "avg_position": 5,
              "median_position": 5,
              "rating": 95,
              "etv": 17259.2,
              "keywords_count": 1,
              "visibility": 0.6,
              "relevant_serp_items": 1,
              "keywords_positions": {
                "phone": [
                  5
                ]
              }
            }
          ]
        }
      ]
    }
  ]
}

状态码与异常处理

请根据顶层 status_code 和任务级 status_code 判断请求是否成功：

20000：请求或任务处理成功。
状态码：表示请求、参数或任务处理异常。

生产环境应同时检查以下字段：

tasks_error 是否大于 0
每个任务的 status_code
status_message
result 是否存在且数据

完整错误码请参考错误码文档。

实用场景

识别目标的排名域名：批量发现与自身业务争夺搜索流量的竞争网站，为竞品监测和市场研究提供数据依据。
比较竞争域名的搜索可见度：结合 rating、visibility 和 avg_position，评估不同竞争对手在目标集合中的整体表现。
估算竞争对手的自然搜索流量：使用 etv 衡量可能带来的月度流量，市场规模评估和 SEO 资源分。
筛选重点竞争对手：通过 filters 按排名、 SERP素数量或可见度筛选域名，缩小人工分析范围。
构建竞争矩阵：结合 keywords_positions 记录各域名在每个下的排名，用于制定差距分析和攻防策略。

SERP 竞争对手 ​

接口说明 ​

请求参数 ​

keywords 使用限制 ​

location_name 与 location_code ​

language_name 与 language_code ​

过滤条件 ​

排序规则 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

tasks 字段 ​

result 字段 ​

items 字段 ​

visibility 计算规则 ​

响应示例 ​

状态码与异常处理 ​

实用场景 ​

SERP 竞争对手

接口说明

请求参数

`keywords` 使用限制

`location_name` 与 `location_code`

`language_name` 与 `language_code`

过滤条件

排序规则

请求示例

cURL

Python

TypeScript

响应结构

顶层字段

`tasks` 字段

`result` 字段

`items` 字段

`visibility` 计算规则

响应示例

状态码与异常处理

实用场景