按分类获取域名指标（旧版实时接口）

接口说明

注意：本接口为 旧版（Legacy）结构。平台 API 已在 2022-03-19 更新了 Labs 接口的请求与响应结构，但当前仍继续支持本页所述的旧版接口。如果你希望使用新版结构，请参考对应的新版本文档。

该接口用于获取与指定产品/服务分类的域名指标变化趋势。接口会返回基于 Google SERP 历史数据计算的域名表现：

当前及历史自然流量估值 ETV
基于展示量的流量估值 impressions_etv
预估付费流量成本 estimated_paid_traffic_cost
域名出现于 SERP 的总次数
排名新增、下降、丢失等变化指标

请求信息

方法：POST
路径：/v3/dataforseo_labs/domain_metrics_by_categories/live
完整地址：https://api.seermartech.cn/v3/dataforseo_labs/domain_metrics_by_categories/live

计费说明

该接口按请求计费。

根据示例响应，本次调用的参考价约 ¥1.6800 / 次。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求格式

所有 POST 数据均应使用 UTF-8 编码的 JSON 格式，且请求体为 JSON 数组：

json

[
 {
 "category_codes": [13418, 11494],
 "language_name": "English",
 "location_code": 2840,
 "first_date": "2021-06-01",
 "second_date": "2021-10-01"
 }
]

使用 POST 方法创建任务参数
请求频率上限：每分钟 2000 次 API 调用
支持通过 limit 控制返回数量
支持通过 order_by 排序
支持通过 filters 过滤

请求参数

任务参数字段说明

字段名	类型	说明
`category_codes`	array	填。产品与服务分类代码数组。最多可指定 5 个分类。可使用分类代码单进行映射。
`first_date`	string	填。对比周期中的第一个日期，格式：`yyyy-mm-dd`，例如：`2021-06-01`。不能晚于今天；`first_date` 与 `second_date` 不能落在同一年的同一个月份；最小可用日期：`2020-10-01`。两个日期可任意顺序填写。
`second_date`	string	填。对比周期中的第二个日期，格式：`yyyy-mm-dd`，例如：`2021-10-01`。不能晚于今天；不能与 `first_date` 指向同一年的同一月份；最小可用日期：`2020-10-01`。两个日期可任意顺序填写。
`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`
`item_types`	array	可选。指定响应中的搜索结果类型。注意：若 `item_types` 中除 `organic` 外的对象类型，结果将按数组中的第一个类型排序；未在响应中的结果类型不能用于排序和过滤。原文未给出完整可选值，可用值以接口容实现为准。
`top_categories_count`	integer	可选。返回额外分类的数量。启用后，接口除了 `category_codes` 指定的分类外，还可返回与这些域名的分类。默认值等于 `category_codes` 中指定的分类数。不能小于 `category_codes` 的数量，最大值：`5`。
`incude_subdomains`	boolean	可选。是否在响应中返回子域名。`false` 返回 `main_domain`；`true` 返回主域及子域（如有）。默认值：`true`。注意：字段名按平台容路径保留，原文拼写即为 `incude_subdomains`。
`etv_min`	integer	可选。当前自然 `organic_etv` 最小值。设置后返回 `organic_etv` 大于该值的域名。
`etv_max`	integer	可选。当前自然 `organic_etv` 最大值。设置后返回 `organic_etv` 小于该值的域名。
`correlate`	boolean	可选。是否与此前获取的数据集做性对齐，默认：`true`。用于降低数据库变动造成的数据不一致。不建议设为 `false`。
`limit`	integer	可选。返回结果中域名的最大数量。默认：`100`；最大：`1000`。
`offset`	integer	可选。结果偏移量，默认：`0`。例如设置为 `10` 时，将跳过前 10 个域名并返回后续结果。
`filters`	array	可选。结果过滤条件数组，最多支持 8 个过滤条件。多个条件之间需使用逻辑运算符 `and` / `or`。支持操作符：`<`, `<=`, `>`, `>=`, `=`, `<>`, `in`, `not_in`, `like`, `not_like`。`like` / `not_like` 支持 `%` 通符。过滤规则写法可参考 `/v3/dataforseo_labs/filters`。
`order_by`	array	可选。结果排序规则。可使用与 `filters` 相同的字段进行排序。排序方式：`asc` 升序，`desc` 降序。单次请求最多可设置 3 条排序规则。
`tag`	string	可选。自定义任务标识，最大长度 `255`。可用于在响应的 `data` 对象中识别任务。

