Google 概览（实时）

POST /v3/dataforseo_labs/google/keyword_overview/live

本接口使用 POST /v3/dataforseo_labs/google/keyword_overview/live 获取指定的 Google 数据。响应当前每次点击费用（CPC）、付费搜索竞争度、搜索量、搜索意图、近 12 个月月度搜索量，以及 SERP 和外链信息。

通过设置 include_clickstream_data，还可以获取点击流指标，例如点击流搜索量、性别分布和年龄分布。

返回结果取决于、地区和语言的组合。可用地区与语言列表请通过以下接口查询：

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

**数据来源：**平台数据库。
指标基于 Google Ads 数据。数据源完成更新后，本平台通常每月更新一次指标。由于 Google 可能重新调整某个月份的搜索量，本接口也会同步更新对应数据。

请求信息

请求方法：POST
请求路径：/v3/dataforseo_labs/google/keyword_overview/live
完整 URL：https://api.seermartech.cn/v3/dataforseo_labs/google/keyword_overview/live
**请求格式：**JSON（UTF-8）
**请求体格式：**JSON 数组
**单次调用：**每个 Live API 请求只能 1 个任务平台限流以认证说明中的 30/60/120 次/分钟规则为准
**并发限制：**最多同时发送 30 个请求

计费说明

每次请求单独计费。启用 include_clickstream_data: true 时，请求费用按基础费用的 2 倍计算。

参考价约 ¥0.145 / 次；启用点击流数据时，参考价约 ¥0.290 / 次。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

每个请求体是数组，并且数组中只能一个任务对象。

参数	类型	填	说明
`keywords`	array	是	要查询的列表。最多 700 个；每个最多 80 个字符、最多 10 个单词。会被转换为小写，并在结果中以独立数组返回。若某些未出现在结果中，表示数据库中没有对应数据；未返回的不计费。
`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`。
`include_serp_info`	boolean	否	是否返回每个的 SERP 数据结果数量、检查 URL 和 SERP 特征。默认值：`false`。
`include_clickstream_data`	boolean	否	是否返回点击流指标。设为 `true` 时，将返回 `clickstream_keyword_info`、`keyword_info_normalized_with_clickstream` 和 `keyword_info_normalized_with_bing`。默认值：`false`。启用后按双倍费用计费。
`tag`	string	否	用户自定义任务标识，最多 255 个字符。可用于请求和响应，指定的值会在响应的 `data` 对象中返回。

规则和限制请以参考文档为准。

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/dataforseo_labs/google/keyword_overview/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "keywords": ["iphone", "iphone 16"],
      "location_name": "United States",
      "language_name": "English",
      "include_serp_info": true,
      "include_clickstream_data": true,
      "tag": "keyword-overview-demo"
    }
  ]'

Python

python

import requests

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

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

payload = [
    {
        "keywords": ["iphone"],
        "location_name": "United States",
        "language_name": "English",
        "include_serp_info": True,
    }
]

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

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        f"请求失败，状态码：{result.get('status_code')}，"
        f"信息：{result.get('status_message')}"
    )

TypeScript

typescript

import axios from "axios";

