获取 Google Ads 搜索量任务结果

接口说明

该接口用于根据任务 id 获取已提交搜索量任务的结果。 返回：搜索量、近 12 个月月度搜索量、竞争度、竞争指数、首页顶部出价区间、CPC 等数据。

平台 API 基于新版 Google Ads 数据体系。如果你仍在使用旧版接口，建议迁移到当前 /v3/keywords_data/google_ads/ 路径下的接口。

• 单次任务最多支持查询 1000 个
• 结果可在任务提交后的 30 天 反复获取
• 在创建任务（POST）时计费，获取结果通常不重复扣费
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

请求方式

GET /v3/keywords_data/google_ads/search_volume/task_get/{id}

路径参数

字段	类型	说明
id	string	任务唯一标识，UUID 格式。可在任务创建后的 30 天随时用于获取结果。

返回结果

接口返回 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	任务 ID，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 数组字段

字段	类型	说明
keyword	string	。返回时会对编码进行解码，例如 + 会被还原为空格。
spell	string	的推荐拼写。如果提交的词疑似拼写错误，系统可能返回修正后的数据；无修正时为 null。
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	月均搜索量。表示指定在目标范围的近似月平均搜索次数；无数据时为 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	当月搜索量

计费说明

该接口本身用于读取已创建任务的结果，通常不会重复计费。 费用发生在创建任务时。

如果参考单价页展示价格，请按以下方式理解平台参考换算：

• 人民币参考价以响应头 X-SeerMarTech-Charge-CNY 为准
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

由于本接口文档页未给出固定单价，因此此处不展示固定人民币参考价。

请求示例

cURL

id="02031608-0696-0110-0000-a81d0414edbe"

curl --location --request GET "https://api.seermartech.cn/v3/keywords_data/google_ads/search_volume/task_get/${id}" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json"

Python

import requests

task_id = "02231934-2604-0066-2000-570459f04879"
url = f"https://api.seermartech.cn/v3/keywords_data/google_ads/search_volume/task_get/{task_id}"

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

response = requests.get(url, headers=headers)
print(response.status_code)
print(response.json)

TypeScript

import axios from "axios";

const taskId = "02231934-2604-0066-2000-570459f04879";

axios({
 method: "get",
 url: `https://api.seermartech.cn/v3/keywords_data/google_ads/search_volume/task_get/${taskId}`,
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
})
 .then((response) => {
 // 返回任务结果
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应示例

{
 "version": "0.1.20231117",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "keywords_data",
 "function": "search_volume",
 "se": "google_ads",
 "language_code": "en",
 "location_code": 2840,
 "keywords": [
 "cheap laptops for sale",
 "purchase laptop"
 ],
 "date_from": "2021-08-01"
 },
 "result": [
 {
 "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": []
 },
 {
 "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": []
 }
 ]
 }
 ]
}

状态码与错误处理

• 20000：请求成功
• 40000+：通常表示任务级错误、参数错误或数据不可用
• 若 tasks_error > 0，说明部分任务执行失败
• 若任务尚未完成，可能暂时取不到 result
• 完整错误码定义可参考错误码附录文档

建议重点校验以下字段：

• 顶层 status_code
• tasks[].status_code
• tasks[].result
• tasks_error

使用建议

1. 通过创建任务接口提交搜索量查询任务
2. 保存返回的任务 id
3. 可结合任务完成通知或轮询机制获取结果
4. 获取结果后，优读取 result 数组中的指标
5. 对 spell、competition、cpc、monthly_searches 做空值容处理

实用场景

• 批量评估商业价值：读取搜索量、CPC、竞争度，快速判断是否适合投放或 SEO 布局。
• 识别季节性波动：结合 monthly_searches 分析近 12 个月趋势，发布节奏和大促排期。
• 筛选低竞争高潜力词：根据 search_volume 与 competition_index 找出更适合切的长尾词，提升自然流量获取效率。
• 估算广告投放门槛：利用 low_top_of_page_bid、high_top_of_page_bid 和 cpc 评估预算需求，优化竞价策略。
• 纠正拼写偏差：通过 spell 字段识别用户提交词是否存在拼写问题，因错词导致选词判断失真。