dataforseo_labs/google/top_searches/live：Google 热门搜索词

POST /v3/dataforseo_labs/google/top_searches/live

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

/v3/dataforseo_labs/google/top_searches/live

本接口可从数据库中获取 Google 热门搜索词，并返回指标、Google Ads 数据、产品类别、搜索意图、SERP 信息及反向链接统计等数据。

接口采用连续分页机制。单次请求最多返回 1000 个；当需要获取 1000 个结果时，请使用响应中的 offset_token 发起后续请求，并通过新的 offset_token 继续获取下一批结果。

计费与请求限制

每次请求均会计费。
启用 include_clickstream_data 后，请求按基础价格的约 2 倍计费。
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
请求体使用 UTF-8 编码的 JSON 格式。
通用 POST 请求体是 JSON 数组，例如：[{ ... }]。
每个 Live API 请求只能一个任务。平台限流以认证说明中的 30/60/120 次/分钟规则为准。
同时发送的请求数量最多为 30 个。

请求参数

参数	类型	填	说明
`location_name`	string	条件填	地理位置完整名称。未指定 `location_code` 时填。`location_name` 与 `location_code` 至少指定一个。示例：`United Kingdom`
`location_code`	integer	条件填	地理位置代码。未指定 `location_name` 时填。可通过 `/v3/dataforseo_labs/locations_and_languages` 获取。示例：`2840`
`language_name`	string	条件填	语言完整名称。未指定 `language_code` 时填。`language_name` 与 `language_code` 至少指定一个。示例：`English`
`language_code`	string	条件填	语言代码。未指定 `language_name` 时填。示例：`en`
`include_serp_info`	boolean	否	是否返回每个的 Google SERP 数据结果数量、 URL 和 SERP 特征。默认值：`false`。
`include_clickstream_data`	boolean	否	是否返回点击流指标。设为 `true` 时，响应会 `clickstream_keyword_info`、`keyword_info_normalized_with_clickstream` 和 `keyword_info_normalized_with_bing`。默认值：`false`。启用后按基础价格约 2 倍计费。
`ignore_synonyms`	boolean	否	是否排除高度相似的。设为 `true` 时返回核心。默认值：`false`。
`filters`	array	否	结果过滤条件。最多设置 8 个过滤条件，条件之间需使用 `and` 或 `or` 连接。
`order_by`	array	否	结果排序规则。最多设置 3 条。支持升序 `asc` 和降序 `desc`，格式为 `字段,方向`。
`tag`	string	否	自定义任务标识，最长 255 个字符。该值会原样返回在响应任务的 `data` 对象中。
`limit`	integer	否	最多返回的数量。默认值和最大值均为 `1000`。
`offset`	integer	否	结果数组的偏移量，默认值为 `0`。例如设置为 `10`，将跳过前 10 个结果。建议用于获取不 10000 个结果。
`offset_token`	string	否	后续请求使用的分页令牌。该值由前一次响应返回。指定此参数后，除 `limit` 外的请求参数将不会参与任务处理。获取 10000 个结果时，建议使用此参数代替 `offset`。

地理位置与语言

可通过以下接口获取可用的地理位置和语言：

/v3/dataforseo_labs/locations_and_languages

过滤器

filters 支持以下运算符：

regex、not_regex、<、<=、>、>=、=、<>、in、not_in、match、not_match、ilike、not_ilike、like、not_like

使用 like、not_like、ilike 或 not_ilike 时，可使用 % 匹零个或多个字符。

过滤器示例：

json

[
  ["keyword", "like", "%seo%"],
  "and",
  ["search_volume", ">", 1000]
]

更多过滤器规则请参考：

/v3/dataforseo_labs/filters

分页说明

使用 `offset`

offset 适合获取不 10000 个结果的场景：

json

[
  {
    "language_code": "en",
    "location_code": 2840,
    "limit": 1000,
    "offset": 1000
  }
]

使用 `offset_token`

当响应中返回 offset_token 时，将复制到下一次请求中：

json

[
  {
    "limit": 1000,
    "offset_token": "下一页响应中的 offset_token"
  }
]

指定 offset_token 后，系统会继续返回初始任务的下一批结果。每次后续请求返回的 offset_token 都是唯一的。

响应字段

顶层响应字段

字段	类型	说明
`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`	array	任务结果数组。

`tasks` 任务字段

