SeerMarTech API 文档

主题

按分类查询域名指标对比（实时） ​

POST /v3/dataforseo_labs/google/domain_metrics_by_categories/live

接口概述 ​

该接口用于返回与指定产品/服务分类的域名指标变化趋势。您可以获取来自 Google SERP 的历史排名数据，以及当前和历史域名指标，例如：

  • ETV（预估流量）
  • impressions ETV
  • 预估付费流量成本 -含该域名的 SERP 总数量
  • 排名新增、上涨、下降、丢失

接口适合用于比较两个时间点之间，某些行业分类下域名整体表现的变化。

  • 数据更新频率：每周
  • 最新更新时间：可通过 /v3/dataforseo_labs/status/ 查询

请求信息 ​

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

计费说明 ​

该接口按请求计费。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

调用限制 ​

  • 每分钟最多 2000 次 API 调用
  • 同时并发请求上限 30

请求体格式 ​

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

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

请求参数 ​

字段名类型说明
category_codesarray填。产品和服务分类代码数组。最多可指定 5 个分类。可通过参考文档获取分类列表。
first_datestring填。第一个对比日期，格式：yyyy-mm-dd，例如：2021-06-01。可用日期可通过 /v3/dataforseo_labs/google/available_history/live/ 获取。不能大于当前日期；且不能与 second_date 处于同一年同一月。最小值：2020-10-01。
second_datestring填。第二个对比日期，格式：yyyy-mm-dd，例如：2021-10-01。可用日期可通过 /v3/dataforseo_labs/google/available_history/live/ 获取。不能大于当前日期；且不能与 first_date 处于同一年同一月。最小值：2020-10-01。
location_namestring当未指定 location_code 时填。地点完整名称。在 location_name 与 location_code 中二选一。可通过 /v3/dataforseo_labs/locations_and_languages 获取可用地点。示例：United Kingdom
location_codeinteger当未指定 location_name 时填。地点唯一编码。在 location_name 与 location_code 中二选一。可通过 /v3/dataforseo_labs/locations_and_languages 获取可用地点。示例：2840
language_namestring当未指定 language_code 时填。语言完整名称。在 language_name 与 language_code 中二选一。可通过 /v3/dataforseo_labs/locations_and_languages 获取可用语言。示例：English
language_codestring当未指定 language_name 时填。语言唯一编码。在 language_name 与 language_code 中二选一。可通过 /v3/dataforseo_labs/locations_and_languages 获取可用语言。示例：en
item_typesarray可选。指定响应中的搜索结果类型。**注意：**如果 item_types 中的首个类型不是 organic，结果将按数组中的第一个类型排序；且无法对未在响应中的结果类型进行过滤和排序。
top_categories_countinteger可选。返回额外分类中的域名数量。通过该参数，除了 category_codes 指定的分类外，还可获取属于分类的域名。默认值等于 category_codes 中指定的分类数量；不能小于 category_codes 中的分类数；最大值：5。
include_subdomainsboolean可选。是否在响应中返回子域名。false：返回 main_domain；true：返回主域名及子域名（如有）。默认值：true
etv_mininteger可选。域名当前自然流量 ETV 最小值。设置后返回 organic_etv 大于该值的域名。
etv_maxinteger可选。域名当前自然流量 ETV 最大值。设置后返回 organic_etv 小于该值的域名。
correlateboolean可选。是否与之前获取的数据集进行校准。默认值：true。用于减轻数据库变化带来的数据不一致问题。不建议设为 false。
limitinteger可选。返回结果中域名数量上限。默认值：100，最大值：1000。
offsetinteger可选。结果偏移量。默认值：0。例如设置为 10 时，将跳过前 10 个域名，从后续域名开始返回。
filtersarray可选。结果过滤条件数组。最多支持 8 个过滤条件。条件之间应使用逻辑运算符 and / or 连接。支持的运算符：regex、not_regex、<、<=、>、>=、=、<>、in、not_in、match、not_match、ilike、not_ilike、like、not_like。like / not_like / ilike / not_ilike 支持使用 % 匹任意长度字符串。更多说明可参考 /v3/dataforseo_labs/filters。
order_byarray可选。结果排序规则。可使用与 filters 相同的字段路径。默认按系统默认规则排序。排序方式：asc 升序，desc 降序。单次请求最多可设置 3 条排序规则。
tagstring可选。自定义任务标识，最大长度 255 字符。可用于在响应中识别该任务，返回时会出现在 data 对象中。

响应结构 ​

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

顶层字段 ​

字段名类型说明
versionstring当前 API 版本
status_codeinteger通用状态码。完整错误码见 /v3/appendix/errors
status_messagestring通用状态信息
timestring执行耗时，单位秒
costfloat本次请求总费用，单位 USD
tasks_countintegertasks 数组中的任务数量
tasks_errorinteger返回错误的任务数量
tasksarray任务结果数组

