获取 Google 推荐任务结果

接口说明

该接口用于根据任务 id 获取“推荐”结果。你可以通过对应的任务创建接口提交最多 200 个，任务处理完成后，再通过本接口按任务 ID 获取结果。返回的数据为平台广告系统基于词给出的建议。

说明：

• 该能力属于旧版数据接口体系，现已逐步被新版广告数据接口替代。
• 如果你仍在使用旧版能力，建议评估迁移到新版接口。
• 平台 API 返回的数据，可能与广告平台界面中的规划存在差异。这通常与账户历史、已投放素材、账户级个性化因素及不同数据源。

请求地址

GET https://api.seermartech.cn/v3/keywords_data/google/keywords_for_keywords/task_get/$id

计费说明

该接口本身不会重复扣费；费用在创建任务时产生。任务结果在 30 天 可重复获取。

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

---

路径参数

字段	类型	说明
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	任务结果数组

建议在接时对 status_code、status_message 以及任务级错误状态建立完整的异常处理机制。错误码可参考 /v3/appendix/errors。

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	推荐结果数组

tasks[].data 字段

字段	类型	说明
api	string	API 模块名
function	string	功能名
se	string	搜索引擎类型
language_code	string	语言代码
location_code	integer	地区代码
keywords	array	创建任务时传的列表
tag	string	自定义标签，用于结果归因

tasks[].result[] 字段

字段	类型	说明
keyword	string	返回的推荐
location_code	integer / null	请求中的地区代码；无数据时为 null
language_code	string / null	请求中的语言代码；无数据时为 null
search_partners	boolean	是否合作搜索网络数据
competition	float / null	付费搜索竞争度，范围 0 到 1，基于平台广告数据计算；无数据时为 null
cpc	float / null	历史平均点击费用，单位 USD；无数据时为 null
search_volume	integer / null	月均搜索量；可表示指定目标范围在主搜索引擎或主搜索引擎+合作网络上的近似搜索次数；无数据时为 null
categories	array / null	产品或服务分类列表；无数据时为 null
monthly_searches	array / null	过去 12 个月的月度搜索量明细；无数据时为 null

monthly_searches[] 字段

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

---

请求示例

cURL

# 将 {id} 替换为任务 ID
id="02031624-0696-0107-0000-ee2653ba89d9"

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

Python

import requests

task_id = "02031624-0696-0107-0000-ee2653ba89d9"
url = f"https://api.seermartech.cn/v3/keywords_data/google/keywords_for_keywords/task_get/{task_id}"

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

response = requests.get(url, headers=headers)
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/keywords_for_keywords/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.response?.data || error.message);
 });

---

响应示例

{
 "version": "0.1.20200130",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "5.0565 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "keywords_data",
 "function": "keywords_for_keywords",
 "se": "google",
 "language_code": "en",
 "location_code": 2840,
 "keywords": [
 "adsense"
 ],
 "tag": "tag1"
 },
 "result": [
 {
 "keyword": "google adsense",
 "location_code": 2840,
 "language_code": "en",
 "search_partners": false,
 "competition": 0.1818930929281237,
 "cpc": 1.858456,
 "search_volume": 110000,
 "categories": [],
 "monthly_searches": []
 },
 {
 "keyword": "adsense",
 "location_code": 2840,
 "language_code": "en",
 "search_partners": false,
 "competition": 0.10024431527022201,
 "cpc": 1.427514,
 "search_volume": 110000,
 "categories": [],
 "monthly_searches": []
 },
 {
 "keyword": "prospect",
 "location_code": 2840,
 "language_code": "en",
 "search_partners": false,
 "competition": 0.0032797439370289166,
 "cpc": 4.623882,
 "search_volume": 90500,
 "categories": [],
 "monthly_searches": []
 },
 {
 "keyword": "mlm",
 "location_code": 2840,
 "language_code": "en",
 "search_partners": false,
 "competition": 0.04609994966369266,
 "cpc": 5.00388,
 "search_volume": 90500,
 "categories": [],
 "monthly_searches": []
 }
 ]
 }
 ]
}

---

状态码与错误处理

顶层状态

• status_code = 20000：请求成功
• 状态：表示请求异常、参数错误、认证失败或平台处理异常

任务级状态

每个 tasks[]素也自己的：

• status_code
• status_message

即使顶层请求成功，也应继续检查每个任务的状态是否正常，是在批量调度或异步任务场景下。

错误码可参考：/v3/appendix/errors

---

使用建议

1. 通过对应的任务创建接口提交。
2. 记录返回的任务 id。
3. 轮询查询任务完成状态，或在任务完成后直接使用本接口获取结果。
4. 结果可在 30 天重复拉取，无需重复创建任务。
5. 对 competition、cpc、search_volume 为空的做好容处理。

实用场景

• 扩展投放词库：根据种子词批量获取建议，快速补广告投放与 SEO规划的候选词。
• 筛选商业价值：结合 cpc 与 competition 识别高商业意图词，落地页、投放页和转化型选题。
• 评估热度：利用 search_volume 与 monthly_searches 判断词的搜索规模和季节性变化，优化发布时间与预算分。
• 构建主题簇：围绕核心业务词获取词，整理为专题页、栏目页和文章集群，提升站点主题覆盖度。
• 定位低竞争机会词：从推荐结果中筛选较低 competition 且仍有搜索量的，帮助新站或新页面更快切搜索流量。