历史排名概览（旧版）/v3/dataforseo_labs/historical_rank_overview/live

接口说明

该接口用于查询指定域名的历史排名与流量数据，适合按时间维度分析站点在搜索结果中的可见性变化：

• 域名在 SERP 中的排名分布
• 自然搜索与付费搜索的预估月流量
• 排名新增、上升、下降、丢失等变化趋势

说明：

• 该文档对应的是旧版（Legacy）结构，平台 API 仍持续容。
• 历史数据最早可追溯到 2020-10-01。

请求信息

请求方式： POST请求地址： https://api.seermartech.cn/v3/dataforseo_labs/historical_rank_overview/live

参考计费： 按请求次数计费。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

频率限制： 每分钟最多可发送 2000 次 API 调用。

请求体格式： JSON（UTF-8），且为 JSON 数组：

[
 {
 "target": "example.com",
 "location_code": 2840,
 "language_name": "English",
 "date_from": "2021-01-01",
 "date_to": "2021-03-29"
 }
]

---

请求参数

参数名	类型	说明
target	string	填。目标网站的域名。请不要 https:// 和 www.。
location_name	string	地区完整名称。未提供 location_code 时填。location_name 与 location_code 二选一。示例：United Kingdom
location_code	integer	地区编码。未提供 location_name 时填。location_name 与 location_code 二选一。示例：2840
language_name	string	语言完整名称。未提供 language_code 时填。language_name 与 language_code 二选一。示例：English
language_code	string	语言代码。未提供 language_name 时填。language_name 与 language_code 二选一。示例：en
date_from	string	可选。时间范围起始日期。默认返回过去 6 个月数据。最早可设为 2020-10-01。格式：yyyy-mm-dd
date_to	string	可选。时间范围结束日期。默认使用当天日期。格式：yyyy-mm-dd，示例：2021-04-01
correlate	boolean	可选。是否与历史已获取数据进行校正，默认 true。用于减轻平台数据库变更带来的不一致，建议始终设为 true。
tag	string	可选。自定义任务标识，最长 255 个字符。可用于请求结果匹，响应中的 data 对象会返回该值。

地区和语言列表

如需获取可用的地区和语言列表，可调用：

/v3/dataforseo_labs/locations_and_languages

---

返回结果说明

响应为 JSON 对象， tasks 数组。

顶层字段

字段	类型	说明
version	string	API 当前版本
status_code	integer	接口通用状态码
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	请求路径
data	object	原样返回请求时提交的参数
result	array	结果数组

result 数组字段

字段	类型	说明
target	string	请求中的目标域名
location_code	integer	请求中的地区编码
language_code	string	请求中的语言代码
total_count	integer	数据库中与请求匹的结果总数
items_count	integer	items 中返回的数据条数
items	array	历史排名与流量数据列表

items 数组字段

每个 items素对应一个月份的数据快。

字段	类型	说明
year	integer	数据所属年份
month	integer	数据所属月份
metrics	object	指定域名的排名指标数据

---

metrics.organic 字段说明

metrics.organic 表示自然搜索数据。

字段	类型	说明
pos_1	integer	排名第 1 位的自然搜索结果数量
pos_2_3	integer	排名第 2-3 位的自然搜索结果数量
pos_4_10	integer	排名第 4-10 位的自然搜索结果数量
pos_11_20	integer	排名第 11-20 位的自然搜索结果数量
pos_21_30	integer	排名第 21-30 位的自然搜索结果数量
pos_31_40	integer	排名第 31-40 位的自然搜索结果数量
pos_41_50	integer	排名第 41-50 位的自然搜索结果数量
pos_51_60	integer	排名第 51-60 位的自然搜索结果数量
pos_61_70	integer	排名第 61-70 位的自然搜索结果数量
pos_71_80	integer	排名第 71-80 位的自然搜索结果数量
pos_81_90	integer	排名第 81-90 位的自然搜索结果数量
pos_91_100	integer	排名第 91-100 位的自然搜索结果数量
etv	float	预估自然月流量。按 CTR 与搜索量计算得到。
impressions_etv	float	基于量计算的预估自然月流量。
count	integer	含该域名的自然搜索 SERP 总数
estimated_paid_traffic_cost	float	若将当前自然流量通过 PPC 广告购买所需的预估月成本（USD）
is_new	integer	新增排名数量
is_up	integer	排名上升的数量
is_down	integer	排名下降的数量
is_lost	integer	丢失排名的数量