字段	类型	说明
`id`	string	任务唯一标识，UUID 格式。
`status_code`	integer	任务状态码。
`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	请求中的语言代码。
`total_count`	integer	数据库中符合请求条件的结果总数。
`items_count`	integer	本次 `items` 数组返回的结果数量。
`offset`	integer	当前结果偏移量。
`offset_token`	string	获取下一批结果所需的分页令牌。
`items`	array	及数据。

`items` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型。
`keyword`	string	。
`location_code`	integer	地理位置代码。
`language_code`	string	语言代码。
`keyword_info`	object	Google Ads 指标。
`clickstream_keyword_info`	object	点击流指标。在 `include_clickstream_data=true` 时返回。
`keyword_properties`	object	附加属性。
`serp_info`	object	Google SERP 数据。在 `include_serp_info=true` 且存在数据时返回，否则为 `null`。
`avg_backlinks_info`	object	排名前 10 的自然结果页面的平均反向链接数据。
`search_intent_info`	object	搜索意图。
`keyword_info_normalized_with_bing`	object	使用 Bing 搜索量归一化后的数据。
`keyword_info_normalized_with_clickstream`	object	使用点击流数据归一化后的数据。

`keyword_info` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型。
`last_updated_time`	string	数据更新时间，UTC 格式：`yyyy-mm-dd hh:mm:ss +00:00`。
`competition`	float	竞争度，取值范围为 0 至 1，数据来源于 Google Ads。
`competition_level`	string	付费搜索结果中的竞争等级，可选值：`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`	array	过去 12 个月的月度搜索量。
`search_volume_trend`	object	搜索量变化趋势。
`search_volume_trend.monthly`	integer	相比上个月的搜索量变化百分比。
`search_volume_trend.quarterly`	integer	相比上一季度的搜索量变化百分比。
`search_volume_trend.yearly`	integer	相比上一年的搜索量变化百分比。

monthly_searches 数组中的：

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

`clickstream_keyword_info` 字段

当请求参数 include_clickstream_data 设置为 true 时返回。

字段	类型	说明
`search_volume`	integer	基于点击流数据计算的月均搜索量。
`last_updated_time`	string	点击流数据集更新时间。
`gender_distribution`	object	按性别划分的点击流指标估算分布。
`gender_distribution.female`	integer	点击流数据中的女性用户数量。
`gender_distribution.male`	integer	点击流数据中的男性用户数量。
`age_distribution`	object	按年龄划分的点击流指标估算分布。
`age_distribution.18-24`	integer	18—24 岁用户数量。
`age_distribution.25-34`	integer	25—34 岁用户数量。
`age_distribution.35-44`	integer	35—44 岁用户数量。
`age_distribution.45-54`	integer	45—54 岁用户数量。
`age_distribution.55-64`	integer	55—64 岁用户数量。
`monthly_searches`	array	按月份统计的点击流搜索量。

`keyword_properties` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型。
`core_keyword`	string	同义词分组中的核心。无法识别同义词时为 `null`。
`synonym_clustering_algorithm`	string	同义词聚类算法。可选值：`keyword_metrics`、`text_processing`；无法识别时为 `null`。
`keyword_difficulty`	integer	难度，表示自然搜索结果前 10 名的难度，取值范围为 0—100。
`detected_language`	string	系统识别出的语言。
`is_another_language`	boolean	识别语言是否不同于请求中指定的语言。
`words_count`	integer	的单词数量。

`serp_info` 字段

当 include_serp_info=true 时请求 SERP 数据。没有对应 SERP 数据时，该字段为 null。

字段	类型	说明
`se_type`	string	搜索引擎类型。
`check_url`	string	可直接访问的搜索结果 URL，可用于校验返回结果。
`serp_item_types`	array	SERP 中出现的结果类型。
`se_results_count`	integer	该对应的搜索结果数量。
`last_updated_time`	string	SERP 数据更新时间。

支持的 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` 字段

该对象提供 Google 自然搜索结果前 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	反向链接数据更新时间。

`search_intent_info` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型，目前为 `google`。
`main_intent`	string	主要搜索意图。可选值：`informational`、`navigational`、`commercial`、`transactional`。
`foreign_intent`	array	助搜索意图，取值同 `main_intent`。
`last_updated_time`	string	搜索意图数据更新时间。

归一化数据

`keyword_info_normalized_with_bing`

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

`keyword_info_normalized_with_clickstream`

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

两个 monthly_searches 数组中的均：

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

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/dataforseo_labs/google/top_searches/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "language_name": "English",
      "location_code": 2840,
      "limit": 3
    }
  ]'

Python

python

import requests

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

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

post_data = [
    {
        "location_name": "United States",
        "language_name": "English",
        "limit": 3,
    }
]

response = requests.post(url, headers=headers, json=post_data)
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/google/top_searches/live",
  [
    {
      language_name: "English",
      location_code: 2840,
      limit: 3,
    },
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
  },
);

console.log(response.data);

响应示例

以下示例展示主要响应结构，返回的 items 字段会根据请求参数和数据可用性更多结果。

json

