获取 Google 搜索量任务结果

接口说明

该接口用于根据任务 id 获取 Google 搜索量任务的处理结果。

你将获得以下数据：

• 最近一个月的搜索量
• 最近 12 个月的搜索量趋势
• 当前平均点击单价（CPC）
• 付费搜索竞争度（Competition）

说明：该能力属于旧版 Google AdWords 数据接口体系，现已被 Google Ads API 能力替代。如你正在使用对应旧版能力，建议迁移到 /v3/keywords_data/google_ads/ 接口。

请求方式

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

完整请求地址示例：

https://api.seermartech.cn/v3/keywords_data/google/search_volume/task_get/{id}

计费说明

账户在创建任务时扣费，任务结果在后续 30 天 可重复获取。

若按参考单价折算，参考价可写为：以任务提交接口的计费为准。 本接口本身用于取回已创建任务结果，通常不会重复扣费；扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

路径参数

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

返回结构

接口返回 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。完整错误码请参考 /v3/appendix-errors/。
status_message	string	任务状态信息。
time	string	当前任务执行耗时，单位秒。
cost	float	当前任务成本，单位 USD。
result_count	integer	result 数组中的结果数量。
path	array	请求路径。
data	object	与创建任务时传的参数一致。
result	array	结果数据数组。

result[] 字段说明

字段名	类型	说明
keyword	string	创建任务时传的。
location_code	integer	创建任务时传的地区编码；如无数据则为 null。
language_code	string	创建任务时传的语言编码；如无数据则为 null。
search_partners	boolean	是否合作搜索网络数据。
competition	float	竞争度。表示该在付费搜索结果中的相对竞争程度，取值范围 0 到 1。如无数据则为 null。
cpc	float	平均点击单价，单位 USD。表示历史平均每次点击成本。如无数据则为 null。
search_volume	integer	月均搜索量。表示该在 Google 或 Google 及合作网络中的近似搜索次数，取决于目标设置。如无数据则为 null。
categories	array	产品与服务分类列表。如无数据则为 null。
monthly_searches	array	最近 12 个月的月度搜索量数据。如无数据则为 null。

monthly_searches[] 字段说明

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

请求示例

cURL

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

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

Python

import requests

task_id = "02031608-0696-0110-0000-a81d0414edbe"
url = f"https://api.seermartech.cn/v3/keywords_data/google/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/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.20200130",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "02031608-0696-0110-0000-a81d0414edbe",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0 sec.",
 "cost": 0,
 "result_count": 1,
 "path": [
 "v3",
 "keywords_data",
 "google",
 "search_volume",
 "task_get",
 "02031608-0696-0110-0000-a81d0414edbe"
 ],
 "data": {
 "api": "keywords_data",
 "function": "search_volume",
 "se": "google",
 "location_name": "London,England,United Kingdom",
 "keywords": [
 "keyword"
 ],
 "tag": "tag1"
 },
 "result": [
 {
 "keyword": "keyword",
 "location_code": 2826,
 "language_code": "en",
 "search_partners": false,
 "competition": 0.73,
 "cpc": 1.25,
 "search_volume": 1900,
 "categories": [
 10004,
 10031
 ],
 "monthly_searches": [
 {
 "year": 2024,
 "month": 1,
 "search_volume": 1600
 },
 {
 "year": 2024,
 "month": 2,
 "search_volume": 1700
 },
 {
 "year": 2024,
 "month": 3,
 "search_volume": 1900
 }
 ]
 }
 ]
 }
 ]
}

状态码说明

状态码	说明
20000	请求成功。
10000-60000	任务级状态码范围，含义请参考 /v3/appendix/errors。
40000+	通常表示任务处理失败或请求存在问题，建议结合 status_message 排查。

使用建议

• 该接口适合在任务提交后，按任务 id 轮询获取处理结果。
• 若你有批量任务处理需求，可通过就绪任务列表接口获取已完成任务，再逐个调用本接口拉取。
• monthly_searches 可用于分析季节性与趋势变化。
• competition 和 cpc 更适合广告投放评估，不应与自然搜索竞争度混淆。

实用场景

• 评估投放价值：读取 search_volume、cpc 和 competition，快速判断某个是否值得广告投放计划。
• 分析季节性趋势：利用 monthly_searches 查看过去 12 个月波动，识别旺季、淡季与趋势拐点。
• 验证需求变化：对比不同时间提交的任务结果，观察搜索热度是否持续增长或下滑。
• 筛选高潜力长尾词：结合搜索量与竞争度，找出“有需求但竞争相对低”的机会。
• 支撑本地化 SEO 决策：基于 location_code 与 language_code 的结果，评估不同地区和语言市场的表现。