历史排名概览（Legacy）

GET /v3/dataforseo_labs/locations_and_languages

本接口使用 POST 方法，路径为：

/v3/dataforseo_labs/historical_rank_overview/live

> 这是历史版本接口。虽然平台 API 已于 2022-03-19 更新请求与响应结构，但本平台仍容此 Legacy 版本。历史排名数据最早可追溯至 2020-10-01。

本接口用于查询指定域名在指定地区和语言下的历史排名与流量数据：

域名在自然搜索结果中的排名分布；
域名在付费搜索结果中的排名分布；
自然搜索与付费搜索的预估月流量；
预估流量成本；
排名新增、上升、下降及丢失。

请求信息

请求方法：POST
请求地址：https://api.seermartech.cn/v3/dataforseo_labs/historical_rank_overview/live
请求格式：application/json
请求体格式：JSON 数组，例如 [{ ... }] 平台限流以认证说明中的 30/60/120 次/分钟规则为准

每个请求任务都放在通用 POST 数组中。接口支持按时间范围查询历史数据。

计费说明

每次请求均会产生费用。该 Legacy 接口未提供固定人民币单价，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

响应中的 cost 字段（平台原始 USD 成本兼容字段）为容平台结构保留的任务费用字段，结算金额请以人民币计费响应头为准。

请求参数

每个任务对象支持以下字段：

字段	类型	填	说明
`target`	string	是	目标域名。不 `https://` 和 `www.`，例如 `example.com`。
`location_name`	string	条件填	地区名。当未指定 `location_code` 时填。与 `location_code` 二选一。
`location_code`	integer	条件填	地区编码。当未指定 `location_name` 时填。与 `location_name` 二选一。
`language_name`	string	条件填	语言名。当未指定 `language_code` 时填。与 `language_code` 二选一。
`language_code`	string	条件填	语言编码。当未指定 `language_name` 时填。与 `language_name` 二选一。
`date_from`	string	否	查询起始日期，格式为 `yyyy-mm-dd`。未指定时默认查询最近 6 个月。最早支持 `2020-10-01`。
`date_to`	string	否	查询结束日期，格式为 `yyyy-mm-dd`。未指定时默认使用当天日期。
`correlate`	boolean	否	是否将当前数据与此前获取的数据集进行。默认值为 `true`。建议保持为 `true`，以减少数据库变化可能造成的数据不一致。
`tag`	string	否	自定义任务标识，最长 255 个字符。该值会原样出现在响应 `data` 对象中，可用于请求与结果。

地区与语言参数

可通过以下接口获取可用的地区和语言列表：

https://api.seermartech.cn/v3/dataforseo_labs/locations_and_languages

示例：

location_name：United Kingdom
location_code：2840
language_name：English
language_code：en

请求示例

curl

bash

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",
      "location_name": "United States",
      "language_name": "English",
      "date_from": "2021-01-01",
      "date_to": "2021-03-29",
      "correlate": true,
      "tag": "historical-overview-demo"
    }
  ]'

Python

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",
}

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

response = requests.post(url, headers=headers, json=payload, timeout=60)
response.raise_for_status()

result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败，错误码：%s，信息：%s"
        % (result.get("status_code"), result.get("status_message"))
    )

TypeScript

typescript

import axios from "axios";

const response = await axios.post(
  "https://api.seermartech.cn/v3/dataforseo_labs/historical_rank_overview/live",
  [
    {
      target: "example.com",
      location_name: "United States",
      language_name: "English",
      date_from: "2021-01-01",
      date_to: "2021-03-29",
    },
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
  }
);

const result = response.data;

if (result.status_code === 20000) {
  console.log(result);
} else {
  console.error(
    `请求失败，错误码：${result.status_code}，信息：${result.status_message}`
  );
}

响应结构

接口返回 JSON 对象，顶层 tasks 数组。

json

