Google 域名分类与排名数据（实时）

POST /v3/dataforseo_labs/google/categories_for_domain/live

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

/v3/dataforseo_labs/google/categories_for_domain/live

用于查询指定域名或子域名参与排名的 Google 产品或服务分类，并返回分类级别的自然搜索、付费搜索及 SERP 排名和流量指标。

数据按周更新，最新更新时间可通过 /v3/dataforseo_labs/status 查询。

接口信息

请求方式：POST
请求地址：https://api.seermartech.cn/v3/dataforseo_labs/google/categories_for_domain/live
请求格式：JSON（UTF-8）
请求体格式：JSON 数组，每次请求最多 1 个任务
并发限制：最多同时发送 30 个请求平台限流以认证说明中的 30/60/120 次/分钟规则为准
计费方式：每次请求计费
参考价：费用取决于请求参数；启用点击流数据后，请求费用按两倍计算。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

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

参数	类型	填	说明
`target`	string	是	目标域名或子域名。不应 `https://` 或 `www.`，例如 `example.com`。
`location_name`	string	条件填	地理位置完整名称。未指定 `location_code` 时填写。`location_name` 与 `location_code` 至少填写一个。
`location_code`	integer	条件填	地理位置代码。未指定 `location_name` 时填写。可通过 `/v3/dataforseo_labs/locations_and_languages` 获取。
`language_name`	string	条件填	语言完整名称。未指定 `language_code` 时填写。`language_name` 与 `language_code` 至少填写一个。
`language_code`	string	条件填	语言代码。未指定 `language_name` 时填写。可通过 `/v3/dataforseo_labs/locations_and_languages` 获取。
`include_subcategories`	boolean	否	是否子分类。`false` 表示忽略子分类，默认值为 `false`。
`include_clickstream_data`	boolean	否	是否返回基于点击流数据计算的指标。设为 `true` 时，结果中会 `clickstream_etv`、`clickstream_gender_distribution` 和 `clickstream_age_distribution`。默认值为 `false`。启用后请求费用按两倍计算。
`historical_serp_mode`	string	否	SERP 数据收集模式。可选值：`live`、`lost`、`all`。默认值为 `live`。
`item_types`	array	否	指定返回的 SERP 结果类型。不同结果类型会影响结果排序及可用的过滤、排序字段。
`filters`	array	否	结果过滤条件，最多设置 8 个过滤条件。多个条件之间使用 `and` 或 `or` 连接。
`order_by`	array	否	结果排序规则。最多设置 3 条，可使用 `asc` 或 `desc` 指定升序或降序。
`limit`	integer	否	最多返回的分类数量。默认值为 `100`，最大值为 `1000`。
`offset`	integer	否	结果偏移量，默认值为 `0`。例如设为 `10`，表示跳过前 10 条结果。
`tag`	string	否	用户自定义任务标识，最长 255 个字符。该值会原样返回在响应任务的 `data` 对象中。

地理位置与语言

可通过以下接口获取可用的地理位置和语言：

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

示例：

location_name：United Kingdom
location_code：2840
language_name：English
language_code：en

`historical_serp_mode` 取值

值	说明
`live`	返回目标域名当前仍有排名的 SERP 指标。
`lost`	返回目标域名曾经有排名、但最近一次检查已不再排名的 SERP 指标。
`all`	同时返回上述两类 SERP 指标。

过滤条件

支持以下运算符：

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

示例：

json

[
  {
    "target": "example.com",
    "location_code": 2840,
    "language_code": "en",
    "filters": [
      [
        "metrics.organic.count",
        ">=",
        100
      ],
      "and",
      [
        [
          "metrics.organic.pos_1",
          ">",
          0
        ],
        "or",
        [
          "metrics.paid.count",
          "in",
          [1, 2]
        ]
      ]
    ]
  }
]

order_by 可使用与 filters 相同的字段，并在字段后指定排序方向，例如：

json

[
  "metrics.organic.etv,desc"
]

请求示例

