Google 历史批量流量预估

POST /v3/dataforseo_labs/google/historical_bulk_traffic_estimation/live

接口说明

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

本接口用于批量获取最多 1,000 个域名或子域名在指定时间范围的历史月度流量预估数据，历史数据最早可追溯至 2020-10-01。如果未指定时间范围，默认返回最近 12 个月的数据。

返回结果会分别提供以下搜索结果类型的流量预估：

自然搜索（organic）
付费搜索（paid）
精选摘要（featured_snippet）
本地（local_pack）

流量预估值（ETV）根据域名排名的搜索量与点击率（CTR）计算得出：

> 预估流量 = 搜索量 × 点击率（CTR）

每次 Live API 请求只能提交 1 个任务，但一个任务最多可 1,000 个域名。接口支持每分钟最多 2,000 次 API 调用，同时发送的请求数最多为 30。

所有 POST 请求使用 UTF-8 编码的 JSON 格式，且请求体是 JSON 数组。

计费说明

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

请求参数

参数	类型	填	说明
`targets`	array	是	目标域名或子域名列表。域名中不得 `https://` 和 `www.`，最多支持 1,000 个。
`location_name`	string	否	地区称。设置该字段后无需设置 `location_code`。例如：`United Kingdom`。不设置时返回所有可用地区的数据。
`location_code`	integer	否	地区代码。设置该字段后无需设置 `location_name`。例如：`2840`。不设置时返回所有可用地区的数据。
`language_name`	string	否	语言称。设置该字段后无需设置 `language_code`。例如：`English`。不设置时返回所有可用语言的数据。
`language_code`	string	否	语言代码。设置该字段后无需设置 `language_name`。例如：`en`。不设置时返回所有可用语言的数据。
`date_from`	string	否	数据起始日期，格式为 `yyyy-mm-dd`。最早支持 `2020-10-01`。未设置时默认查询最近 12 个月。
`date_to`	string	否	数据结束日期，格式为 `yyyy-mm-dd`。未设置时默认使用当前日期。
`ignore_synonyms`	boolean	否	是否忽略高度相似的。设置为 `true` 时返回核心数据；默认值为 `false`。
`item_types`	array	否	指定返回的搜索结果类型。可选值：`organic`、`paid`、`featured_snippet`、`local_pack`。如果数组中 `organic` 以外的类型，结果将数组中的第一个类型排序。
`tag`	string	否	自定义任务标识，最长 255 个字符。可用于任务与响应结果。提交的值会原样返回在响应的 `data` 对象中。

地区与语言代码

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

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

location_name 与 location_code 二选一；language_name 与 language_code 二选一。

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/dataforseo_labs/google/historical_bulk_traffic_estimation/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "targets": [
        "example.com",
        "cnn.com",
        "forbes.com"
      ],
      "location_code": 2840,
      "language_code": "en",
      "date_from": "2021-01-01",
      "date_to": "2021-03-29",
      "item_types": [
        "organic",
        "paid"
      ]
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/google/historical_bulk_traffic_estimation/live"

headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
}

payload = [
    {
        "targets": [
            "example.com",
            "cnn.com",
            "forbes.com",
        ],
        "location_name": "United States",
        "language_name": "English",
        "date_from": "2021-01-01",
        "date_to": "2021-03-29",
        "item_types": [
            "organic",
            "paid",
        ],
    }
]

response = requests.post(url, headers=headers, json=payload)
result = response.json()

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

TypeScript

typescript

import axios from "axios";