响应结构

接口返回 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[]` 字段

字段名	类型	说明
`categories`	array	请求中传的分类
`location_code`	integer	请求中的地区代码
`language_code`	string	请求中的语言代码
`total_count`	integer	数据库中与当前请求的结果总数
`items_count`	integer	当前 `items` 数组返回的数量
`items`	array	域名历史排名与流量数据

`items[]` 字段说明

字段名	类型	说明
`top_categories`	array	收集该域名时识别出的分类
`organic_etv`	float	域名当前自然搜索 ETV
`organic_count`	integer	当前该域名的自然搜索 SERP 总数
`organic_is_lost`	integer	当前丢失的排名数量，即此前出现但最近一次检查未出现的数
`organic_is_new`	integer	当前新增的排名数量
`domain`	string	在指定分类下找到的域名，可能子域
`main_domain`	string	主域名
`metrics_history`	object	该域名的历史排名与流量数据
`metrics_difference`	object	`first_date` 与 `second_date` 之间的指标差值

`metrics_history` 说明

metrics_history 以月份键值返回，例如：

较晚日期对应：202110
较早日期对应：202106

说明：

较大的日期（月）会显示为 $date_1
较小的日期（月）会显示为 $date_2

每个月份对象下可能以下结果类型：

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

每个结果类型对象都相似的指标结构。

通用排名分布字段

以下字段在 organic、paid、featured_snippet、local_pack 中结构一致：

字段名	类型	说明
`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	预估流量。基于搜索量与 CTR 估算该时间点的月度流量。
`impressions_etv`	float	基于展示量与 CTR 估算的月度流量。
`count`	integer	含该域名的对应类型 SERP 总数
`estimated_paid_traffic_cost`	float	将该流量通过 Google 搜索广告获取的预估成本，单位 USD
`is_new`	integer	该时间点新增排名数量
`is_up`	integer	该时间点排名上升的数量
`is_down`	integer	该时间点排名下降的数量
`is_lost`	integer	该时间点丢失的排名数量

各结果类型含义

`organic`

自然搜索历史排名与流量数据。

`paid`

付费搜索历史排名与流量数据。

`featured_snippet`

精选摘要历史排名与流量数据。若无数据，可能返回 null。

`local_pack`

本地历史排名与流量数据。若无数据，可能返回 null。

`metrics_difference` 说明

metrics_difference 表示两个日期之间的指标差值。

计算方式为：

较晚日期的指标值 - 较早日期的指标值

返回结构同样按以下类型拆分：

organic
paid
featured_snippet
local_pack

每种类型下与 metrics_history 相同的字段，例如：

排名分布变化：pos_1 ~ pos_91_100
流量变化：etv、impressions_etv
覆盖变化：count
成本变化：estimated_paid_traffic_cost
排名状态变化：is_new、is_up、is_down、is_lost

说明：示例数据中的数值表现为“新值减旧值”的结果，例如 202110 - 202106 后得到正负变化值。集成时应以响应数据为准进行解释。

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/dataforseo_labs/domain_metrics_by_categories/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "category_codes": [13418, 11494],
 "language_name": "English",
 "location_code": 2840,
 "first_date": "2021-06-01",
 "second_date": "2021-10-01"
 }
]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/domain_metrics_by_categories/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "category_codes": [13418, 11494],
 "language_name": "English",
 "location_code": 2840,
 "first_date": "2021-06-01",
 "second_date": "2021-10-01"
 }
]

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

