Google 热门搜索词（容旧版）

接口说明

/v3/dataforseo_labs/top_google_searches/live 用于获取 Google 热门搜索词数据。该接口基于平台数据库，可返回海量及指标：

Google Ads 指标
Bing Ads 指标
产品/服务分类
Google SERP 数据

注意：这是容旧版（Legacy）接口。虽然平台已更新本平台 Labs API 的请求与响应结构，但本容路径仍持续支持。若你正在维护旧版集成，可继续使用本文档所述结构。

与多数接口不同，本接口采用连续分页拉取机制：

单次最多返回 1000 个；
如需获取更多数据，需要继续发起后续请求；
首次请求中传完整查询参数；
响应会返回唯一的 offset_token；
后续请求需携带该 offset_token 和可选的 limit，即可继续获取下一批结果。

这种方式适合逐步导出大批量数据，并一次性请求过大导致时。

请求地址

POST https://api.seermartech.cn/v3/dataforseo_labs/top_google_searches/live

计费说明

本接口按请求次数计费。

参考价以响应中的 cost 字段为准。若按示例响应中的平台价格 USD 0.0105 估算，则：

参考价约 ¥0.1680 / 次

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

请求格式

请求方法：POST
请求体编码：application/json
请求体结构：JSON 数组 [{ ... }]
频率限制：最高 2000 次调用/分钟

你可以通过以下能力控制返回结果：

指定返回数量
设置过滤条件
设置排序规则
使用 offset_token 连续翻页

请求参数

基础定位参数

字段	类型	说明
`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` 二选一。示例：`en`

结果控制参数

字段	类型	说明
`include_serp_info`	boolean	是否为每个附带 SERP 数据。可选。设为 `true` 时，会返回 `serp_info`，结果数、 URL、SERP 特征等。默认值：`false`
`filters`	array	结果过滤条件数组。可选。最多支持 `8` 个过滤条件，并可通过逻辑运算符 `and`、`or` 组合
`order_by`	array	排序规则。可选。可使用与 `filters` 相同的字段进行排序。排序方式支持 `asc`（升序）和 `desc`（降序）。单次请求最多支持 `3` 条排序规则
`tag`	string	自定义任务标识。可选。最大长度 `255` 字符。便于在响应中识别任务
`limit`	integer	返回最大数量。可选。默认值：`1000`；最大值：`1000`
`offset`	integer	结果偏移量。可选。默认值：`0`。例如设为 `10` 时，会跳过前 10 条结果
`offset_token`	string	连续请求用的偏移令牌。可选。用于获取后续结果批次，适合 `10,000` 条结果的场景，时

`offset_token` 使用规则

当请求中指定 offset_token 时：

除 limit 之外它请求参数都会被忽略；
你将继续获取首次请求对应任务的下一批结果；
每次响应返回的 offset_token 都是当前后续任务唯一对应的令牌。

过滤与排序

`filters`

支持的比较运算符：

<
<=
>
>=
=
<>
in
not_in
like
not_like

说明：

like / not_like 支持使用 % 匹任意长度字符串；
多个条件之间可用 and / or 组合；
最多 8 个过滤条件。

过滤字段的可选路径应以该接口返回结构中的字段为准，例如可针对指标、难度、搜索量等字段进行过滤。

`order_by`

排序格式为字段路径加排序方向，例如：

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

说明：

最多 3 条排序规则；
多条规则之间用数组分隔；
排序字段通常与可过滤字段一致。

请求示例

curl

bash

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

Python

python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/top_google_searches/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "location_name": "United States",
 "language_name": "English",
 "include_serp_info": True,
 "limit": 5
 }
]

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

TypeScript

typescript

import axios from "axios";

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

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

分页拉取示例

首次请求

首次请求需要传完整筛选条件：

json

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

后续请求

拿到首次响应中的 offset_token 后，继续拉取下一批：

json

[
 {
 "offset_token": "YOUR_OFFSET_TOKEN",
 "limit": 1000
 }
]

指定 offset_token 后，除 limit 外的字段均不会参与任务处理。

响应结构

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

顶层字段

