Google 热门搜索词实时查询

接口说明

Top Searches 接口用于从平台数据库中获取海量热门搜索词数据。返回的每个都附带一组指标：

Google Ads 竞价指标
产品分类
Google SERP 数据
难度
外链均值信息
搜索意图
归一化搜索量数据

该接口的调用机制与常规查询略有不同：单次请求最多返回 1000 个。如果需要获取 1000 条结果，应在首次请求中提交完整参数（如 limit、语言、地区等），然后使用响应中返回的 offset_token 发起后续请求，逐批获取下一组结果。通过连续请求，可以逐步导出所需的大规模数据。

请求地址

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

计费说明

本接口按请求计费。

由于参考文档未给出固定单价，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

调用限制

POST 数据使用 JSON（UTF-8 编码）
请求体格式为 JSON 数组：[{ ... }]
每分钟最多可发送 2000 次 API 调用
最大并发请求数为 30

分页与批量获取机制

单次最多返回 1000 条结果
若需获取 1000 条数据，使用响应中的 offset_token 继续请求
offset_token 适用于获取 10000 条结果的场景，可时
如果请求中传 offset_token，则除 limit 外余参数都会被忽略
offset 更适合在小规模分页（建议不 10000 条）时使用

请求参数

任务参数说明

字段名	类型	说明
`location_name`	string	地区名。未传 `location_code` 时填。`location_name` 与 `location_code` 二选一。可通过 `/v3/dataforseo_labs/locations_and_languages` 获取可用地区列表。示例：`United Kingdom`
`location_code`	integer	地区编码。未传 `location_name` 时填。`location_name` 与 `location_code` 二选一。可通过 `/v3/dataforseo_labs/locations_and_languages` 获取可用地区编码。示例：`2840`
`language_name`	string	语言名。未传 `language_code` 时填。`language_name` 与 `language_code` 二选一。可通过 `/v3/dataforseo_labs/locations_and_languages` 获取可用语言列表。示例：`English`
`language_code`	string	语言代码。未传 `language_name` 时填。`language_name` 与 `language_code` 二选一。可通过 `/v3/dataforseo_labs/locations_and_languages` 获取可用语言代码。示例：`en`
`include_serp_info`	boolean	是否为每个返回 SERP 数据。可选。设为 `true` 后，将返回 `serp_info` 数组，搜索结果数量、 URL、SERP 特征等。默认：`false`
`include_clickstream_data`	boolean	是否返回基于点击流的指标。可选。设为 `true` 后，将返回 `clickstream_keyword_info`、`keyword_info_normalized_with_clickstream`、`keyword_info_normalized_with_bing`。默认：`false`。启用后请求价格翻倍，扣费以响应头 `X-SeerMarTech-Charge-CNY` 为准
`ignore_synonyms`	boolean	是否忽略高度相似。可选。设为 `true` 时返回核心，排除高度相似词。默认：`false`
`filters`	array	结果过滤条件数组。可选。最多支持 `8` 个过滤条件，可通过 `and`、`or` 组合。支持操作符：`regex`、`not_regex`、`<`、`<=`、`>`、`>=`、`=`、`<>`、`in`、`not_in`、`match`、`not_match`、`ilike`、`not_ilike`、`like`、`not_like`。`like` / `not_like` / `ilike` / `not_ilike` 支持 `%` 通任意长度字符串。更多规则可参考 `/v3/dataforseo_labs/filters`
`order_by`	array	排序规则。可选。可使用与 `filters` 相同的字段路径进行排序。排序方向支持：`asc`（升序）、`desc`（降序）。单次请求最多支持 `3` 条排序规则
`tag`	string	用户自定义任务标识。可选，最大长度 `255` 个字符。可用于请求与响应结果的业务
`limit`	integer	返回数量上限。可选。默认：`1000`，最大：`1000`
`offset`	integer	返回结果偏移量。可选。默认：`0`。例如传 `10` 时，将跳过前 10 个并从后续结果开始返回。建议在获取不 `10000` 条数据时使用
`offset_token`	string	后续请求使用的分页令牌。可选。每次响应都会返回对应的 `offset_token`。当需要获取 `10000` 条结果时，建议使用该参数而非 `offset`。注意：如果请求中指定了 `offset_token`，则除 `limit` 外的参数不会参与任务处理

过滤与排序说明

`filters` 示例结构

可按字段路径筛选结果，例如：

json

[
 ["keyword_info.search_volume", ">", 10000],
 "and",
 ["keyword_properties.keyword_difficulty", "<=", 30]
]

`order_by` 示例结构

json

[
 "keyword_info.search_volume,desc",
 "keyword_properties.keyword_difficulty,asc"
]

响应结构

接口返回 JSON 格式结果，顶层 tasks 数组。

顶层字段

字段名	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	通用状态码。完整错误码可参考 `/v3/appendix/errors`
`status_message`	string	通用信息说明
`time`	string	执行时间，单位秒
`cost`	float	本次所有任务总费用，单位 USD
`tasks_count`	integer	`tasks` 数组中的任务数量
`tasks_error`	integer	返回错误的任务数量
`tasks`	array	任务结果数组