{
  "version": "0.1.20240801",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.5228 sec.",
  "cost": 0.0103,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.5000 sec.",
      "cost": 0.0103,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "google",
        "top_searches",
        "live"
      ],
      "data": {
        "api": "dataforseo_labs",
        "function": "top_searches",
        "se_type": "google",
        "language_name": "English",
        "location_code": 2840,
        "limit": 3
      },
      "result": [
        {
          "se_type": "google",
          "location_code": 2840,
          "language_code": "en",
          "total_count": 1000000,
          "items_count": 3,
          "offset": 0,
          "offset_token": "下一页分页令牌",
          "items": [
            {
              "se_type": "google",
              "keyword": "example keyword",
              "location_code": 2840,
              "language_code": "en",
              "keyword_info": {
                "se_type": "google",
                "last_updated_time": "2024-08-12 02:02:19 +00:00",
                "competition": 0.01,
                "competition_level": "LOW",
                "cpc": 0.03,
                "search_volume": 151000000,
                "low_top_of_page_bid": 0.01,
                "high_top_of_page_bid": 0.01,
                "categories": [],
                "monthly_searches": [],
                "search_volume_trend": {
                  "monthly": 22,
                  "quarterly": 22,
                  "yearly": 0
                }
              },
              "clickstream_keyword_info": null,
              "keyword_properties": {
                "se_type": "google",
                "core_keyword": null,
                "synonym_clustering_algorithm": "text_processing",
                "keyword_difficulty": 16,
                "detected_language": null,
                "is_another_language": true,
                "words_count": 2
              },
              "serp_info": null,
              "avg_backlinks_info": {
                "se_type": "google",
                "backlinks": 830563.6,
                "dofollow": 171603.2,
                "referring_pages": 647749.9,
                "referring_domains": 734.1,
                "referring_main_domains": 569.2,
                "rank": 188.8,
                "main_domain_rank": 711.4,
                "last_updated_time": "2024-08-04 08:23:20 +00:00"
              },
              "search_intent_info": {
                "se_type": "google",
                "main_intent": "navigational",
                "foreign_intent": null,
                "last_updated_time": "2023-08-31 20:30:38 +00:00"
              },
              "keyword_info_normalized_with_bing": {
                "last_updated_time": "2024-08-08 02:39:41 +00:00",
                "search_volume": 185000000,
                "is_normalized": true,
                "monthly_searches": []
              },
              "keyword_info_normalized_with_clickstream": {
                "last_updated_time": "2024-08-08 02:39:41 +00:00",
                "search_volume": 185000000,
                "is_normalized": true,
                "monthly_searches": []
              }
            }
          ]
        }
      ]
    }
  ]
}

状态码与错误处理

请根据顶层 status_code 和任务级 status_code 判断请求是否成功。成功状态码通常为 20000。应用程序应同时检查：

tasks_error 是否大于 0；
tasks[].status_code 是否为成功状态；
tasks[].status_message 是否错误说明；
result 是否存在以及是否预期的 items 数据。

完整错误码请参考：

/v3/appendix/errors

实用场景

挖掘指定国家和语言下的热门搜索词：批量获取市场热门，为 SEO规划和落地页选题提供数据依据。
筛选高搜索量、低竞争度：结合 filters、search_volume 和 competition_level 过滤结果，提升拓展效率和自然排名机会。
分析的搜索趋势变化：利用 monthly_searches 和 search_volume_trend 识别季节性需求，为发布、促销活动和预算安排提供参考。
评估的 SERP 竞争环境：启用 include_serp_info 获取 SERP 特征，并结合 avg_backlinks_info 判断自然结果前 10 名所需的竞争强度。
识别用户搜索意图与人群特征：结合 search_intent_info、gender_distribution 和 age_distribution 细分用户，支持类型选择和投放人群定位。

dataforseo_labs/google/top_searches/live：Google 热门搜索词 ​

计费与请求限制 ​

请求参数 ​

地理位置与语言 ​

过滤器 ​

分页说明 ​

使用 offset ​

使用 offset_token ​

响应字段 ​

顶层响应字段 ​

tasks 任务字段 ​

result 字段 ​

items 字段 ​

keyword_info 字段 ​

clickstream_keyword_info 字段 ​

keyword_properties 字段 ​

serp_info 字段 ​

avg_backlinks_info 字段 ​

search_intent_info 字段 ​

归一化数据 ​

keyword_info_normalized_with_bing ​

keyword_info_normalized_with_clickstream ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

状态码与错误处理 ​

实用场景 ​

dataforseo_labs/google/top_searches/live：Google 热门搜索词

计费与请求限制

请求参数

地理位置与语言

过滤器

分页说明

使用 `offset`

使用 `offset_token`

响应字段

顶层响应字段

`tasks` 任务字段

`result` 字段

`items` 字段

`keyword_info` 字段

`clickstream_keyword_info` 字段

`keyword_properties` 字段

`serp_info` 字段

`avg_backlinks_info` 字段

`search_intent_info` 字段

归一化数据

`keyword_info_normalized_with_bing`

`keyword_info_normalized_with_clickstream`

请求示例

cURL

Python

TypeScript

响应示例

状态码与错误处理

实用场景