获取 Google 分类任务结果

接口说明

该接口用于根据已创建任务的 id 获取“按产品分类推荐”的结果。

说明：Google AdWords Keywords Data API 属于旧版能力，现已由 Google Ads API 替代。若你仍在使用对应旧版能力，建议迁移到 /v3/keywords_data/google_ads/ 接口体系。

通过本接口，你可以针对指定的产品分类获取建议，并同时拿到以下核心指标：

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

单个任务最多可返回 700 个建议及指标。

请求方式

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

计费说明

该接口本身不会因获取结果而额外扣费，账户在创建任务时计费。

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

路径参数

字段	类型	说明
id	string	任务唯一标识符，UUID 格式。该 id 可在任务创建后的 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 和任务级别状态码建立完善的异常处理机制。完整错误码可参考 /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	请求路径
data	object	与创建任务时传参数一致的数据对象
result	array	任务结果数组

result 数组字段

字段	类型	说明
keyword	string	返回的
location_code	integer	创建任务时使用的地区编码；若无数据则为 null
language_code	string	创建任务时使用的语言编码；若无数据则为 null
search_partners	boolean	是否合作搜索网络数据
competition	float	付费搜索竞争度，取值范围 0-1；基于 Google Ads 数据计算；若无数据则为 null
cpc	float	平均点击价格，单位 USD；若无数据则为 null
search_volume	integer	月均搜索量；表示目标范围的大致搜索次数；若无数据则为 null
categories	array	产品/服务分类列表；若无数据则为 null
monthly_searches	array	过去 12 个月的月度搜索量；若无数据则为 null

monthly_searches 数组字段

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

返回数据说明

该接口会返回指定产品分类下的候选列表。除本身外，还会附带以下常用 SEO / SEM 指标：

• search_volume：用于衡量需求规模
• monthly_searches：用于观察季节性和趋势变化
• cpc：用于评估商业价值与投放成本
• competition：用于评估付费搜索竞争强度
• categories：用于识别所属产品/服务分类

调用示例

cURL

id="02031629-0696-0109-0000-4aa9592ce749"

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

Python

import requests

task_id = "02031629-0696-0109-0000-4aa9592ce749"

url = f"https://api.seermartech.cn/v3/keywords_data/google/keywords_for_category/task_get/{task_id}"

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

response = requests.get(url, headers=headers)
data = response.json

print(data)

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_category/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": "5.2880 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "02031629-0696-0109-0000-4aa9592ce749",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "5.1023 sec.",
 "cost": 0,
 "result_count": 4,
 "path": [
 "v3",
 "keywords_data",
 "google",
 "keywords_for_category",
 "task_get",
 "02031629-0696-0109-0000-4aa9592ce749"
 ],
 "data": {
 "api": "keywords_data",
 "function": "keywords_for_category",
 "se": "google",
 "location_name": "London,England,United Kingdom",
 "language_name": "English",
 "category_code": 13895,
 "tag": "tag1"
 },
 "result": [
 {
 "keyword": "polygon",
 "location_code": 1006886,
 "language_code": "en",
 "search_partners": false,
 "competition": 0.0013572539051896456,
 "cpc": 0,
 "search_volume": 6600,
 "categories": [13895],
 "monthly_searches": [
 {
 "year": 2019,
 "month": 12,
 "search_volume": 6600
 }
 ]
 },
 {
 "keyword": "mountain bike",
 "location_code": 1006886,
 "language_code": "en",
 "search_partners": false,
 "competition": 0.9998855922507818,
 "cpc": 0.770228,
 "search_volume": 5400,
 "categories": [13895],
 "monthly_searches": [
 {
 "year": 2019,
 "month": 12,
 "search_volume": 5400
 }
 ]
 },
 {
 "keyword": "hyundai kona",
 "location_code": 1006886,
 "language_code": "en",
 "search_partners": false,
 "competition": 0.29028968834971763,
 "cpc": 0.860399,
 "search_volume": 4400,
 "categories": [13895],
 "monthly_searches": [
 {
 "year": 2019,
 "month": 12,
 "search_volume": 4400
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理

• 顶层 status_code 表示整次请求是否成功
• tasks[].status_code 表示单个任务是否成功
• 若任务尚未完成、参数无效或结果不可用，应根据状态码和 status_message 进行重试、告警或回退处理

常见处理建议：

1. 判断顶层 status_code 是否成功
2. 再遍历 tasks，检查每个任务的 status_code
3. 若 result 为空，确认任务是否已完成，或检查原始提交参数是否正确
4. 对 null 值字段做好容，特别是 cpc、competition、search_volume、monthly_searches

使用建议

• 该接口适合与任务提交接口合使用：提交分类任务，再通过本接口按 id 获取结果
• 若需要批量消费结果，建议使用就绪任务列表接口，再按任务 id 逐个获取结果
• 对结果可结合搜索量、CPC 与竞争度进行优级排序，用于 SEO规划或投放词筛选

实用场景

• 挖掘分类词：按产品分类批量获取，快速建立行业词库与站点栏目词表。
• 筛选高价值：结合 search_volume、cpc、competition 识别流量与商业价值的重点词。
• 分析季节性需求：利用 monthly_searches 观察近 12 个月波动，制定发布时间和投放节奏。
• 扩展广告投放词：从分类维度补长尾与词，提升广告覆盖面与投放精细度。
• 优化类目页：将分类高频词映射到类目页标题、描述和模块，提高页面性。