Google Ads 搜索量实时查询

接口概述

POST /v3/keywords_data/google_ads/search_volume/live

用于实时获取在 Google Ads 数据源中的搜索量信息。单次请求最多可提交 1000 个，返回：

• 搜索量（search_volume）
• 月度搜索趋势（monthly_searches）
• 竞争度（competition、competition_index）
• 首页顶部竞价区间（low_top_of_page_bid、high_top_of_page_bid）
• 平均点击价格（cpc）

历史数据最长可追溯 24 个月。

注意：

• 每个账号使用该类 Google Ads Live 端点时，每分钟最多 12 次请求
• 数据接口整体支持较高并发，但本接口受平台实时端点频控限制
• 无论 keywords 数组中传 1 个还是 1000 个，均按请求次数计费

参考价约 ¥1.2000 / 次；扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求地址

POST https://api.seermartech.cn/v3/keywords_data/google_ads/search_volume/live

请求体格式

所有 POST 数据需使用 UTF-8 编码的 JSON，且请求体为 JSON 数组：

[
 {
 "keywords": ["buy laptop", "cheap laptops for sale"]
 }
]

---

请求参数

以下为任务设置时可用字段。

字段名	类型	说明
keywords	array	填。列表。最多 1000 个；每个最长 80 个字符；每个短语最多 10 个单词。系统会自动转为小写。
location_name	string	可选。搜索引擎地区完整名称。不传则返回范围数据。使用该字段时，无需再传 location_code 或 location_coordinate。示例：London,England,United Kingdom
location_code	integer	可选。搜索引擎地区编码。不传则返回范围数据。使用该字段时，无需再传 location_name 或 location_coordinate。示例：2840
location_coordinate	string	可选。GPS 坐标，格式为 "latitude,longitude"。使用该字段时，无需再传 location_name 或 location_code。返回数据按该坐标所属国家提供。示例：52.6178549,-155.352142
language_name	string	可选。语言完整名称。示例：English
language_code	string	可选。语言代码。示例：en
search_partners	boolean	可选。是否 Google 搜索合作伙伴网络数据。true 表示 Google 及合作站点；默认 false，返回 Google 搜索站点数据。
date_from	string	可选。时间范围起始日期，格式 "yyyy-mm-dd"。最早可设为当前日期往前 4 年。默认返回过去 12 个月数据。不能晚于 date_to，也不能晚于昨天。若状态接口 /v3/keywords_data/google_ads/status/ 返回 actual_data=false，则最晚可设到上上月；若返回 actual_data=true，则最晚可设到上月。
date_to	string	可选。时间范围结束日期，格式 "yyyy-mm-dd"。不能大于上个月，因为平台不返回当月数据。不传时默认使用昨天日期。示例：2022-11-30
include_adult_keywords	boolean	可选。是否成人。设为 true 时会尝试返回数据；默认 false。受平台限制影响，这类可能无数据。
sort_by	string	可选。结果排序方式，按降序排序。可选值：relevance、search_volume、competition_index、low_top_of_page_bid、high_top_of_page_bid。默认：relevance
tag	string	可选。自定义任务标识，最大 255 字符。可用于请求结果对账或业务追踪。响应中的 data 会返回该值。

keywords 字段使用说明

keywords 为本接口最核心参数，使用时请注意：

1. 某些组合可能无法返回数据，这是平台广告数据源的正常表现。
2. 相近可能会被合并返回同一搜索量值。
3. 如需更精确比较相似，建议拆分为多个请求分别提交。
4. 不支持某些特殊符号、UTF 特殊字符或 emoji。
5. 会被统一转换为小写。

地区与语言列表获取

可通过以下容路径查询支持的地区和语言：

• 地区列表：/v3/keywords_data/google_ads/locations
• 语言列表：/v3/keywords_data/google_ads/languages

---

返回结果说明

接口返回 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	请求路径
data	array	原样回显请求时提交的参数
result	array	结果数据数组

result[] 字段

字段名	类型	说明
keyword	string	。返回时会解码特殊编码；+ 会被还原为空格。
spell	string	纠正后的拼写。如果提交的疑似拼写错误，结果可能按修正后的词返回。
location_code	integer	请求中的地区编码；无数据时为 null
language_code	string	请求中的语言代码；无数据时为 null
search_partners	boolean	是否合作伙伴搜索网络数据
competition	string	付费搜索竞争度。可选值：HIGH、MEDIUM、LOW；无数据时为 null
competition_index	integer	付费搜索竞争指数，范围 0-100；无数据时为 null
search_volume	integer	月均搜索量。表示指定在 Google 搜索或 Google+合作伙伴网络中的近似搜索次数；无数据时为 null
low_top_of_page_bid	float	首页顶部广告位较低竞价参考值，约高于 20% 最低展示出价
high_top_of_page_bid	float	首页顶部广告位较高竞价参考值，约高于 80% 最低展示出价
cpc	float	单次点击成本，单位 USD
monthly_searches	array	月度搜索量明细；默认返回过去 12 个月，可结合日期参数获取更长区间；无数据时为 null