TypeScript

typescript

import axios from "axios";

const postData = [
 {
 category_codes: [13418, 11494],
 language_name: "English",
 location_code: 2840,
 first_date: "2021-06-01",
 second_date: "2021-10-01"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/dataforseo_labs/domain_metrics_by_categories/live",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: postData
})
 .then((response) => {
 // 输出接口返回结果
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应示例

json

{
 "version": "0.1.20210917",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "1.3303 sec.",
 "cost": 0.105,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "dataforseo_labs",
 "function": "domain_metrics_by_categories",
 "location_code": 2840,
 "language_code": "en",
 "category_codes": [13418, 11494],
 "first_date": "2021-06-01",
 "second_date": "2021-10-01",
 "limit": 5
 },
 "result": [
 {
 "location_code": 2840,
 "language_code": "en",
 "total_count": 1378,
 "items_count": 5,
 "items": [
 {
 "organic_etv": 106.0256969127804,
 "organic_count": 31,
 "organic_is_lost": 29,
 "organic_is_new": 17,
 "domain": "www.5mstore.com.br",
 "main_domain": "5mstore.com.br",
 "metrics_history": {
 "202110": {
 "organic": {
 "pos_1": 0,
 "pos_2_3": 0,
 "pos_4_10": 0,
 "pos_11_20": 1,
 "pos_21_30": 2,
 "pos_31_40": 3,
 "pos_41_50": 9,
 "pos_51_60": 8,
 "pos_61_70": 9,
 "pos_71_80": 6,
 "pos_81_90": 14,
 "pos_91_100": 5,
 "etv": 15815.38347693719,
 "impressions_etv": 0.010710000060498714,
 "count": 56,
 "estimated_paid_traffic_cost": 16609.743743775063,
 "is_new": 45,
 "is_up": 7,
 "is_down": 0,
 "is_lost": 28
 },
 "paid": {
 "pos_1": 0,
 "pos_2_3": 0,
 "pos_4_10": 0,
 "pos_11_20": 0,
 "pos_21_30": 0,
 "pos_31_40": 0,
 "pos_41_50": 0,
 "pos_51_60": 0,
 "pos_61_70": 0,
 "pos_71_80": 0,
 "pos_81_90": 0,
 "pos_91_100": 0,
 "etv": 0,
 "impressions_etv": 0,
 "count": 0,
 "estimated_paid_traffic_cost": 0,
 "is_new": 0,
 "is_up": 0,
 "is_down": 0,
 "is_lost": 0
 },
 "featured_snippet": null,
 "local_pack": null
 },
 "202106": {
 "organic": {
 "pos_1": 0,
 "pos_2_3": 0,
 "pos_4_10": 0,
 "pos_11_20": 1,
 "pos_21_30": 3,
 "pos_31_40": 5,
 "pos_41_50": 12,
 "pos_51_60": 19,
 "pos_61_70": 22,
 "pos_71_80": 22,
 "pos_81_90": 25,
 "pos_91_100": 16,
 "etv": 7076.367219526859,
 "impressions_etv": 0.06622633553552629,
 "count": 125,
 "estimated_paid_traffic_cost": 7556.070480937276,
 "is_new": 17,
 "is_up": 11,
 "is_down": 1,
 "is_lost": 91
 },
 "paid": {
 "pos_1": 0,
 "pos_2_3": 0,
 "pos_4_10": 0,
 "pos_11_20": 0,
 "pos_21_30": 0,
 "pos_31_40": 0,
 "pos_41_50": 0,
 "pos_51_60": 0,
 "pos_61_70": 0,
 "pos_71_80": 0,
 "pos_81_90": 0,
 "pos_91_100": 0,
 "etv": 0,
 "impressions_etv": 0,
 "count": 0,
 "estimated_paid_traffic_cost": 0,
 "is_new": 0,
 "is_up": 0,
 "is_down": 0,
 "is_lost": 0
 },
 "featured_snippet": null,
 "local_pack": null
 }
 },
 "metrics_difference": {
 "organic": {
 "pos_1": 0,
 "pos_2_3": 0,
 "pos_4_10": 0,
 "pos_11_20": 0,
 "pos_21_30": -1,
 "pos_31_40": -2,
 "pos_41_50": -3,
 "pos_51_60": -11,
 "pos_61_70": -13,
 "pos_71_80": -16,
 "pos_81_90": -11,
 "pos_91_100": -10,
 "etv": 8739.01625741033,
 "impressions_etv": -0.05551633547502757,
 "count": -68,
 "estimated_paid_traffic_cost": 9053.673262837787,
 "is_new": 28,
 "is_up": -4,
 "is_down": -1,
 "is_lost": -63
 },
 "paid": {
 "pos_1": 0,
 "pos_2_3": 0,
 "pos_4_10": 0,
 "pos_11_20": 0,
 "pos_21_30": 0,
 "pos_31_40": 0,
 "pos_41_50": 0,
 "pos_51_60": 0,
 "pos_61_70": 0,
 "pos_71_80": 0,
 "pos_81_90": 0,
 "pos_91_100": 0,
 "etv": 0,
 "impressions_etv": 0,
 "count": 0,
 "estimated_paid_traffic_cost": 0,
 "is_new": 0,
 "is_up": 0,
 "is_down": 0,
 "is_lost": 0
 },
 "featured_snippet": null,
 "local_pack": null
 }
 }
 ]
 }
 ]
 }
 ]
}

