SeerMarTech API 文档

主题

域名排名概览（实时） ​

接口说明 ​

该接口用于获取指定域名在自然搜索与付费搜索中的排名和流量概览数据。你可以查看该域名在 SERP 中的排名分布，以及自然结果和付费结果的预估月流量表现。

数据更新频率 ​

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

返回结果排序规则 ​

响应中的域名数据按以下顺序排序：

  1. 按 location_code 数值升序排序，例如 2840 会排在 3000 前；
  2. 若 location_code 相同，则按 language_code 字母升序排序，例如 "en" 会排在 "es" 前。

请求方式 ​

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

计费说明 ​

每次请求均会产生费用。 参考价请以平台计费为准，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

调用限制 ​

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

请求体格式 ​

所有 POST 数据均需使用 JSON（UTF-8 编码），且请求体为 JSON 数组：

json
[
 {
 "target": "example.com",
 "language_name": "English",
 "location_code": 2840
 }
]

请求参数 ​

字段名类型说明
targetstring填。目标网站的域名。不要 https:// 和 www.。
location_namestring可选。地区名。使用该字段时，无需再传 location_code。可通过 /v3/dataforseo_labs/locations_and_languages 获取可用地区列表。留空则返回所有可用地区的数据。示例：United Kingdom
location_codeinteger可选。地区编码。使用该字段时，无需再传 location_name。可通过 /v3/dataforseo_labs/locations_and_languages 获取可用地区列表。留空则返回所有可用地区的数据。示例：2840
language_namestring可选。语言名。使用该字段时，无需再传 language_code。可通过 /v3/dataforseo_labs/locations_and_languages 获取可用语言列表。留空则返回所有可用语言的数据。示例：English
language_codestring可选。语言代码。使用该字段时，无需再传 language_name。可通过 /v3/dataforseo_labs/locations_and_languages 获取可用语言列表。留空则返回所有可用语言的数据。示例：en
ignore_synonymsboolean可选。是否忽略高相似。设为 true 时，会在排名和流量计算中排除高度相似的基于同义词分组中的主进行计算。默认值：false
limitinteger可选。单次返回的最大结果数。默认值：100，最大值：1000
offsetinteger可选。结果偏移量。默认值：0。例如设置为 10 时，返回结果会跳过前 10 个 items。
tagstring可选。用户自定义任务标识。最大长度 255 个字符。可用于请求与响应结果对账，响应中会在 data 对象返回该值。

响应结构 ​

接口返回 JSON 编码数据，顶层 tasks 数组，每个任务对应一次请求项。

顶层字段 ​

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

建议在接时做好异常状态与错误码处理。

tasks[] 字段 ​

字段名类型说明
idstring任务唯一标识，UUID 格式
status_codeinteger任务状态码，范围通常为 10000–60000，完整列表见 /v3/appendix/errors
status_messagestring任务状态信息
timestring任务执行耗时，单位秒
costfloat当前任务费用，单位 USD
result_countintegerresult 数组中的数量
patharrayURL 路径
dataobject与请求中提交的参数一致
resultarray结果数组

result[] 字段 ​

字段名类型说明
se_typestring搜索引擎类型
targetstring请求中的目标域名
location_codeinteger请求中的地区编码
language_codestring请求中的语言代码
total_countinteger数据库中与本次请求匹的总结果数
items_countinteger当前 items 数组返回的结果数
itemsarray排名与流量数据列表

items[] 字段 ​

字段名类型说明
se_typestring搜索引擎类型
location_codeinteger请求中的地区编码
language_codestring请求中的语言代码
metricsobject指定域名的排名指标对象

metrics 结构说明 ​

metrics.organic ​

自然搜索中的排名与流量数据。

字段名类型说明
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若将自然搜索流量转化为付费投放所需的预估月成本。基于自然 etv 与付费 cpc 估算。
is_newinteger新增排名数量
is_upinteger排名上升的数量
is_downinteger排名下降的数量
is_lostinteger丢失排名的数量，即此前存在于 SERP、最近一次检查未发现的数量

metrics.paid ​

付费搜索中的排名与流量数据。

字段名类型说明
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预估月付费流量成本，基于 etv 与 cpc 估算。
is_newinteger新增排名数量
is_upinteger排名上升的数量
is_downinteger排名下降的数量
is_lostinteger丢失排名的数量

请求示例 ​

cURL ​

bash
curl --location --request POST "https://api.seermartech.cn/v3/dataforseo_labs/google/domain_rank_overview/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "target": "example.com",
 "language_name": "English",
 "location_code": 2840
 }
]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/google/domain_rank_overview/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "target": "example.com",
 "location_name": "United States",
 "language_name": "English"
 }
]

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

TypeScript ​

typescript
import axios from "axios";

const postArray = [
 {
 target: "example.com",
 language_name: "English",
 location_code: 2840,
 },
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/dataforseo_labs/google/domain_rank_overview/live",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
 data: postArray,
})
 .then((response) => {
 // 输出结果数据
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应示例 ​

json
{
 "version": "0.1.20220216",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.2946 sec.",
 "cost": 0.0101,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "dataforseo_labs",
 "function": "domain_rank_overview",
 "se_type": "google",
 "target": "example.com",
 "language_name": "English",
 "location_code": 2840
 },
 "result": []
 }
 ]
}

错误处理 ​

可通过以下字段判断请求是否成功：

  • 顶层 status_code
  • tasks[].status_code
  • tasks[].status_message

完整错误码与状态说明请参考 /v3/appendix/errors。 建议同时处理以下：

  • 鉴权失败
  • 参数缺失或格式错误
  • 并发或频率限
  • 平台数据暂时不可用
  • 单个任务成功、部分任务失败的混合返回场景

使用建议 ​

  • 若要限定国家或地区，优使用 location_code
  • 若要限定语言，优使用 language_code
  • 如需减少同义词对流量与排名估算的重复影响，可将 ignore_synonyms 设为 true
  • 当需要遍历大量地区或语言结果时，可结合 limit 与 offset 分页拉取
  • 如果未指定地区和语言，接口会返回所有可用地区/语言的数据，响应体可能较大

实用场景 ​

  • 评估站点 SEO 整体可见度：查看目标域名在自然搜索前 1、前 3、前 10、前 100 的分布，快速判断 SEO 基础盘是否稳固。
  • 对比自然流量与付费流量结构：同时分析 organic 与 paid 指标，识别品牌更依赖自然获客还是广告投放。
  • 监控排名波动趋势：结合 is_new、is_up、is_down、is_lost 指标，发现近期新增词、上涨词和丢词，及时定位异常。
  • 估算流量商业价值：利用 etv 和 estimated_paid_traffic_cost 评估自然流量替代广告流量的成本，为 SEO 投产出分析提供依据。
  • 开展多地区搜索表现分析：按不同 location_code 和 language_code 获取结果，评估同一域名在不同市场的搜索表现差异。

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

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