Google 子域名实时分析

POST /v3/dataforseo_labs/google/subdomains/live

接口说明

POST https://api.seermartech.cn/v3/dataforseo_labs/google/subdomains/live

本接口用于查询指定域名下的子域名，并返回在 Google 自然搜索、付费搜索及搜索结果类型中的排名分布。同时，接口会根据搜索量、点击率和展示数据估算各子域名的流量规模。

数据按周更新，最新更新时间可通过状态接口查询。

状态接口：/v3/dataforseo_labs/status
地区与语言列表：/v3/dataforseo_labs/locations_and_languages
每个 Live API 请求只能 1 个任务平台限流以认证说明中的 30/60/120 次/分钟规则为准
同时执行的请求数最多为 30 个
请求体使用 UTF-8 编码的 JSON
支持设置返回数量、筛选条件和排序规则

计费说明

每次请求均会产生费用。启用 include_clickstream_data: true 时，请求费用按标准费用的 2 倍计算。

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

认证方式

请求时使用 Bearer Token：

http

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

请求参数

请求体是 JSON 数组，且每个 Live API 请求只能一个任务。

参数	类型	填	说明
`target`	string	是	目标域名。不应 `https://` 或 `www.`，例如 `example.com`。
`location_name`	string	否	地区名，例如 `United Kingdom`。指定此参数后无需指定 `location_code`。省略时返回所有可用地区的数据。
`location_code`	integer	否	地区代码，例如 `2840`。指定此参数后无需指定 `location_name`。省略时返回所有可用地区的数据。
`language_name`	string	否	语言名，例如 `English`。指定此参数后无需指定 `language_code`。省略时返回所有可用语言的数据。
`language_code`	string	否	语言代码，例如 `en`。指定此参数后无需指定 `language_name`。
`item_types`	array	否	指定返回的搜索结果类型。可选值 `organic`、`paid`、`featured_snippet`、`local_pack`。如果数组中 `organic` 以外的类型，结果将优数组中的第一个类型排序。未返回的类型不能用于筛选或排序。
`include_clickstream_data`	boolean	否	是否返回基于点击流数据计算的指标。设为 `true` 时，响应中会 `clickstream_etv`、`clickstream_gender_distribution` 和 `clickstream_age_distribution`。默认值为 `false`。
`historical_serp_mode`	string	否	历史排名数据模式。`live`：返回目标域名当前仍有排名的搜索结果；`lost`：返回目标域名曾有排名但最近一次检查中已消失的搜索结果；`all`：返回上述两类结果。默认值为 `live`。
`ignore_synonyms`	boolean	否	是否忽略高度相似的。设为 `true` 时返回核心，排除高度相似。默认值为 `false`。
`filters`	array	否	结果筛选规则。最多设置 8 个筛选条件，条件之间使用 `and` 或 `or` 连接。
`order_by`	array	否	结果排序规则。最多设置 3 条。排序方向使用 `asc`（升序）或 `desc`（降序）。
`limit`	integer	否	最多返回的结果数量。默认值为 `100`，最大值为 `1000`。
`offset`	integer	否	结果偏移量。默认值为 `0`。例如设置为 `10` 时，将跳过前 10 条结果。
`tag`	string	否	自定义任务标识，最长 255 个字符。该值会原样返回在响应的 `data` 对象中，可用于请求与结果。

地区与语言参数

可通过以下接口获取可用地区和语言：

text

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

location_name 与 location_code 二选一；language_name 与 language_code 二选一。两组参数均省略时，将返回所有可用地区或语言的数据。

筛选条件

支持以下运算符：

text

regex
not_regex
<
<=
>
>=
=
<>
in
not_in

示例：

json

[
  {
    "target": "example.com",
    "location_code": 2840,
    "language_code": "en",
    "filters": [
      [
        "metrics.organic.pos_1",
        "<>",
        0
      ],
      "or",
      [
        "metrics.organic.pos_2_3",
        "<>",
        0
      ]
    ]
  }
]

排序条件

排序规则格式如下：

json

[
  "metrics.organic.etv,desc",
  "subdomain,asc"
]

如果指定了多个排序规则，使用逗号分隔排序字段和排序方向。最多支持 3 条排序规则。

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/dataforseo_labs/google/subdomains/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "target": "example.com",
      "location_name": "United States",
      "language_name": "English",
      "filters": [
        [
          "metrics.organic.pos_1",
          "<>",
          0
        ],
        "or",
        [
          "metrics.organic.pos_2_3",
          "<>",
          0
        ]
      ],
      "limit": 100
    }
  ]'