---

metrics.paid 字段说明

metrics.paid 表示付费搜索数据。

字段	类型	说明
pos_1	integer	排名第 1 位的付费搜索结果数量
pos_2_3	integer	排名第 2-3 位的付费搜索结果数量
pos_4_10	integer	排名第 4-10 位的付费搜索结果数量
pos_11_20	integer	排名第 11-20 位的付费搜索结果数量
pos_21_30	integer	排名第 21-30 位的付费搜索结果数量
pos_31_40	integer	排名第 31-40 位的付费搜索结果数量
pos_41_50	integer	排名第 41-50 位的付费搜索结果数量
pos_51_60	integer	排名第 51-60 位的付费搜索结果数量
pos_61_70	integer	排名第 61-70 位的付费搜索结果数量
pos_71_80	integer	排名第 71-80 位的付费搜索结果数量
pos_81_90	integer	排名第 81-90 位的付费搜索结果数量
pos_91_100	integer	排名第 91-100 位的付费搜索结果数量
etv	float	预估付费月流量。按 CTR 与搜索量计算得到。
impressions_etv	float	基于量计算的预估付费月流量。
count	integer	含该域名的付费搜索 SERP 总数
estimated_paid_traffic_cost	float	当前付费月流量的预估成本（USD），基于 etv 与 cpc 计算
is_new	integer	新增排名数量
is_up	integer	排名上升的数量
is_down	integer	排名下降的数量
is_lost	integer	丢失排名的数量

---

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/dataforseo_labs/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"
 }
]'

Python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/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"
 }
]

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

TypeScript

import axios from "axios";

const postData = [
 {
 target: "example.com",
 language_name: "English",
 location_code: 2840,
 date_from: "2021-01-01",
 date_to: "2021-03-29"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/dataforseo_labs/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);
 });

---

响应示例

以下示例基于参考文档结构整理，原始示例存在截断，这里保留核心字段结构用于说明。

{
 "version": "0.1.20210818",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "3.7830 sec.",
 "cost": 0.103,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "dataforseo_labs",
 "function": "historical_rank_overview",
 "target": "example.com",
 "location_code": 2840,
 "language_code": "en",
 "date_from": "2021-01-01",
 "date_to": "2021-03-29"
 },
 "result": [
 {}
 ]
 }
 ]
}

---

状态码与错误处理

• 顶层 status_code 表示整次请求的处理状态
• tasks[].status_code 表示单个任务的执行状态
• 建议同时检查这两个字段，并对异常状态建立重试、告警和参数校验机制

常见成功状态：

状态码	含义
20000	请求成功

更多错误码与状态说明请参考错误码文档。

---

使用建议

1. 域名格式要标准：target 填写裸域名，不要带协议头和 www。
2. 尽量使用 correlate=true：有助于保持历史数据的连续性与可比性。
3. 按月进行趋势分析：该接口返回的是历史月份维度数据，适合做长期走势监控。
4. 自然与付费分开解读：organic 与 paid 指标口径不同，建议分别建模分析。

实用场景

• 监控域名历史 SEO 可见性：按月追踪自然搜索排名分布变化，快速判断站点优化是否带来稳定提升。
• 评估流量波动原因：结合 etv、is_up、is_down、is_lost 等字段，定位流量增长或下滑是由排名变化还是覆盖变化造成的。
• 衡量自然流量商业价值：利用 estimated_paid_traffic_cost 估算自然流量的广告替代成本，评估 SEO 投产出比。
• 对比自然与付费搜索表现：同时分析 organic 与 paid 历史数据，识别品牌在和广告投放上的结构变化。
• 发现排名新增与流失趋势：通过 is_new 与 is_lost 识别扩张效果或资产流失，支持更新与收缩决策。