Google 历史排名概览（实时）

POST /v3/dataforseo_labs/google/historical_rank_overview/live

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

/v3/dataforseo_labs/google/historical_rank_overview/live

接口用于获取指定域名的历史排名与流量数据域名在自然搜索和付费搜索结果中的排名分布、预估月流量及流量价值等指标。

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

请求说明

请求格式：JSON
请求体：JSON 数组，最多 1 个任务
单个 Live 请求只能提交 1 个任务平台限流以认证说明中的 30/60/120 次/分钟规则为准
同时处理的请求数最多为 30 个
支持对返回结果进行数量控制、筛选和排序（本接口当前主要返回指定域名的历史数据）

计费

每次请求均会产生费用。启用 include_clickstream_data=true 时，该请求按标准价格的 2 倍计费。

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

参数	类型	填	说明
`target`	string	是	目标域名。请勿 `https://` 或 `www.`，例如 `example.com`。
`location_name`	string	条件填	地区名。未指定 `location_code` 时填。与 `location_code` 二选一。可通过 `/v3/dataforseo_labs/locations_and_languages` 获取可用地区。示例：`United Kingdom`。
`location_code`	integer	条件填	地区代码。未指定 `location_name` 时填。与 `location_name` 二选一。示例：`2840`。
`language_name`	string	条件填	语言名。未指定 `language_code` 时填。与 `language_code` 二选一。可通过 `/v3/dataforseo_labs/locations_and_languages` 获取可用语言。示例：`English`。
`language_code`	string	条件填	语言代码。未指定 `language_name` 时填。与 `language_name` 二选一。示例：`en`。
`date_from`	string	否	查询时间范围的开始日期。格式为 `yyyy-mm-dd`。未指定时，返回最近 6 个月的数据。最早支持日期为 `2020-10-01`。
`date_to`	string	否	查询时间范围的结束日期。格式为 `yyyy-mm-dd`。未指定时默认使用当前日期。示例：`2021-04-01`。
`correlate`	boolean	否	是否将当前数据与之前获取的数据集进行，以减少数据库变更造成的数据不一致。默认值为 `true`，建议保持为 `true`。
`ignore_synonyms`	boolean	否	是否忽略高度相似的。设置为 `true` 时返回核心数据，不高度相似数据。默认值为 `false`。
`include_clickstream_data`	boolean	否	是否在结果中点击流指标。设置为 `true` 时，返回 `clickstream_etv`、`clickstream_gender_distribution` 和 `clickstream_age_distribution`。默认值为 `false`。历史点击流数据从 `2024-05` 开始提供。启用后请求费用按 2 倍计算。
`tag`	string	否	用户自定义任务标识，用于匹请求与响应结果。最大长度为 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",
      "location_name": "United States",
      "language_name": "English",
      "date_from": "2021-01-01",
      "date_to": "2021-03-29"
    }
  ]'

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

post_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, headers=headers, json=post_data)

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

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

axios
  .post(
    "https://api.seermartech.cn/v3/dataforseo_labs/google/historical_rank_overview/live",
    postData,
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    const result = response.data;

    if (result.status_code === 20000) {
      console.log(result);
    } else {
      console.error(
        `接口错误。错误码：${result.status_code}，错误信息：${result.status_message}`
      );
    }
  })
  .catch((error) => {
    console.error("请求失败：", error.message);
  });

响应结构

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

顶层字段

字段	类型	说明
`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	请求 URL 路径。
`data`	object	创建任务时提交的参数。
`result`	array	任务结果数组。

`result` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型，例如 `google`。
`target`	string	请求中指定的目标域名。
`location_code`	integer	请求中指定的地区代码。
`language_code`	string	请求中指定的语言代码。
`total_count`	integer	数据库中与请求条件匹的结果总数。
`items_count`	integer	`items` 数组中返回的结果数量。
`items`	array	按月份返回的历史排名与流量数据。

`items` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型。
`year`	integer	数据所属年份。
`month`	integer	数据所属月份。
`metrics`	object	指定域名的排名指标。

`metrics.organic`：自然搜索指标

organic 对象域名在自然搜索结果中的排名分布、预估流量及排名变化数据。

排名分布字段

以下字段表示域名出现在相应自然搜索排名区间的 SERP 数量：

字段	类型	说明
`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）与搜索量计算。
`count`	integer	含该域名的自然搜索结果总数。
`estimated_paid_traffic_cost`	float	预估自然流量的付费获取成本。表示通过 Google 搜索广告获取同等月度自然流量所需的估算费用，通常根据自然搜索 `etv` 与付费点击单价（CPC）计算。
`is_new`	integer	新增排名的数量。
`is_up`	integer	排名上升的数量。
`is_down`	integer	排名下降的数量。
`is_lost`	integer	丢失排名的数量，即此前出现在 SERP 中、但最近一次检查时未再发现的。
`clickstream_etv`	integer	基于点击流数据计算的预估流量。只有将 `include_clickstream_data` 设置为 `true` 时才返回。
`clickstream_gender_distribution`	object	点击流指标按性别划分的分布。只有启用 `include_clickstream_data` 时才返回。
`clickstream_age_distribution`	object	点击流指标按年龄划分的分布。只有启用 `include_clickstream_data` 时才返回。

`clickstream_gender_distribution` 字段

字段	类型	说明
`female`	integer	点击流数据集中女性用户数量。
`male`	integer	点击流数据集中男性用户数量。

`clickstream_age_distribution` 字段

字段	类型	说明
`18-24`	integer	18-24 岁用户数量。
`25-34`	integer	25-34 岁用户数量。
`35-44`	integer	35-44 岁用户数量。
`45-54`	integer	45-54 岁用户数量。
`55-64`	integer	55-64 岁用户数量。