curl

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/dataforseo_labs/google/categories_for_domain/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",
      "include_subcategories": false,
      "historical_serp_mode": "live",
      "limit": 3,
      "tag": "domain-category-demo"
    }
  ]'

Python

python

import requests

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

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

payload = [
    {
        "target": "example.com",
        "location_name": "United States",
        "language_name": "English",
        "filters": [
            ["metrics.organic.count", ">=", 100],
            "and",
            [
                ["metrics.organic.pos_1", ">", 0],
                "or",
                ["metrics.paid.count", "in", [1, 2]],
            ],
        ],
        "limit": 3,
    }
]

response = requests.post(url, headers=headers, json=payload, timeout=60)
response.raise_for_status()

result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败，错误码：{}，信息：{}".format(
            result.get("status_code"),
            result.get("status_message"),
        )
    )

TypeScript

typescript

import axios from "axios";

const url =
  "https://api.seermartech.cn/v3/dataforseo_labs/google/categories_for_domain/live";

const payload = [
  {
    target: "example.com",
    location_name: "United States",
    language_name: "English",
    filters: [
      ["metrics.organic.count", ">=", 100],
      "and",
      [
        ["metrics.organic.pos_1", ">", 0],
        "or",
        ["metrics.paid.count", "in", [1, 2]],
      ],
    ],
    limit: 3,
  },
];

axios
  .post(url, payload, {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
  })
  .then((response) => {
    const result = response.data;

    if (result.status_code === 20000) {
      console.log(result);
    } else {
      console.error(
        `请求失败，错误码：${result.status_code}，信息：${result.status_message}`
      );
    }
  })
  .catch((error) => {
    console.error("网络或服务异常：", error.message);
  });

响应结构

接口返回 JSON 对象 tasks 数组任务执行结果。

顶层字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	请求级状态码。完整错误码请参考 `/v3/appendix/errors`。
`status_message`	string	请求级说明信息。
`time`	string	请求执行耗时，例如 `0.2802 sec.`。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务总数。
`tasks_error`	integer	执行失败的任务数量。
`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	分类及排名数据。

`result` 字段

字段	类型	说明
`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	搜索引擎类型。
`categories`	array	产品或服务分类。
`metrics`	object	目标域名或子域名在该分类下的排名及流量指标。

metrics 可能以下结果类型：

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

返回的对象取决于数据及 item_types 参数。

指标对象字段

organic、paid、featured_snippet 和 local_pack 对象使用相同的指标结构，区别在于指标对应的 SERP 类型不同。

排名分布字段

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

流量与变化字段

字段	类型	说明
`etv`	float	估算流量。表示目标域名每月可能获得的搜索流量，通常根据点击率与分类搜索量计算。
`count`	integer	含目标域名或子域名的 SERP 总数。
`estimated_paid_traffic_cost`	float	估算流量成本。表示通过 Google 搜索广告获取相同估算流量所需的月度成本，基于 `etv` 与 CPC 计算。
`is_new`	integer	新增排名数量。
`is_up`	integer	排名上升的数量。
`is_down`	integer	排名下降的数量。
`is_lost`	integer	之前存在排名、但最近一次检查未发现的排名数量。

点击流量字段

只有将 include_clickstream_data 设置为 true 时，以下字段才会返回：

字段	类型	说明
`clickstream_etv`	integer	基于点击流数据估算的流量，按点击率与点击流搜索量计算。
`clickstream_gender_distribution`	object	点击流数据中的性别分布。
`clickstream_gender_distribution.female`	integer	点击流样本中的女性用户占比或数量指标。
`clickstream_gender_distribution.male`	integer	点击流样本中的男性用户占比或数量指标。
`clickstream_age_distribution`	object	点击流数据中的年龄分布。
`clickstream_age_distribution.18-24`	integer	18–24 岁用户指标。
`clickstream_age_distribution.25-34`	integer	25–34 岁用户指标。
`clickstream_age_distribution.35-44`	integer	35–44 岁用户指标。
`clickstream_age_distribution.45-54`	integer	45–54 岁用户指标。
`clickstream_age_distribution.55-64`	integer	55–64 岁用户指标。