monthly_searches[] 字段

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

---

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/keywords_data/google_ads/search_volume/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "location_code": 2840,
 "keywords": [
 "buy laptop",
 "cheap laptops for sale",
 "purchase laptop"
 ],
 "date_from": "2021-08-01",
 "search_partners": true
 }
]'

Python

import requests

url = "https://api.seermartech.cn/v3/keywords_data/google_ads/search_volume/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
payload = [
 {
 "location_code": 2840,
 "keywords": [
 "buy laptop",
 "cheap laptops for sale",
 "purchase laptop"
 ],
 "date_from": "2021-08-01",
 "search_partners": True
 }
]

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

TypeScript

import axios from "axios";

const payload = [
 {
 location_code: 2840,
 keywords: [
 "buy laptop",
 "cheap laptops for sale",
 "purchase laptop"
 ],
 date_from: "2021-08-01",
 search_partners: true
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/keywords_data/google_ads/search_volume/live",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: payload
})
 .then((response) => {
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

---

响应示例

{
 "version": "0.1.20231117",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "1.9903 sec.",
 "cost": 0.075,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "1.9500 sec.",
 "cost": 0.075,
 "result_count": 3,
 "path": [
 "v3",
 "keywords_data",
 "google_ads",
 "search_volume",
 "live"
 ],
 "data": {
 "api": "keywords_data",
 "function": "search_volume",
 "se": "google_ads",
 "language_code": "en",
 "location_code": 2840,
 "keywords": [
 "buy laptop",
 "cheap laptops for sale",
 "purchase laptop"
 ],
 "date_from": "2021-08-01"
 },
 "result": [
 {
 "keyword": "buy laptop",
 "spell": null,
 "location_code": 2840,
 "language_code": "en",
 "search_partners": false,
 "competition": "HIGH",
 "competition_index": 100,
 "search_volume": 12100,
 "low_top_of_page_bid": 0.62,
 "high_top_of_page_bid": 4.91,
 "cpc": 2.13,
 "monthly_searches": [
 {
 "year": 2023,
 "month": 10,
 "search_volume": 12100
 }
 ]
 },
 {
 "keyword": "cheap laptops for sale",
 "spell": null,
 "location_code": 2840,
 "language_code": "en",
 "search_partners": false,
 "competition": "HIGH",
 "competition_index": 100,
 "search_volume": 6600,
 "low_top_of_page_bid": 0.38,
 "high_top_of_page_bid": 2.78,
 "cpc": 1.25,
 "monthly_searches": [
 {
 "year": 2023,
 "month": 10,
 "search_volume": 6600
 }
 ]
 },
 {
 "keyword": "purchase laptop",
 "spell": null,
 "location_code": 2840,
 "language_code": "en",
 "search_partners": false,
 "competition": "HIGH",
 "competition_index": 99,
 "search_volume": 110,
 "low_top_of_page_bid": 2.07,
 "high_top_of_page_bid": 15.43,
 "cpc": 12.74,
 "monthly_searches": [
 {
 "year": 2023,
 "month": 10,
 "search_volume": 110
 }
 ]
 }
 ]
 }
 ]
}

---

状态码与错误处理

• 顶层 status_code 表示整次请求处理状态
• tasks[].status_code 表示单个任务状态
• 建议同时校验：
• HTTP 状态码
• 顶层 status_code
• 单任务 tasks[].status_code

常见成功状态：

• 20000：成功

如需处理完整错误码，请参考 /v3/appendix/errors。

错误处理建议

1. 对 tasks_error 大于 0 的做告警或重试。
2. 对空结果业务侧降级处理，因为平台可能对某些词不返回数据。
3. 对相似建议拆单请求，搜索量被合并。
4. 调用频率务控制在 每分钟 12 次 ，触发限流。

使用建议

• 批量评估时，优一次提交尽可能多的词，以提升单次请求性价比
• 做对比时，把高度相似的词放在同一个请求中
• 如果你依赖最新月份数据，建议检查 /v3/keywords_data/google_ads/status/ 的 actual_data
• 针对本地化 SEO/投放分析，应明确设置地区与语言参数，拿到汇总数据

实用场景

• 批量评估价值：一次查询最多 1000 个词的搜索量、竞争度与 CPC，快速筛选适合 SEO 或投放的目标词。
• 判断区域市场需求：结合 location_code 或 location_coordinate 查看不同国家/地区的搜索热度，为本地化和出海策略提供依据。
• 识别季节性趋势：利用 monthly_searches 分析过去 12-24 个月的变化，判断是否存在淡旺季，优化发布时间。
• 评估商业化难度：通过 competition_index、cpc、首页顶部竞价区间衡量投放竞争压力，广告预算规划。
• 校验拼写与规范性：通过 spell 字段识别疑似拼写错误的查询词，减少无效词采买与布局偏差。