tasks[] 字段 ​

字段名类型说明
idstring任务唯一标识，UUID 格式
status_codeinteger任务状态码
status_messagestring任务状态说明
timestring任务执行耗时
costfloat任务费用，单位 USD
result_countintegerresult 数组中的数量
patharray请求路径
dataobject请求中提交的参数
resultarray获取结果

result[] 字段 ​

字段名类型说明
se_typestring搜索引擎类型
categoriesarray请求中的分类
location_codeinteger请求中的地点代码
language_codestring请求中的语言代码
total_countinteger数据库中符合条件的总结果数
items_countintegeritems 数组返回的结果数
itemsarray历史排名与流量数据

items[] 字段说明 ​

字段名类型说明
se_typestring搜索引擎类型
top_categoriesarray采集该域名时的分类
organic_etvfloat域名当前自然搜索 ETV
organic_countinteger当前该域名的自然搜索 SERP 总数
organic_is_lostinteger当前丢失的已排名数量
organic_is_newinteger当前新增的已排名数量
domainstring命中的域名
main_domainstring主域名
metrics_historyobject该域名的历史排名与流量数据
metrics_differenceobject两个日期之间的指标差值

metrics_history 结构说明 ​

metrics_history 以年月作为键，例如 202110、202106。 说明：

  • 较大的日期对应 first_date 与 second_date 中较晚的月份
  • 较小的日期对应较早的月份

每个月份对象下可以下类型的数据：

  • organic
  • paid
  • featured_snippet
  • local_pack

上述每种对象均可能以下字段：

字段名类型说明
pos_1integer排名第 1 位的 SERP 数量
pos_2_3integer排名第 2-3 位的 SERP 数量
pos_4_10integer排名第 4-10 位的 SERP 数量
pos_11_20integer排名第 11-20 位的 SERP 数量
pos_21_30integer排名第 21-30 位的 SERP 数量
pos_31_40integer排名第 31-40 位的 SERP 数量
pos_41_50integer排名第 41-50 位的 SERP 数量
pos_51_60integer排名第 51-60 位的 SERP 数量
pos_61_70integer排名第 61-70 位的 SERP 数量
pos_71_80integer排名第 71-80 位的 SERP 数量
pos_81_90integer排名第 81-90 位的 SERP 数量
pos_91_100integer排名第 91-100 位的 SERP 数量
etvfloat预估流量。按指定日期该域名所有已排名的 CTR 与搜索量乘积估算。
countinteger含该域名的对应类型 SERP 总数
estimated_paid_traffic_costfloat预估流量成本。用于估算若通过付费广告获取同等流量所需成本。
is_newinteger新增排名数量
is_upinteger排名上升的数量
is_downinteger排名下降的数量
is_lostinteger丢失排名数量

说明：

  • organic 表示自然搜索数据
  • paid 表示付费搜索数据
  • featured_snippet 表示精选摘要数据
  • local_pack 表示本地结果数据 某些类型在特定月份可能为 null。

metrics_difference 结构说明 ​

metrics_difference 表示 first_date 与 second_date 之间的指标差值。 计算方式为：较晚日期的指标值减去较早日期的指标值。

支持以下对象：

  • organic
  • paid
  • featured_snippet
  • local_pack

各对象字段与 metrics_history 中对应结构一致，含义为该指标在两个时间点之间的变化量。例如：

  • pos_1：排名第 1 的 SERP 数量变化
  • etv：预估流量变化
  • count：该域名的 SERP 数量变化
  • estimated_paid_traffic_cost：等价流量成本变化
  • is_new / is_up / is_down / is_lost：对应状态数量变化

请求示例 ​

cURL ​

bash
curl --location --request POST "https://api.seermartech.cn/v3/dataforseo_labs/google/domain_metrics_by_categories/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "category_codes": [13418, 10004],
 "location_code": 2840,
 "language_name": "English",
 "first_date": "2021-06-01",
 "second_date": "2021-10-01",
 "filters": [
 ["metrics_history.202106.organic.pos_1", ">", 0],
 "and",
 ["organic_etv", ">", 10000]
 ],
 "limit": 3
 }
]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/google/domain_metrics_by_categories/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "category_codes": [13418, 10004],
 "location_code": 2840,
 "language_name": "English",
 "first_date": "2021-06-01",
 "second_date": "2021-10-01",
 "filters": [
 ["metrics_history.202106.organic.pos_1", ">", 0],
 "and",
 ["organic_etv", ">", 10000]
 ],
 "limit": 3
 }
]

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

TypeScript ​