`tasks[]` 字段

字段名	类型	说明
`id`	string	任务唯一标识，UUID 格式
`status_code`	integer	任务状态码，范围通常为 `10000-60000`
`status_message`	string	任务状态说明
`time`	string	任务执行时间，单位秒
`cost`	float	该任务费用，单位 USD
`result_count`	integer	`result` 数组数量
`path`	array	请求路径
`data`	object	回显请求中提交的参数
`result`	array	获取结果数组

`result[]` 字段

字段名	类型	说明
`se_type`	string	搜索引擎类型
`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`

基础指标。

字段名	类型	说明
`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	付费搜索竞争级别：`LOW`、`MEDIUM`、`HIGH`，未知时为 `null`
`cpc`	float	历史平均单次点击成本，单位 USD
`search_volume`	integer	平均月搜索量
`low_top_of_page_bid`	float	首页顶部广告展示的低位出价参考值
`high_top_of_page_bid`	float	首页顶部广告展示的高位出价参考值
`categories`	array	产品与服务分类
`monthly_searches`	array	最近 12 个月的月度搜索量
`search_volume_trend`	object	搜索量趋势变化

`monthly_searches[]`

字段名	类型	说明
`year`	integer	年
`month`	integer	月
`search_volume`	integer	当月搜索量

`search_volume_trend`

字段名	类型	说明
`monthly`	integer	相比上月的百分比变化
`quarterly`	integer	相比上季度的百分比变化
`yearly`	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 岁用户数

`keyword_properties`

附加属性。

字段名	类型	说明
`se_type`	string	搜索引擎类型
`core_keyword`	string	同义词聚类中的核心；无可识别同义词时为 `null`
`synonym_clustering_algorithm`	string	同义词识别算法：`keyword_metrics` 或 `text_processing`；无结果时为 `null`
`keyword_difficulty`	integer	排名难度，范围 `0-100`
`detected_language`	string	系统识别出的语言
`is_another_language`	boolean	识别语言是否与请求语言不一致
`words_count`	integer	词数

`serp_info`

Google SERP 数据。若未设置 include_serp_info=true，或数据库无对应数据，则为 null。

字段名	类型	说明
`se_type`	string	搜索引擎类型
`check_url`	string	搜索结果直达链接，用于校验结果
`serp_item_types`	array	SERP 中检测到的结果类型
`se_results_count`	integer	搜索结果总数
`last_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	平均 Rank 值
`main_domain_rank`	float	平均主域 Rank 值
`last_updated_time`	string	外链数据更新时间，UTC 格式

`search_intent_info`

搜索意图信息。

字段名	类型	说明
`se_type`	string	搜索引擎类型，可能值：`google`
`main_intent`	string	主搜索意图：`informational`、`navigational`、`commercial`、`transactional`
`foreign_intent`	array	补搜索意图
`last_updated_time`	string	搜索意图更新时间，UTC 格式

`keyword_info_normalized_with_bing`

使用 Bing 搜索量进行归一化后的搜索量信息。

字段名	类型	说明
`last_updated_time`	string	数据集更新时间，UTC 格式
`search_volume`	integer	当前搜索量
`is_normalized`	boolean	是否已做归一化处理
`monthly_searches`	array	月度搜索量

`keyword_info_normalized_with_clickstream`

使用点击流数据进行归一化后的搜索量信息。

字段名	类型	说明
`last_updated_time`	string	数据集更新时间，UTC 格式
`search_volume`	integer	当前搜索量
`is_normalized`	boolean	是否已做归一化处理
`monthly_searches`	array	月度搜索量

请求示例

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"
}
payload = [
 {
 "location_name": "United States",
 "language_name": "English",
 "limit": 3
 }
]

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

if data.get("status_code") == 20000:
 print(data)
else:
 print(f"error. Code: {data.get('status_code')} Message: {data.get('status_message')}")

TypeScript

typescript

import axios from "axios";

const postData = [
 {
 location_name: "United States",
 language_name: "English",
 limit: 3
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/dataforseo_labs/google/top_searches/live",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: postData
})
 .then((response) => {
 // 返回结果
 console.log(response.data);
 })
 .catch((error) => {
 console.log(error);
 });