错误处理

顶层 status_code 表示整个请求的执行状态
tasks[].status_code 表示单个任务的执行状态
完整错误码列表请参考 /v3/appendix/errors

处理建议

判断 HTTP 状态码是否正常
再检查顶层 status_code 是否为 20000
逐项检查 tasks[].status_code
对 tasks_error > 0 的做重试、告警或降级处理

使用要点

first_date 与 second_date 不能处于同一年的同一月份
最早支持的日期为 2020-10-01
分类最多支持 5 个
若需要查看主域与子域整体表现，保持 incude_subdomains=true
若需要保证跨期分析的一致性，建议保留 correlate=true
若需要分页抓取大量域名，组合使用 limit 与 offset
若需要聚焦高价值域名，可结合 etv_min、filters 与 order_by

实用场景

筛选高价值竞争域名：按指定行业分类拉取域名列表，并按 organic_etv 或 estimated_paid_traffic_cost 排序，快速锁定最值得研究的竞争站点。
对比行业周期变化：比较两个时间点的 metrics_difference，判断某一分类下哪些域名在自然流量、排名覆盖和广告价值上增长最快。
监控细分市场新：结合 organic_is_new、is_new 等字段识别近期在某分类中快速冒头的新域名，竞品预警。
评估子域策略效果：开启 incude_subdomains，观察主域及子域在不同时间点的分类与流量表现，判断分站或区域站布局是否有效。
发现分类外延机会：使用 top_categories_count 查看域名的额外分类，帮助挖掘跨品类拓展或新业务布局方向。

按分类获取域名指标（旧版实时接口） ​

接口说明 ​

请求信息 ​

计费说明 ​

请求格式 ​

请求参数 ​

任务参数字段说明 ​

响应结构 ​

顶层响应字段 ​

tasks[] 字段 ​

result[] 字段 ​

items[] 字段说明 ​

metrics_history 说明 ​

通用排名分布字段 ​

各结果类型含义 ​

organic ​

paid ​

featured_snippet ​

local_pack ​

metrics_difference 说明 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

错误处理 ​

处理建议 ​

使用要点 ​

实用场景 ​