const response = await axios.post(
  "https://api.seermartech.cn/v3/dataforseo_labs/google/keyword_overview/live",
  [
    {
      keywords: ["iphone"],
      location_name: "United States",
      language_name: "English",
      include_serp_info: true,
    },
  ],
  {
    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 数组。

顶层字段

字段	类型	说明
`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`。
`location_code`	integer	请求中的地区代码。
`language_code`	string	请求中的语言代码。
`items_count`	integer	`items` 数组中的结果数量。
`items`	array	及数据。

`items` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型。
`keyword`	string	返回的。经过 URL 解码后，`+` 会被解码为空格。
`location_code`	integer / null	请求中的地区代码。没有对应数据时为 `null`。
`language_code`	string	请求中的语言代码。
`search_partners`	boolean	是否 Google 合作伙伴网站的数据。为 `true` 时， Google 及合作伙伴搜索网络；为 `false` 时 Google 搜索网站数据。
`keyword_info`	object	基础指标。
`keyword_info_normalized_with_bing`	object	使用 Bing 搜索量归一化后的指标。
`keyword_info_normalized_with_clickstream`	object	使用点击流数据归一化后的指标。
`clickstream_keyword_info`	object	点击流指标在 `include_clickstream_data` 为 `true` 时返回。
`keyword_properties`	object	属性信息。
`serp_info`	object / null	SERP 数据。未启用 `include_serp_info` 或数据库中没有对应 SERP 数据时为 `null`。
`avg_backlinks_info`	object	该自然排名前 10 个网站的平均外链指标。
`search_intent_info`	object	搜索意图信息。

`keyword_info` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型。
`last_updated_time`	string	数据更新时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`。
`competition`	float	竞争度，基于 Google Ads 数据，取值范围为 `0` 至 `1`。
`competition_level`	string / null	付费 SERP 中的竞争等级。可选值：`LOW`、`MEDIUM`、`HIGH`；未知时为 `null`。
`cpc`	float	历史平均每次点击费用。
`search_volume`	integer	平均月搜索量，表示 Google 中该的大致搜索次数。
`low_top_of_page_bid`	float	广告出现在首页顶部位置所需的最低出价估计值，通常高于约 20% 的最低展示出价。
`high_top_of_page_bid`	float	广告出现在首页顶部位置所需的最高出价估计值，通常高于约 80% 的最低展示出价。
`categories`	array	产品和服务类别。

出价数据会根据请求中的地区不同而变化。

`monthly_searches` 字段

keyword_info.monthly_searches 为近 12 个月的月度搜索量数组。

字段	类型	说明
`year`	integer	年份。
`month`	integer	月份。
`search_volume`	integer	该月份的平均搜索量。

`search_volume_trend` 字段

表示搜索量相对于不同历史周期的变化百分比。

字段	类型	说明
`monthly`	integer	相比上个月的变化百分比。
`quarterly`	integer	相比上一季度的变化百分比。
`yearly`	integer	相比上一年的变化百分比。

归一化指标

`keyword_info_normalized_with_bing`

在 include_clickstream_data 为 true 时返回。

字段	类型	说明
`last_updated_time`	string	数据集更新时间，UTC 格式。
`search_volume`	integer	使用 Bing 搜索量归一化后的当前搜索量。
`is_normalized`	boolean	是否已使用 Bing 数据进行归一化。
`monthly_searches`	array	归一化后的月度搜索量。

monthly_searches 中的对象：

字段	类型	说明
`year`	integer	年份。
`month`	integer	月份。
`search_volume`	integer	对应月份的搜索量。

`keyword_info_normalized_with_clickstream`

在 include_clickstream_data 为 true 时返回。

字段	类型	说明
`last_updated_time`	string	数据集更新时间，UTC 格式。
`search_volume`	integer	使用点击流数据归一化后的当前搜索量。
`is_normalized`	boolean	是否已使用点击流数据进行归一化。
`monthly_searches`	array	归一化后的月度搜索量。

monthly_searches 中的对象：

字段	类型	说明
`year`	integer	年份。
`month`	integer	月份。
`search_volume`	integer	对应月份的搜索量。

`clickstream_keyword_info` 字段

在请求参数 include_clickstream_data 为 true 时返回。

字段	类型	说明
`search_volume`	integer	月均点击流搜索量。
`last_updated_time`	string	点击流数据集更新时间，UTC 格式。
`gender_distribution`	object	基于点击流估算的性别分布。
`age_distribution`	object	基于点击流估算的年龄分布。
`monthly_searches`	array	月度点击流搜索量。

`gender_distribution`

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

`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 岁用户指标。

点击流 `monthly_searches`

字段	类型	说明
`year`	integer	年份。
`month`	integer	月份。
`search_volume`	integer	对应月份的点击流搜索量。

`keyword_properties` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型。
`core_keyword`	string / null	同义词分组中的核心。为 `null` 时，表示数据库未识别出与该同义的核心词。
`synonym_clustering_algorithm`	string / null	同义词聚类算法。可选值：`keyword_metrics`（基于指标）、`text_processing`（基于文本处理）。
`keyword_difficulty`	integer	自然搜索前 10 名的难度，取值范围为 `0` 至 `100`。该指标会分析 SERP 前 10 个页面的链接特征等因素。
`detected_language`	string	系统识别出的语言。
`is_another_language`	boolean	识别语言是否与请求设置的语言不同。为 `true` 时表示不一致。

`serp_info` 字段

当未设置 include_serp_info: true，或数据库中没有该的 SERP 数据时，serp_info 为 null。

字段	类型	说明
`se_type`	string	搜索引擎类型。
`check_url`	string	对应搜索结果页的直接 URL，可用于核验结果。
`serp_item_types`	array	SERP 中发现的结果类型。
`se_results_count`	string	该的搜索结果数量。
`last_updated_time`	string	SERP 数据更新时间，UTC 格式。
`previous_updated_time`	string	上一次 SERP 数据更新时间，UTC 格式。

serp_item_types 可能以下值：

answer_box、app、carousel、multi_carousel、featured_snippet、google_flights、google_reviews、third_party_reviews、google_posts、images、jobs、knowledge_graph、local_pack、hotels_pack、map、organic、paid、people_also_ask、related_searches、people_also_search、shopping、top_stories、twitter、video、events、mention_carousel、recipes、top_sights、scholarly_articles、popular_products、podcasts、questions_and_answers、find_results_on、stocks_box、visual_stories、commercial_units、local_services、google_hotels、math_solver、currency_box、product_considerations、found_on_web、short_videos、refine_products、explore_brands、perspectives、discussions_and_forums、compare_sites、courses、ai_overview。

结果数据会针对以下返回：

organic
paid
featured_snippet
local_pack

`avg_backlinks_info` 字段

该对象提供自然排名前 10 个网站的平均外链、引用页面、引用域名及排名指标。

字段	类型	说明
`se_type`	string	搜索引擎类型。
`backlinks`	float	平均外链数量。
`dofollow`	float	平均 Dofollow 链接数量。
`referring_pages`	float	平均引用页面数量。
`referring_domains`	float	平均引用域名数量。
`referring_main_domains`	float	平均引用主域名数量。
`rank`	float	平均排名值。
`main_domain_rank`	float	平均主域名排名值。
`last_updated_time`	string	外链数据更新时间，UTC 格式。

`search_intent_info` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型，可能为 `google`。
`main_intent`	string	主要搜索意图。可选值：`informational`（信息型）、`navigational`（导航型）、`commercial`（商业调查型）、`transactional`（交易型）。
`foreign_intent`	array / null	补搜索意图，取值范围同 `main_intent`。
`last_updated_time`	string	搜索意图数据更新时间，UTC 格式。

响应示例

json

{
  "version": "0.1.20241227",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.1845 sec.",
  "cost": 0.145,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1600 sec.",
      "cost": 0.145,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "google",
        "keyword_overview",
        "live"
      ],
      "data": {
        "api": "dataforseo_labs",
        "function": "keyword_overview",
        "se_type": "google",
        "language_code": "en",
        "location_code": 2840,
        "include_clickstream_data": true,
        "include_serp_info": true,
        "keywords": ["iphone"]
      },
      "result": [
        {
          "se_type": "google",
          "location_code": 2840,
          "language_code": "en",
          "items_count": 1,
          "items": [
            {
              "se_type": "google",
              "keyword": "iphone",
              "location_code": 2840,
              "language_code": "en",
              "search_partners": false,
              "keyword_info": {
                "se_type": "google",
                "last_updated_time": "2025-02-15 06:43:28 +00:00",
                "competition": 1,
                "competition_level": "HIGH",
                "cpc": 1.25,
                "search_volume": 368000,
                "low_top_of_page_bid": 0.85,
                "high_top_of_page_bid": 2.4,
                "categories": [10001],
                "monthly_searches": [
                  {
                    "year": 2025,
                    "month": 2,
                    "search_volume": 368000
                  }
                ],
                "search_volume_trend": {
                  "monthly": 0,
                  "quarterly": -19,
                  "yearly": 22
                }
              },
              "keyword_info_normalized_with_bing": {
                "last_updated_time": "2025-02-15 06:43:28 +00:00",
                "search_volume": 600417,
                "is_normalized": true,
                "monthly_searches": []
              },
              "keyword_info_normalized_with_clickstream": {
                "last_updated_time": "2025-02-15 06:43:28 +00:00",
                "search_volume": 1176877,
                "is_normalized": true,
                "monthly_searches": []
              },
              "clickstream_keyword_info": {
                "search_volume": 737851,
                "last_updated_time": "2025-01-04 00:08:42 +00:00",
                "gender_distribution": {
                  "female": 51,
                  "male": 49
                },
                "age_distribution": {
                  "18-24": 22,
                  "25-34": 19,
                  "35-44": 25,
                  "45-54": 32,
                  "55-64": 2
                },
                "monthly_searches": []
              },
              "keyword_properties": {
                "se_type": "google",
                "core_keyword": null,
                "synonym_clustering_algorithm": "text_processing",
                "keyword_difficulty": 89,
                "detected_language": "en",
                "is_another_language": false
              },
              "serp_info": {
                "se_type": "google",
                "check_url": "https://www.google.com/search?q=iphone&num=100&hl=en&gl=US",
                "serp_item_types": [
                  "organic",
                  "paid",
                  "images",
                  "people_also_ask"
                ],
                "se_results_count": "13380000000",
                "last_updated_time": "2025-02-26 21:10:59 +00:00",
                "previous_updated_time": "2025-01-16 07:38:29 +00:00"
              },
              "avg_backlinks_info": {
                "se_type": "google",
                "backlinks": 1333333.7,
                "dofollow": 1048624.3,
                "referring_pages": 1077104.1,
                "referring_domains": 9109.9,
                "referring_main_domains": 8417.2,
                "rank": 415.6,
                "main_domain_rank": 818.7,
                "last_updated_time": "2025-02-26 19:11:00 +00:00"
              },
              "search_intent_info": {
                "se_type": "google",
                "main_intent": "informational",
                "foreign_intent": null,
                "last_updated_time": "2023-02-28 15:25:15 +00:00"
              }
            }
          ]
        }
      ]
    }
  ]
}