响应示例

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": [
 {
 "data": {
 "api": "dataforseo_labs",
 "function": "top_searches",
 "se_type": "google",
 "language_name": "English",
 "location_code": 2840,
 "limit": 3
 },
 "result": [
 {
 "items": [
 {
 "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": 1
 },
 "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": []
 }
 },
 {
 "se_type": "google",
 "keyword": "yyyyyyyyyoutube",
 "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": 0,
 "detected_language": null,
 "is_another_language": true,
 "words_count": 1
 },
 "serp_info": null,
 "avg_backlinks_info": {
 "se_type": "google",
 "backlinks": 6.2,
 "dofollow": 1.5,
 "referring_pages": 1.6,
 "referring_domains": 0.3,
 "referring_main_domains": 0.3,
 "rank": 16.6,
 "main_domain_rank": 911.7,
 "last_updated_time": "2024-07-21 09:56:03 +00:00"
 },
 "search_intent_info": {
 "se_type": "google",
 "main_intent": "navigational",
 "foreign_intent": null,
 "last_updated_time": "2023-08-01 06:19:20 +00:00"
 },
 "keyword_info_normalized_with_bing": {
 "last_updated_time": "2024-08-16 17:07:14 +00:00",
 "search_volume": 12,
 "is_normalized": true,
 "monthly_searches": []
 },
 "keyword_info_normalized_with_clickstream": {
 "last_updated_time": "2024-08-16 17:07:14 +00:00",
 "search_volume": 0,
 "is_normalized": true,
 "monthly_searches": []
 }
 },
 {
 "se_type": "google",
 "keyword": "uytuytuyt",
 "location_code": 2840,
 "language_code": "en",
 "keyword_info": {
 "se_type": "google",
 "last_updated_time": "2024-08-11 08:14:45 +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": null,
 "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": null,
 "keyword_difficulty": 0,
 "detected_language": null,
 "is_another_language": true,
 "words_count": 1
 },
 "serp_info": null,
 "avg_backlinks_info": {
 "se_type": "google",
 "backlinks": 8.1,
 "dofollow": 8.1,
 "referring_pages": 8.1,
 "referring_domains": 0.4,
 "referring_main_domains": 0.2,
 "rank": 14.7,
 "main_domain_rank": 934.5,
 "last_updated_time": "2024-07-14 21:42:27 +00:00"
 },
 "search_intent_info": {
 "se_type": "google",
 "main_intent": "navigational",
 "foreign_intent": null,
 "last_updated_time": "2023-03-02 01:47:58 +00:00"
 },
 "keyword_info_normalized_with_bing": {
 "last_updated_time": "2024-08-16 17:07:14 +00:00",
 "search_volume": 0,
 "is_normalized": true,
 "monthly_searches": []
 },
 "keyword_info_normalized_with_clickstream": {
 "last_updated_time": "2024-08-16 17:07:14 +00:00",
 "search_volume": 50,
 "is_normalized": true,
 "monthly_searches": []
 }
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理

建议对接口返回的 status_code 与任务级 tasks[].status_code 建立完整的异常处理逻辑。

顶层 status_code：表示整次请求的处理状态
tasks[].status_code：表示任务的执行状态
常见成功状态码：20000
完整错误码说明可参考 /v3/appendix/errors

在以下场景中应重点处理：

地区或语言参数无效
过滤条件格式错误
offset_token 失效或不匹
请求频率限
并发请求限

使用建议

首次请求带完整参数：指定地区、语言、limit 以及过滤/排序规则
大批量拉取时优使用 offset_token：比单纯使用 offset 更稳定
谨开启 include_clickstream_data：会导致请求费用翻倍
在需要时开启 include_serp_info：减少不的数据体积
结合 ignore_synonyms 去重：适合构建核心词库

实用场景

筛选热门核心词：按搜索量、难度和竞争度筛选高潜力，用于搭建 SEO 优级词库
批量导出区域热搜词：按国家或语言持续分页拉取热门搜索词，为化站点提供本地化选题依据
识别低难度流量机会：结合 search_volume 与 keyword_difficulty 找出高流量、低竞争词，加速自然排名布局
分析 SERP 版位特征：开启 include_serp_info，识别是否存在精选摘要、本地、图片等，用于优化形态和点击率
细分用户搜索画像：开启点击流数据后，利用年龄和性别分布分析目标受众，策划与广告投放优化

Google 热门搜索词实时查询 ​

接口说明 ​

请求地址 ​

计费说明 ​

调用限制 ​

分页与批量获取机制 ​

请求参数 ​

任务参数说明 ​

过滤与排序说明 ​

filters 示例结构 ​

order_by 示例结构 ​

响应结构 ​

顶层字段 ​

tasks[] 字段 ​

result[] 字段 ​

items[] 字段说明 ​

基础字段 ​

keyword_info ​

monthly_searches[] ​

search_volume_trend ​

clickstream_keyword_info ​

gender_distribution ​

age_distribution ​

keyword_properties ​

serp_info ​

avg_backlinks_info ​

search_intent_info ​

keyword_info_normalized_with_bing ​

keyword_info_normalized_with_clickstream ​

请求示例 ​

cURL ​

Python ​

Google 热门搜索词实时查询

接口说明

请求地址

计费说明

调用限制

分页与批量获取机制

请求参数

任务参数说明

过滤与排序说明

`filters` 示例结构

`order_by` 示例结构

响应结构

顶层字段

`tasks[]` 字段

`result[]` 字段

`items[]` 字段说明

基础字段

`keyword_info`

`monthly_searches[]`

`search_volume_trend`

`clickstream_keyword_info`

`gender_distribution`

`age_distribution`

`keyword_properties`

`serp_info`

`avg_backlinks_info`

`search_intent_info`

`keyword_info_normalized_with_bing`

`keyword_info_normalized_with_clickstream`

请求示例

cURL

Python