{
  "version": "0.1.20210818",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "3.7830 sec.",
  "cost": 0.103,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "3.7000 sec.",
      "cost": 0.103,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "historical_rank_overview",
        "live"
      ],
      "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": [
        {
          "target": "example.com",
          "location_code": 2840,
          "language_code": "en",
          "total_count": 3,
          "items_count": 3,
          "items": [
            {
              "year": 2021,
              "month": 1,
              "metrics": {
                "organic": {
                  "pos_1": 10,
                  "pos_2_3": 20,
                  "pos_4_10": 50,
                  "pos_11_20": 70,
                  "pos_21_30": 40,
                  "pos_31_40": 25,
                  "pos_41_50": 15,
                  "pos_51_60": 10,
                  "pos_61_70": 8,
                  "pos_71_80": 5,
                  "pos_81_90": 3,
                  "pos_91_100": 2,
                  "etv": 12500.5,
                  "impressions_etv": 15800.2,
                  "count": 258,
                  "estimated_paid_traffic_cost": 3200.75,
                  "is_new": 18,
                  "is_up": 32,
                  "is_down": 21,
                  "is_lost": 9
                },
                "paid": {
                  "pos_1": 2,
                  "pos_2_3": 4,
                  "pos_4_10": 8,
                  "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": 850.4,
                  "impressions_etv": 1030.2,
                  "count": 14,
                  "estimated_paid_traffic_cost": 1800.6,
                  "is_new": 3,
                  "is_up": 5,
                  "is_down": 2,
                  "is_lost": 1
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

响应字段

顶层字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	通用状态码。成功时通常为 `20000`。
`status_message`	string	通用状态信息。
`time`	string	请求执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务总数。
`tasks_error`	integer	`tasks` 数组中返回错误的任务数量。
`tasks`	array	任务结果数组。

任务字段

字段	类型	说明
`id`	string	任务唯一标识，UUID 格式。
`status_code`	integer	任务状态码，通常在 `10000` 至 `60000` 范围。
`status_message`	string	任务状态说明。
`time`	string	任务执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量。
`path`	array	请求 API 的路径片段。
`data`	object	请求任务中提交的参数。
`result`	array	任务结果数组。

结果字段

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

`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	基于展示次数估算的自然搜索月流量，通常根据点击率（CTR）与展示次数乘积估算。
`count`	integer	含该域名的自然搜索结果总数。
`estimated_paid_traffic_cost`	float	将预估自然流量通过付费搜索获取时的预估月成本。通常根据自然搜索 `etv` 与付费点击单价（CPC）估算。
`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	基于展示次数估算的付费搜索月流量，根据点击率（CTR）与展示次数估算。
`count`	integer	含该域名的付费搜索结果总数。
`estimated_paid_traffic_cost`	float	基于 `etv` 与 CPC 估算的付费搜索月流量成本。
`is_new`	integer	新发现的排名数量。
`is_up`	integer	排名上升的数量。
`is_down`	integer	排名下降的数量。
`is_lost`	integer	上次检查中存在、但最近一次检查未发现的排名数量。

错误处理

请同时检查以下状态字段：

顶层 status_code；
顶层 status_message；
每个任务中的 status_code；
每个任务中的 status_message；
tasks_error 是否大于 0。

建议客户端针对单个任务分别处理错误，一个任务失败影响同一请求中的任务。完整错误码请参考错误码文档。

实用场景

回溯域名自然排名分布，按月分析在 Top 1、Top 3、Top 10 及更深排名区间的变化，评估 SEO 项目阶段性成果。
监测自然流量趋势，结合 etv 和 impressions_etv 判断流量增长来自搜索量变化还是排名与展示变化。
定位排名波动原因，使用 is_new、is_up、is_down 和 is_lost 统计新增、上升、下降及丢失的排名，排查算法更新或站改版影响。
评估竞品搜索可见度，对多个域名使用相同地区、语言和时间范围进行对比，衡量竞品在自然与付费搜索中的差距。
估算 SEO 流量替代成本，使用 estimated_paid_traffic_cost 估算通过付费搜索获取同等自然流量所需的月度预算，为 SEO 与广告预算分提供依据。

历史排名概览（Legacy） ​

请求信息 ​

计费说明 ​

请求参数 ​

地区与语言参数 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应结构 ​

响应字段 ​

顶层字段 ​

任务字段 ​

结果字段 ​

items 字段 ​

metrics.organic：自然搜索指标 ​

metrics.paid：付费搜索指标 ​

错误处理 ​

实用场景 ​