Python

python

import requests

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

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

post_data = [
    {
        "target": "example.com",
        "location_name": "United States",
        "language_name": "English",
        "filters": [
            ["metrics.organic.pos_1", "<>", 0],
            "or",
            ["metrics.organic.pos_2_3", "<>", 0],
        ],
    }
]

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

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        f"请求失败，状态码：{result.get('status_code')}，"
        f"信息：{result.get('status_message')}"
    )

TypeScript

typescript

import axios from "axios";

const postData = [
  {
    target: "example.com",
    location_name: "United States",
    language_name: "English",
    filters: [
      ["metrics.organic.pos_1", "<>", 0],
      "or",
      ["metrics.organic.pos_2_3", "<>", 0],
    ],
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/dataforseo_labs/google/subdomains/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	请求执行耗时，例如 `0.1664 sec.`。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务总数。
`tasks_error`	integer	`tasks` 数组中返回错误的任务数。
`tasks`	array	任务结果数组。

任务字段

字段	类型	说明
`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	请求 URL 路径。
`data`	object	创建任务时提交的参数。
`result`	array	任务结果数组。

结果字段

字段	类型	说明
`se_type`	string	搜索引擎类型，本接口为 `google`。
`target`	string	请求中的目标域名。
`location_code`	integer	请求中的地区代码。
`language_code`	string	请求中的语言代码。
`total_count`	integer	数据库中符合请求条件的结果总数。
`items_count`	integer	本次返回的 `items` 数量。
`items`	array	子域名及指标数据。

子域名结果项

每个 items素以下字段：

字段	类型	说明
`se_type`	string	搜索引擎类型。
`subdomain`	string	返回的子域名。
`metrics`	object	该子域名的排名、流量和变化指标。

metrics 对象可能以下搜索结果类型：

organic：自然搜索结果
paid：付费搜索结果
featured_snippet：精选摘要
local_pack：本地搜索结果

各类型对象的字段结构一致，含义根据搜索结果类型有所不同。

排名分布字段

字段	类型	说明
`pos_1`	integer	排名第 1 的搜索结果数量。
`pos_2_3`	integer	排名第 2 至第 3 的搜索结果数量。
`pos_4_10`	integer	排名第 4 至第 10 的搜索结果数量。
`pos_11_20`	integer	排名第 11 至第 20 的搜索结果数量。
`pos_21_30`	integer	排名第 21 至第 30 的搜索结果数量。
`pos_31_40`	integer	排名第 31 至第 40 的搜索结果数量。
`pos_41_50`	integer	排名第 41 至第 50 的搜索结果数量。
`pos_51_60`	integer	排名第 51 至第 60 的搜索结果数量。
`pos_61_70`	integer	排名第 61 至第 70 的搜索结果数量。
`pos_71_80`	integer	排名第 71 至第 80 的搜索结果数量。
`pos_81_90`	integer	排名第 81 至第 90 的搜索结果数量。
`pos_91_100`	integer	排名第 91 至第 100 的搜索结果数量。

流量与排名变化字段

字段	类型	说明
`etv`	float	估算流量。表示该搜索结果类型下的月度预估流量，通常根据点击率与搜索量计算。
`count`	integer	含该子域名的搜索结果总数。
`estimated_paid_traffic_cost`	float	估算流量成本。表示通过 Google 搜索广告获取相同月度流量所需的预估成本。
`is_new`	integer	新增排名数量。
`is_up`	integer	排名上升的数量。
`is_down`	integer	排名下降的数量。
`is_lost`	integer	丢失排名的数量，即此前出现在搜索结果中、但最近一次检查未出现的数量。

点击流指标

以下字段在请求参数 include_clickstream_data 设置为 true 时返回：

字段	类型	说明
`clickstream_etv`	integer	基于点击流数据估算的流量，通常根据点击率与点击流搜索量计算。
`clickstream_gender_distribution`	object	点击流数据中的性别分布。
`clickstream_age_distribution`	object	点击流数据中的年龄分布。

性别分布

字段	类型	说明
`female`	integer	点击流样本中的女性用户数量。
`male`	integer	点击流样本中的男性用户数量。

年龄分布

字段	类型	说明
`18-24`	integer	18 至 24 岁用户数量。
`25-34`	integer	25 至 34 岁用户数量。
`35-44`	integer	35 至 44 岁用户数量。
`45-54`	integer	45 至 54 岁用户数量。
`55-64`	integer	55 至 64 岁用户数量。

不同结果类型中的指标说明

`organic`

表示自然搜索数据：

自然搜索排名分布
自然搜索估算流量 etv -含该子域名的自然搜索结果数量 count
将自然流量转化为付费广告流量的估算成本 estimated_paid_traffic_cost
新增、上升、下降和丢失的排名
可选的点击流流量及用户画像数据

`paid`

表示付费搜索数据：

付费搜索排名分布
付费搜索估算流量 etv -含该子域名的付费搜索结果数量 count
基于 etv 与每次点击成本估算的月度广告流量成本
新增、上升、下降和丢失的排名
可选的点击流流量及用户画像数据

`featured_snippet`

表示 Google 精选摘要结果数据：

精选摘要排名分布
精选摘要估算流量 etv -含该子域名的精选摘要数量 count
精选摘要的估算流量成本
新增、上升、下降和丢失的排名
可选的点击流流量及用户画像数据

`local_pack`

表示 Google 本地搜索结果数据：

本地搜索结果排名分布
本地搜索估算流量 etv -含该子域名的本地搜索结果数量 count
本地搜索的估算流量成本
新增、上升、下降和丢失的排名
可选的点击流流量及用户画像数据

响应示例

json

{
  "version": "0.1.20240514",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.1664 sec.",
  "cost": 0.0101,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1500 sec.",
      "cost": 0.0101,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "google",
        "subdomains",
        "live"
      ],
      "data": {
        "api": "dataforseo_labs",
        "function": "subdomains",
        "se_type": "google",
        "target": "example.com",
        "language_name": "English",
        "location_code": 2840,
        "filters": [
          [
            "metrics.organic.pos_1",
            "<>",
            0
          ],
          "or",
          [
            "metrics.organic.pos_2_3",
            "<>",
            0
          ]
        ]
      },
      "result": [
        {
          "se_type": "google",
          "target": "example.com",
          "location_code": 2840,
          "language_code": "en",
          "total_count": 12,
          "items_count": 1,
          "items": [
            {
              "se_type": "google",
              "subdomain": "blog.example.com",
              "metrics": {
                "organic": {
                  "pos_1": 10,
                  "pos_2_3": 18,
                  "pos_4_10": 45,
                  "pos_11_20": 30,
                  "etv": 12500.5,
                  "count": 103,
                  "estimated_paid_traffic_cost": 8420.25,
                  "is_new": 4,
                  "is_up": 12,
                  "is_down": 7,
                  "is_lost": 2
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

错误处理

应同时检查以下状态字段：

顶层 status_code、status_message
任务级 status_code、status_message
tasks_error 是否大于 0

20000 表示请求成功。完整状态码和错误信息请参考错误码文档。

实用场景

识别高价值子域名：按自然搜索估算流量和排名分布筛选核心子域名，为资源和 SEO 预算分提供依据。
定位增长机会：比较 is_new、is_up、is_down 和 is_lost 指标，快速发现排名增长或流失最明显的业务模块。
评估自然流量商业价值：结合 etv 与 estimated_paid_traffic_cost，估算各子域名自然流量的广告替代成本，投放和投资决策。
分析搜索结果类型覆盖：分别查询 organic、paid、featured_snippet 和 local_pack，判断不同子域名在自然结果、广告、精选摘要和本地搜索中的可见度。
制定区域化策略：按地区和语言拆分子域名排名及流量数据，识别不同市场的 SEO 表现差异并优化本地化。

Google 子域名实时分析 ​

接口说明 ​

计费说明 ​

认证方式 ​

请求参数 ​

地区与语言参数 ​

筛选条件 ​

排序条件 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

任务字段 ​

结果字段 ​

子域名结果项 ​

排名分布字段 ​

流量与排名变化字段 ​

点击流指标 ​

性别分布 ​

年龄分布 ​

不同结果类型中的指标说明 ​

organic ​

paid ​

featured_snippet ​

local_pack ​

响应示例 ​

错误处理 ​

实用场景 ​

Google 子域名实时分析

接口说明

计费说明

认证方式

请求参数

地区与语言参数

筛选条件

排序条件

请求示例

cURL

Python

TypeScript

响应结构

顶层字段

任务字段

结果字段

子域名结果项

排名分布字段

流量与排名变化字段

点击流指标

性别分布

年龄分布

不同结果类型中的指标说明

`organic`

`paid`

`featured_snippet`

`local_pack`

响应示例

错误处理

实用场景