const payload = [
  {
    targets: ["example.com", "cnn.com", "forbes.com"],
    location_code: 2840,
    language_code: "en",
    date_from: "2021-01-01",
    date_to: "2021-03-29",
    item_types: ["organic", "paid"],
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/dataforseo_labs/google/historical_bulk_traffic_estimation/live",
    payload,
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.error(error.response?.data || 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	请求路径信息。
`data`	object	请求中提交的任务参数。
`result`	array	任务结果数组。

`data` 字段

data 对象会请求中提交的主要参数，例如：

json

{
  "api": "dataforseo_labs",
  "function": "historical_bulk_traffic_estimation",
  "se_type": "google",
  "targets": [
    "example.com"
  ],
  "location_code": 2840,
  "language_code": "en",
  "date_from": "2021-01-01",
  "date_to": "2021-03-29",
  "item_types": [
    "organic",
    "paid"
  ]
}

`result` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型，通常为 `google`。
`location_code`	integer	请求中指定的地区代码。无可用数据时为 `null`。
`language_code`	string	请求中指定的语言代码。无可用数据时为 `null`。
`total_count`	integer	与请求条件匹的数据库结果总数。
`items_count`	integer	当前响应中 `items` 数组返回的结果数量。
`items`	array	域名流量预估结果数组。

`items` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型。
`target`	string	请求中的目标域名或子域名。
`metrics`	object	目标域名的流量预估数据。

`metrics` 字段

metrics 对象根据 item_types 返回以下一个或多个数组：

organic：自然搜索流量数据
paid：付费搜索流量数据
featured_snippet：Google 搜索结果精选摘要流量数据
local_pack：搜索结果本地流量数据

每个数据数组中的字段如下：

字段	类型	说明
`year`	integer	数据所属年份。
`month`	integer	数据所属月份。
`etv`	float	预估月度流量。该值根据目标域名排名的搜索量和 CTR 计算。
`count`	integer	对应搜索结果类型中该域名的结果数量。

不同类型中 count 的含义如下：

organic.count：该域名的自然搜索结果数量。
paid.count：该域名的付费搜索结果数量。
featured_snippet.count：该域名的精选摘要条目数量。
local_pack.count：该域名的本地条目数量。

如果请求的结果类型没有数据，对应字段可能返回 null。

响应示例

json

{
  "version": "0.1.20230705",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.1397 sec.",
  "cost": 0.103,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1200 sec.",
      "cost": 0.103,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "google",
        "historical_bulk_traffic_estimation",
        "live"
      ],
      "data": {
        "api": "dataforseo_labs",
        "function": "historical_bulk_traffic_estimation",
        "se_type": "google",
        "targets": [
          "example.com",
          "cnn.com",
          "forbes.com"
        ],
        "location_code": 2840,
        "language_code": "en",
        "date_from": "2021-01-01",
        "date_to": "2021-03-29",
        "item_types": [
          "organic",
          "paid"
        ]
      },
      "result": [
        {
          "se_type": "google",
          "location_code": 2840,
          "language_code": "en",
          "total_count": 3,
          "items_count": 3,
          "items": [
            {
              "se_type": "google",
              "target": "example.com",
              "metrics": {
                "organic": [
                  {
                    "year": 2021,
                    "month": 1,
                    "etv": 12500.5,
                    "count": 830
                  }
                ],
                "paid": [
                  {
                    "year": 2021,
                    "month": 1,
                    "etv": 320.2,
                    "count": 24
                  }
                ],
                "featured_snippet": null,
                "local_pack": null
              }
            },
            {
              "se_type": "google",
              "target": "cnn.com",
              "metrics": {
                "organic": [],
                "paid": [],
                "featured_snippet": null,
                "local_pack": null
              }
            },
            {
              "se_type": "google",
              "target": "forbes.com",
              "metrics": {
                "organic": [],
                "paid": [],
                "featured_snippet": null,
                "local_pack": null
              }
            }
          ]
        }
      ]
    }
  ]
}

状态码与错误处理

请根据 status_code 和 status_message 判断请求及任务是否成功：

顶层 status_code：表示整个 API 请求的处理状态。
任务级 status_code：表示任务的处理状态。
tasks_error：用于快速判断是否存在任务处理错误。

建议客户端对网络异常、参数错误、鉴权失败、频率限制和服务端错误进行统一处理，并记录任务 id、状态码及状态信息，便于后续排查。

实用场景

对比多个竞品域名的历史自然流量，识别不同市场和时间段的 SEO 增长趋势，为竞品研究和预算分提供依据。
拆分分析自然搜索与付费搜索流量，评估品牌在 SEO 和搜索广告之间的流量贡献，制定渠道组合策略。
监测精选摘要和本地的历史流量变化，发现 SERP 特殊展现机会，指导结构优化和本地 SEO 投。
批量评估客户或站群域名的流量表现，快速生成月度 SEO 报告，减少逐域名查询和数据整理成本。
结合地区与语言维度分析域名表现，定位不同国家或语种市场的流量增长空间，为化 SEO 规划提供数据支持。

Google 历史批量流量预估 ​

接口说明 ​

计费说明 ​

请求参数 ​

地区与语言代码 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

任务字段 ​

data 字段 ​

result 字段 ​

items 字段 ​

metrics 字段 ​

响应示例 ​

状态码与错误处理 ​

实用场景 ​