字段	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	通用状态码
`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	URL 路径
`data`	object	回显请求中提交的参数
`result`	array	结果数组

`result` 数组字段

字段	类型	说明
`location_code`	integer	请求中的地区代码
`language_code`	string	请求中的语言代码
`total_count`	integer	数据库中与请求的总结果数
`items_count`	integer	当前 `items` 数组中的结果数量
`offset`	integer	当前偏移量
`offset_token`	string	下一次请求使用的偏移令牌
`items`	array	及数据

`items` 数组字段

基础字段

字段	类型	说明
`keyword`	string
`location_code`	integer	请求中的地区代码
`language_code`	string	请求中的语言代码

`keyword_info`：基础指标

字段	类型	说明
`last_updated_time`	string	数据更新时间，UTC，格式：`yyyy-mm-dd hh-mm-ss +00:00`
`competition`	float	竞争度，基于 Google Ads 数据，范围 `0` 到 `1`
`cpc`	float	历史平均点击费用，单位 USD
`search_volume`	integer	月均搜索量
`categories`	array	产品/服务分类
`monthly_searches`	array	最近 12 个月月度搜索量数据

`monthly_searches` 子字段

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

`keyword_properties`：属性

字段	类型	说明
`core_keyword`	string	分组中的核心词；若为 `null`，表示数据库中没有满足条件的相似分组核心词
`keyword_difficulty`	integer	自然搜索前 10 排名难度，范围 `0-100`

`impressions_info`：与广告预估数据

daily_impressions 系列字段可视为对搜索量更细粒度的补。该对象基于高出价场景（bid=999）估算，用于弱化账户个体差异。

字段	类型	说明
`last_updated_time`	string	曝数据更新时间，UTC
`bid`	integer	最大 CPC 出价。该接口固定使用 `999` 作为估算基准
`match` / `match_type`	string	匹类型，可为 `exact`、`broad`、`phrase`
`ad_position_min`	float	广告最低位置
`ad_position_max`	float	广告最高位置
`ad_position_average`	float	广告平均位置
`cpc_min`	float	估算最小 CPC，单位 USD。注意：不是 CPC
`cpc_max`	float	估算最大 CPC，单位 USD。注意：不是 CPC
`cpc_average`	float	估算平均 CPC，单位 USD。注意：不是 CPC
`daily_impressions_min`	float	估算最小日量
`daily_impressions_max`	float	估算最大日量
`daily_impressions_average`	float	估算平均日量
`daily_clicks_min`	float	估算最小日点击量
`daily_clicks_max`	float	估算最大日点击量
`daily_clicks_average`	float	估算平均日点击量
`daily_cost_min`	float	估算最小日花费，单位 USD
`daily_cost_max`	float	估算最大日花费，单位 USD
`daily_cost_average`	float	估算平均日花费，单位 USD

`bing_keyword_info`：Bing 指标

注意：Bing 数据覆盖部分地区和语言。

字段	类型	说明
`last_updated_time`	string	数据更新时间，UTC
`search_volume`	integer	Bing 最近一个月搜索量
`monthly_searches`	array	按月的 Bing 搜索量

`serp_info`：Google SERP 信息

如果请求时未将 include_serp_info 设为 true，数据库中没有该的 SERP 数据，则返回 null。

字段	类型	说明
`check_url`	string	可直接打开的搜索结果页 URL，用于核验结果
`serp_item_types`	array	SERP 中出现的结果类型
`se_results_count`	integer	该的搜索结果总数
`last_updated_time`	string	SERP 数据更新时间，UTC

支持的 SERP素类型：

answer_box
app
carousel
multi_carousel
featured_snippet
google_flights
google_reviews
images
jobs
knowledge_graph
local_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

，接口返回详细结果的核心主要为：

organic
paid
featured_snippet
local_pack

响应示例

json

{
 "version": "0.1.20220131",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "3.6239 sec.",
 "cost": 0.0105,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "dataforseo_labs",
 "function": "top_google_searches",
 "language_name": "English",
 "location_code": 2840,
 "include_serp_info": true,
 "limit": 5
 },
 "result": [
 {
 "items": [
 {
 "keyword": "you",
 "location_code": 2840,
 "language_code": "en",
 "keyword_info": {
 "last_updated_time": "2022-01-13 00:30:36 +00:00",
 "competition": 0.010777017248397794,
 "cpc": 0.078062,
 "search_volume": 151000000
 },
 "keyword_properties": {
 "core_keyword": null,
 "keyword_difficulty": 94
 },
 "impressions_info": {
 "last_updated_time": "2022-01-17 18:12:13 +00:00",
 "bid": 999,
 "match_type": "exact",
 "ad_position_min": 1.11,
 "ad_position_max": 1,
 "ad_position_average": 1.06,
 "cpc_min": 0.41,
 "cpc_max": 0.51,
 "cpc_average": 0.46,
 "daily_impressions_min": 3560.82,
 "daily_impressions_max": 4352.12,
 "daily_impressions_average": 3956.47,
 "daily_clicks_min": 164.24,
 "daily_clicks_max": 200.74,
 "daily_clicks_average": 182.49,
 "daily_cost_min": 75.44,
 "daily_cost_max": 92.2,
 "daily_cost_average": 83.82
 },
 "bing_keyword_info": {
 "last_updated_time": "2022-01-23 18:56:48 +00:00",
 "search_volume": 611640
 },
 "serp_info": {
 "check_url": "https://www.google.com/search?q=you&num=100&hl=en&gl=US&gws_rd=cr&ie=UTF-8&oe=UTF-8&uule=w+CAIQIFISCQs2MuSEtepUEUK33kOSuTsc",
 "se_results_count": 25270000000,
 "last_updated_time": "2022-01-13 20:29:03 +00:00"
 }
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理

接口会返回顶层 status_code 与任务级 status_code。

建议你在接时同时处理以下两层状态：

HTTP 状态码
业务状态码（status_code）

常见处理建议：

顶层 status_code = 20000 通常表示请求成功；
若 tasks_error > 0，说明部分任务失败；
若任务级 status_code 非成功值，应结合 status_message 记录原因并重试或修正参数；
对于大批量拉取任务，建议保存每次响应中的 offset_token，以便断点续拉。

使用建议

1. 优使用 `location_code` 与 `language_code`

代码形式通常更稳定，适合程序化调用。

2. 获取大批量结果时使用 `offset_token`

不要尝试一次请求拉取大结果集；应按批次循环拉取。

3. 需要 SERP 数据时再启用 `include_serp_info`

该字段会增加返回数据体积，只有在需要搜索结果页特征时再开启。

4. 用 `filters` 和 `order_by` 缩小范围

过滤再拉取，可减少无效数据与请求次数。

实用场景

筛选高流量热门词：按地区和语言拉取热门 Google 搜索词，快速发现高搜索量主题，用于选题和流量布局。
挖掘低难度机会词：结合 keyword_difficulty、search_volume 和 competition 过滤，优挑选更容易自然排名的机会词。
分析 SERP 版式变化：开启 include_serp_info，识别对应的 featured_snippet、local_pack、people_also_ask 等特征，判断形式和排名策略。
评估广告投放空间：利用 cpc、daily_impressions_average、daily_clicks_average 等字段，估算商业价值与潜在投放成本。
批量构建数据库：结合 offset_token 连续翻页，分批导出大规模热门搜索词，用于站群规划、行业词库建设和市场监测。

Google 热门搜索词（容旧版） ​

接口说明 ​

请求地址 ​

计费说明 ​

请求格式 ​

请求参数 ​

基础定位参数 ​

结果控制参数 ​

offset_token 使用规则 ​

过滤与排序 ​

filters ​

order_by ​

请求示例 ​

curl ​

Python ​

TypeScript ​

分页拉取示例 ​

首次请求 ​

后续请求 ​

响应结构 ​

顶层字段 ​

tasks 数组字段 ​

result 数组字段 ​

items 数组字段 ​

基础字段 ​

keyword_info：基础指标 ​

monthly_searches 子字段 ​

keyword_properties：属性 ​

impressions_info：与广告预估数据 ​

bing_keyword_info：Bing 指标 ​

serp_info：Google SERP 信息 ​

响应示例 ​

Google 热门搜索词（容旧版）

接口说明

请求地址

计费说明

请求格式

请求参数

基础定位参数

结果控制参数

`offset_token` 使用规则

过滤与排序

`filters`

`order_by`

请求示例

curl

Python

TypeScript

分页拉取示例

首次请求

后续请求

响应结构

顶层字段

`tasks` 数组字段

`result` 数组字段

`items` 数组字段

基础字段

`keyword_info`：基础指标

`monthly_searches` 子字段

`keyword_properties`：属性

`impressions_info`：与广告预估数据

`bing_keyword_info`：Bing 指标

`serp_info`：Google SERP 信息

响应示例