错误处理

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

顶层 status_code 表示整个 API 请求的处理状态。
tasks[].status_code 表示任务的处理状态。
tasks_error 表示失败任务数量。
成功响应通常使用状态码 20000。
建议在客户端实现完整的异常处理、时重试和错误记录机制。

完整错误码请参考错误码文档。

实用场景

评估竞争度与点击成本，筛选更商业价值的 SEO 和投放词。
比较不同地区和语言的搜索量，制定本地化与海外市场扩张策略。
分析近 12 个月搜索趋势，识别季节性需求并安排发布节奏。
结合 SERP 特征和前 10 名页面的平均外链数据，判断自然排名的难度。
启用点击流指标，分析受众的年龄与性别分布，优化定位和广告人群策略。

Google 概览（实时） ​

请求信息 ​

计费说明 ​

请求参数 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

任务字段 ​

result 字段 ​

items 字段 ​

keyword_info 字段 ​

monthly_searches 字段 ​

search_volume_trend 字段 ​

归一化指标 ​

keyword_info_normalized_with_bing ​

keyword_info_normalized_with_clickstream ​

clickstream_keyword_info 字段 ​

gender_distribution ​

age_distribution ​

点击流 monthly_searches ​

keyword_properties 字段 ​

serp_info 字段 ​

avg_backlinks_info 字段 ​

search_intent_info 字段 ​

响应示例 ​

错误处理 ​

实用场景 ​