SeerMarTech API 文档

主题

历史排名总览 ​

POST /v3/dataforseo_labs/google/historical_rank_overview/live

接口说明 ​

该接口用于获取指定域名的历史排名与流量数据：

  • 域名在搜索结果中的历史排名分布
  • 自然搜索与付费搜索的历史预估月流量
  • 历史排名变化（新增、上升、下降、丢失）
  • 可选的点击流维度流量及人群分布数据

接口按周更新，最新数据更新时间可通过 /v3/dataforseo_labs/status/ 查询。 历史数据最早可追溯至 2020-10-01。

请求方式 ​

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

计费说明 ​

每次请求都会产生扣费。 如未启用点击流数据，参考价约 ¥1.6960 / 次。 若启用 include_clickstream_data=true，请求价格翻倍。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

调用限制 ​

  • 每分钟最多可发起 2000 次 API 调用
  • 最多 30 个请求可同时并发执行
  • POST 请求体为 UTF-8 编码的 JSON 数组格式：[{ ... }]

请求参数 ​

以下为任务对象支持的字段说明。

字段名类型说明
targetstring填。目标网站的域名。填写时不要 https:// 和 www.
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
date_fromstring时间范围起始日期，可选。不传时默认返回过去 6 个月数据。最小值：2020-10-01。格式：yyyy-mm-dd
date_tostring时间范围结束日期，可选。不传时默认使用当天日期。格式：yyyy-mm-dd
correlateboolean可选，默认 true。是否将本次结果与此前获取的数据集进行，用于减小数据库变更带来的不一致问题。建议始终设置为 true
ignore_synonymsboolean可选，默认 false。设为 true 时返回核心对应数据，排除高相似数据
include_clickstream_databoolean可选，默认 false。设为 true 后，响应会增加 clickstream_etv、clickstream_gender_distribution、clickstream_age_distribution 字段。注意：启用后价格翻倍。历史点击流数据自 2024/05 起提供
tagstring可选。自定义任务标识，最长 255 个字符。可用于请求与结果的业务侧，返回时会出现在响应的 data 对象中

请求示例 ​

cURL ​

bash
curl --location --request POST "https://api.seermartech.cn/v3/dataforseo_labs/google/historical_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,
 "date_from": "2021-01-01",
 "date_to": "2021-03-29",
 "correlate": true
 }
]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/google/historical_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",
 "date_from": "2021-01-01",
 "date_to": "2021-03-29",
 "correlate": True
 }
]

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

TypeScript ​

typescript
import axios from "axios";

const postData = [
 {
 target: "example.com",
 location_name: "United States",
 language_name: "English",
 date_from: "2021-01-01",
 date_to: "2021-03-29",
 correlate: true
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/dataforseo_labs/google/historical_rank_overview/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 对象，顶层 tasks 数组。

顶层字段 ​

字段名类型说明
versionstring当前 API 版本
status_codeinteger通用状态码，完整列表见 /v3/appendix/errors
status_messagestring通用状态信息
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_countintegeritems 数组返回的数据条数
itemsarray历史排名与流量数据

items[] 字段 ​

字段名类型说明
se_typestring搜索引擎类型
yearinteger数据所属年份
monthinteger数据所属月份
metricsobject指定域名的排名指标汇总

metrics 字段说明 ​

metrics 下 organic 和 paid 两部分，分别表示自然搜索与付费搜索数据。两字段结构基本一致。

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若将自然流量通过付费投放获取，对应的预估月成本（USD）
is_newinteger新增排名数量
is_upinteger排名上升的数量
is_downinteger排名下降的数量
is_lostinteger丢失排名的数量
clickstream_etvinteger基于点击流数据计算的预估流量。在 include_clickstream_data=true 时返回
clickstream_gender_distributionobject点击流数据的性别分布。在 include_clickstream_data=true 时返回
clickstream_age_distributionobject点击流数据的年龄分布。在 include_clickstream_data=true 时返回

clickstream_gender_distribution ​

字段名类型说明
femaleinteger点击流数据中的女性用户数量
maleinteger点击流数据中的男性用户数量

clickstream_age_distribution ​

字段名类型说明
18-24integer18-24 岁用户数量
25-34integer25-34 岁用户数量
35-44integer35-44 岁用户数量
45-54integer45-54 岁用户数量
55-64integer55-64 岁用户数量

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预估付费月流量
countinteger含该域名的付费搜索 SERP 总数
estimated_paid_traffic_costfloat预估付费月流量成本（USD）
is_newinteger新增排名数量
is_upinteger排名上升的数量
is_downinteger排名下降的数量
is_lostinteger丢失排名的数量
clickstream_etvinteger基于点击流数据计算的预估流量。在 include_clickstream_data=true 时返回
clickstream_gender_distributionobject点击流数据的性别分布。在 include_clickstream_data=true 时返回
clickstream_age_distributionobject点击流数据的年龄分布。在 include_clickstream_data=true 时返回

响应示例 ​

json
{
 "version": "0.1.20240514",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.3473 sec.",
 "cost": 0.106,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "dataforseo_labs",
 "function": "historical_rank_overview",
 "se_type": "google",
 "target": "walmart.com",
 "language_name": "English",
 "location_code": 2840
 },
 "result": [
 {}
 ]
 }
 ]
}

错误处理 ​

  • 顶层 status_code 表示整次请求状态
  • tasks[].status_code 表示单个任务状态
  • 建议同时校验两层状态码，并为异常设计重试、告警和降级处理逻辑
  • 完整错误码列表请参考 /v3/appendix/errors

使用建议 ​

  • 查询较长时间跨度时，建议显式传 date_from 与 date_to，依赖默认时间范围
  • 如需保证不同时间获取结果的可比性，建议始终设置 correlate=true
  • 若只核心表现，可启用 ignore_synonyms=true 以减少高相似词干扰
  • 在确有用户画像或点击流流量分析需求时再启用 include_clickstream_data，以控制成本

实用场景 ​

  • 追踪域名历史 SEO 趋势：按月查看自然排名分布和预估流量变化，评估 SEO 项目长期增长效果
  • 对比自然流量与付费流量结构：同时分析 organic 与 paid 的排名覆盖和流量成本，制定投放与协同策略
  • 识别排名波动拐点：基于 is_new、is_up、is_down、is_lost 等字段定位某月异常波动，快速排查算法更新或站点改版影响
  • 评估品牌在不同市场的搜索表现：切换 location_code 与 language_code，分析域名在不同国家/语言环境下的历史可见度
  • 分析用户人群特征：启用点击流数据后，结合性别与年龄分布观察搜索受众结构，为定位和广告创意优化提供依据

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

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