`metrics.paid`：付费搜索指标

paid 对象域名在付费搜索结果中的排名分布、预估流量及排名变化数据。

排名分布字段

以下字段表示域名出现在相应付费搜索排名区间的 SERP 数量：

字段	类型	说明
`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）与搜索量计算。
`count`	integer	含该域名的付费搜索结果总数。
`estimated_paid_traffic_cost`	float	预估月度付费搜索流量成本，通常根据 `etv` 与 CPC 数据计算。
`is_new`	integer	新增排名的数量。
`is_up`	integer	排名上升的数量。
`is_down`	integer	排名下降的数量。
`is_lost`	integer	丢失排名的数量，即此前出现在 SERP 中、但最近一次检查时未再发现的。
`clickstream_etv`	integer	基于点击流数据计算的预估流量。只有将 `include_clickstream_data` 设置为 `true` 时才返回。
`clickstream_gender_distribution`	object	点击流指标按性别划分的分布。只有启用 `include_clickstream_data` 时才返回。
`clickstream_age_distribution`	object	点击流指标按年龄划分的分布。只有启用 `include_clickstream_data` 时才返回。

`paid.clickstream_gender_distribution` 字段

字段	类型	说明
`female`	integer	点击流数据集中女性用户数量。
`male`	integer	点击流数据集中男性用户数量。

`paid.clickstream_age_distribution` 字段

字段	类型	说明
`18-24`	integer	18-24 岁用户数量。
`25-34`	integer	25-34 岁用户数量。
`35-44`	integer	35-44 岁用户数量。
`45-54`	integer	45-54 岁用户数量。
`55-64`	integer	55-64 岁用户数量。

响应示例

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": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.3200 sec.",
      "cost": 0.106,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "google",
        "historical_rank_overview",
        "live"
      ],
      "data": {
        "api": "dataforseo_labs",
        "function": "historical_rank_overview",
        "se_type": "google",
        "target": "example.com",
        "language_name": "English",
        "location_code": 2840
      },
      "result": [
        {
          "se_type": "google",
          "target": "example.com",
          "location_code": 2840,
          "language_code": "en",
          "total_count": 3,
          "items_count": 3,
          "items": [
            {
              "se_type": "google",
              "year": 2021,
              "month": 1,
              "metrics": {
                "organic": {
                  "pos_1": 10,
                  "pos_2_3": 25,
                  "pos_4_10": 80,
                  "pos_11_20": 120,
                  "pos_21_30": 90,
                  "pos_31_40": 70,
                  "pos_41_50": 55,
                  "pos_51_60": 40,
                  "pos_61_70": 30,
                  "pos_71_80": 20,
                  "pos_81_90": 15,
                  "pos_91_100": 10,
                  "etv": 12500.5,
                  "count": 565,
                  "estimated_paid_traffic_cost": 18300.2,
                  "is_new": 35,
                  "is_up": 120,
                  "is_down": 80,
                  "is_lost": 15
                },
                "paid": {
                  "pos_1": 2,
                  "pos_2_3": 5,
                  "pos_4_10": 12,
                  "etv": 950.4,
                  "count": 19,
                  "estimated_paid_traffic_cost": 2400.8,
                  "is_new": 3,
                  "is_up": 6,
                  "is_down": 2,
                  "is_lost": 1
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

> 上述数值用于展示响应结构。启用 include_clickstream_data=true 后，organic 和 paid 对象中还可能点击流字段。

错误处理

请根据顶层和任务级别的 status_code、status_message 判断请求是否成功：

顶层 status_code：表示整个请求的处理状态。
任务级 status_code：表示任务的处理状态。
tasks_error：表示返回错误的任务数量。
成功状态码通常为 20000。
客户端应针对网络异常、鉴权失败、参数错误、限流和服务端错误建立重试及异常处理机制。

实用场景

对比域名历史排名分布：按月追踪自然搜索各排名区间的数量，定位 SEO 增长或衰退趋势。
评估流量变化与业务影响：结合 etv 和 estimated_paid_traffic_cost，估算排名波动带来的自然流量及广告替代成本。
监控竞争对手 SEO 表现：批量查询竞争域名在指定国家和语言下的历史排名，支持市场竞争分析。
识别排名增长与流失节点：利用 is_new、is_up、is_down 和 is_lost 定位更新、算法变化或技术改版后的排名变化。
分析搜索受众结构：启用点击流数据后，结合性别和年龄分布评估不同 SEO 或付费搜索流量的受众特征。

Google 历史排名概览（实时） ​

请求说明 ​

计费 ​

请求参数 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

任务字段 ​

result 字段 ​

items 字段 ​

metrics.organic：自然搜索指标 ​

排名分布字段 ​

流量与排名变化字段 ​

clickstream_gender_distribution 字段 ​

clickstream_age_distribution 字段 ​

metrics.paid：付费搜索指标 ​

排名分布字段 ​

流量与排名变化字段 ​

paid.clickstream_gender_distribution 字段 ​

paid.clickstream_age_distribution 字段 ​

响应示例 ​

错误处理 ​

实用场景 ​

Google 历史排名概览（实时）

请求说明

计费

请求参数

请求示例

cURL

Python

TypeScript

响应结构

顶层字段

任务字段

`result` 字段

`items` 字段

`metrics.organic`：自然搜索指标

排名分布字段

流量与排名变化字段

`clickstream_gender_distribution` 字段

`clickstream_age_distribution` 字段

`metrics.paid`：付费搜索指标

排名分布字段

流量与排名变化字段

`paid.clickstream_gender_distribution` 字段

`paid.clickstream_age_distribution` 字段

响应示例

错误处理

实用场景