响应示例

以下示例展示一个分类项的型结构。响应可能多个分类项及不同的 SERP 类型。

json

{
  "version": "0.1.20240514",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.2802 sec.",
  "cost": 0.0103,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "00000000-0000-0000-0000-000000000001",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.2500 sec.",
      "cost": 0.0103,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "google",
        "categories_for_domain",
        "live"
      ],
      "data": {
        "api": "dataforseo_labs",
        "function": "categories_for_domain",
        "se_type": "google",
        "target": "example.com",
        "language_code": "en",
        "location_name": "United States",
        "limit": 3
      },
      "result": [
        {
          "se_type": "google",
          "target": "example.com",
          "location_code": 2840,
          "language_code": "en",
          "total_count": 120,
          "items_count": 1,
          "items": [
            {
              "se_type": "google",
              "categories": [
                "Example category"
              ],
              "metrics": {
                "organic": {
                  "pos_1": 13,
                  "pos_2_3": 15,
                  "pos_4_10": 139,
                  "pos_11_20": 186,
                  "pos_21_30": 147,
                  "pos_31_40": 138,
                  "pos_41_50": 149,
                  "pos_51_60": 142,
                  "pos_61_70": 135,
                  "pos_71_80": 132,
                  "pos_81_90": 128,
                  "pos_91_100": 107,
                  "etv": 5467.5736870300025,
                  "count": 1431,
                  "estimated_paid_traffic_cost": 28019.096953213215,
                  "is_new": 491,
                  "is_up": 572,
                  "is_down": 315,
                  "is_lost": 0,
                  "clickstream_etv": 329.783559,
                  "clickstream_gender_distribution": {
                    "female": 34,
                    "male": 65
                  },
                  "clickstream_age_distribution": {
                    "18-24": 15,
                    "25-34": 39,
                    "35-44": 41,
                    "45-54": 3,
                    "55-64": 0
                  }
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

状态码与错误处理

请根据以下字段判断请求是否成功：

顶层 status_code
任务级 tasks[].status_code
对应的 status_message

20000 表示请求或任务执行成功。完整状态码和错误信息请参考：

/v3/appendix/errors

建议客户端针对网络时、参数校验失败、权限错误、频率限制和服务端异常实现重试、告警及错误记录机制。

实用场景

识别域名覆盖的产品与服务分类，快速发现网站获得搜索的主题领域，为架构和栏目规划提供依据。
对比不同分类的自然搜索流量与排名分布，优优化排名位于第 11–20 位且备较高 etv 的主题，提升首页的机会。
监测分类级别的排名变化，结合 is_new、is_up、is_down 和 is_lost 定位增长主题与流量流失主题，支持 SEO 周报和异常告警。
评估自然流量的商业价值，使用 estimated_paid_traffic_cost 估算通过付费搜索获取相同流量的成本， SEO 与广告预算分。
分析分类对应的用户画像，启用 include_clickstream_data 后查看性别和年龄分布，为选题、落地页设计及受众细分提供参考。

Google 域名分类与排名数据（实时） ​

接口信息 ​

请求参数 ​

地理位置与语言 ​

historical_serp_mode 取值 ​

过滤条件 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

任务字段 ​

result 字段 ​

分类项字段 ​

指标对象字段 ​

排名分布字段 ​

流量与变化字段 ​

点击流量字段 ​

响应示例 ​

状态码与错误处理 ​

实用场景 ​

Google 域名分类与排名数据（实时）

接口信息

请求参数

地理位置与语言

`historical_serp_mode` 取值

过滤条件

请求示例

curl

Python

TypeScript

响应结构

顶层字段

任务字段

`result` 字段

分类项字段

指标对象字段

排名分布字段

流量与变化字段

点击流量字段

响应示例

状态码与错误处理

实用场景