typescript
import axios from "axios";

const postData = [
 {
 category_codes: [13418, 10004],
 location_code: 2840,
 language_name: "English",
 first_date: "2021-06-01",
 second_date: "2021-10-01",
 filters: [
 ["metrics_history.202106.organic.pos_1", ">", 0],
 "and",
 ["organic_etv", ">", 10000]
 ],
 limit: 3
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/dataforseo_labs/google/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.20220216",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "1.8991 sec.",
 "cost": 0.103,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "dataforseo_labs",
 "function": "domain_metrics_by_categories",
 "se_type": "google",
 "location_code": 2840,
 "language_code": "en",
 "category_codes": [13418, 10004],
 "first_date": "2021-06-01",
 "second_date": "2021-10-01",
 "limit": 3
 },
 "result": [
 {
 "location_code": 2840,
 "language_code": "en",
 "total_count": 1131,
 "items_count": 3,
 "items": [
 {
 "organic_etv": 1179.6579938028008,
 "organic_count": 58,
 "organic_is_lost": 11,
 "organic_is_new": 12,
 "domain": "enricospastryshop.com",
 "main_domain": "enricospastryshop.com",
 "metrics_history": {
 "202106": {
 "organic": {
 "pos_1": 4,
 "pos_2_3": 3,
 "pos_4_10": 1,
 "pos_11_20": 4,
 "pos_21_30": 6,
 "pos_31_40": 1,
 "pos_41_50": 2,
 "pos_51_60": 4,
 "pos_61_70": 5,
 "pos_71_80": 7,
 "pos_81_90": 4,
 "pos_91_100": 1,
 "etv": 147.2205658582747,
 "count": 41,
 "estimated_paid_traffic_cost": 69.1921289233835,
 "is_new": 1,
 "is_up": 4,
 "is_down": 15,
 "is_lost": 12
 },
 "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,
 "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
 },
 "202110": {
 "organic": {
 "pos_1": 4,
 "pos_2_3": 4,
 "pos_4_10": 0,
 "pos_11_20": 4,
 "pos_21_30": 4,
 "pos_31_40": 3,
 "pos_41_50": 3,
 "pos_51_60": 7,
 "pos_61_70": 6,
 "pos_71_80": 6,
 "pos_81_90": 0,
 "pos_91_100": 4,
 "etv": 308.8720009159297,
 "count": 46,
 "estimated_paid_traffic_cost": 335.2933321259916,
 "is_new": 12,
 "is_up": 11,
 "is_down": 7,
 "is_lost": 19
 },
 "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,
 "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": 1,
 "pos_2_3": 1,
 "pos_4_10": -1,
 "pos_11_20": 0,
 "pos_21_30": -1,
 "pos_31_40": 2,
 "pos_41_50": 1,
 "pos_51_60": 3,
 "pos_61_70": 1,
 "pos_71_80": -1,
 "pos_81_90": -4,
 "pos_91_100": 3,
 "etv": 161.65143505765496,
 "count": 6,
 "estimated_paid_traffic_cost": 266.1012032026081,
 "is_new": 11,
 "is_up": 6,
 "is_down": -8,
 "is_lost": 7
 },
 "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,
 "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 表示任务的执行状态
  • 建议同时检查：
  • HTTP 状态码
  • 顶层 status_code
  • tasks_error
  • 各任务的 status_code

完整错误码定义可参考 /v3/appendix/errors。 强烈建议在接时实现完善的异常处理与重试机制。

使用建议 ​

  1. 通过 /v3/dataforseo_labs/google/available_history/live/ 获取可用历史月份，再设置 first_date 与 second_date
  2. 若需要地点和语言枚举值，可调用 /v3/dataforseo_labs/locations_and_languages
  3. 若需要更稳定的跨期比较结果，建议保留 correlate=true
  4. 当需要筛选高价值域名时，可结合 filters 与 etv_min / etv_max
  5. 如果需要对子域做单独分析，请保留 include_subdomains=true

实用场景 ​

  • 对比行业站点涨跌：按分类查看两个时间点之间的域名排名与流量变化，快速识别行业赢家和下滑站点。
  • 筛选潜在竞品：通过 organic_etv、count、is_new 等指标过滤出增长明显的域名，用于竞品监测和市场研究。
  • 评估细分赛道活跃度：结合 top_categories_count 扩展分类，发现相邻行业中的流量参与，或产品布局。
  • 监控本地与特色结果占位：分析 featured_snippet、local_pack 等结果类型在不同时间点的表现，评估 SERP 特殊版位机会。
  • 追踪域名历史表现：基于 metrics_history 和 metrics_difference 建立时间对比报表，用于 SEO 月报、季度复盘和客户汇报。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API