SeerMarTech API 文档

主题

获取 Keywords For Keywords 任务结果 ​

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

接口说明 ​

该接口用于根据任务 id 获取 Keywords For Keywords 的结果数据。

该能力基于最新版本的 Google Ads 数据体系，用于为指定词语筛选建议。您可以在创建任务时最多提交 20 个，任务完成后，通过本接口按任务 ID 获取结果。返回结果为平台 API 提供的建议及竞价、搜索量、竞争度等指标。

  • 请求方式：GET
  • 请求地址：https://api.seermartech.cn/v3/keywords_data/google_ads/keywords_for_keywords/task_get/$id

计费说明 ​

此类接口通常在创建任务时扣费，获取结果本身在任务创建后的 30 天 可重复查询。

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

路径参数 ​

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

返回结构 ​

接口返回 JSON 数据，顶层 tasks 数组，每个任务中任务状态、请求参数回显和结果列表。

顶层字段 ​

字段类型说明
versionstring当前 API 版本。
status_codeinteger通用状态码。建议对异常和错误状态进行完整处理。
status_messagestring通用状态信息。
timestring执行耗时，单位秒。
costfloat本次请求总成本，单位 USD。扣费以该字段为准。
tasks_countintegertasks 数组中的任务数量。
tasks_errorinteger返回错误的任务数量。
tasksarray任务结果数组。

tasks[] 字段 ​

字段类型说明
idstring任务 ID，UUID 格式。
status_codeinteger任务状态码，范围通常为 10000-60000。
status_messagestring任务状态说明。
timestring任务执行耗时，单位秒。
costfloat单个任务成本，单位 USD。
result_countintegerresult 数组中的数量。
patharray请求路径。
dataobject与创建任务时传参数一致的回显数据。
resultarray结果数组。

tasks[].result[] 字段 ​

字段类型说明
keywordstringPOST 提交时的，或基于提交词返回的建议。
location_codeintegerPOST 请求中的地区编码；如果无数据，返回 null。
language_codestringPOST 请求中的语言编码；如果无数据，返回 null。
search_partnersboolean是否 Google 搜索合作伙伴数据。
若为 true，结果 Google 自有网络及合作伙伴站点；若为 false，返回 Google 搜索站点数据。
competitionstring竞争度适用于付费搜索场景。可能值：LOW、MEDIUM、HIGH。若未知则为 null。
competition_indexinteger竞争指数，范围 0-100。反映广告位竞争强度；若数据不足则为 null。
search_volumeinteger月均搜索量。根据任务定向范围，表示 Google 搜索或 Google 搜索+合作伙伴的近似搜索量。无数据时返回 null。
low_top_of_page_bidfloat广告展示在首页顶部位置的较低出价参考值。通常高于约 20% 的最低展示出价。不同地区下该值可能不同。
high_top_of_page_bidfloat广告展示在首页顶部位置的较高出价参考值。通常高于约 80% 的最低展示出价。不同地区下该值可能不同。
cpcfloat单次点击成本，单位 USD。表示该广告点击的大致成本。
monthly_searchesarray最近 12 个月的月度搜索量明细；无数据时返回 null。
monthly_searches[].yearinteger年份。
monthly_searches[].monthinteger月份。
monthly_searches[].search_volumeinteger当月搜索量。
keyword_annotationsobject注释信息。
keyword_annotations.conceptsarray概念列表。
keyword_annotations.concepts[].namestring概念名称。
keyword_annotations.concepts[].concept_groupobject概念分组信息。
keyword_annotations.concepts[].concept_group.namestring概念组名称。
keyword_annotations.concepts[].concept_group.typestring概念组类型。

使用说明 ​

  1. 通过对应的任务创建接口创建任务。
  2. 记录返回的任务 id。
  3. 任务完成后，调用本接口按 id 获取结果。
  4. 如需批量获取已完成任务，也可结合已完成任务列表接口轮询处理。

请求示例 ​

curl ​

bash
id="02031624-0696-0107-0000-ee2653ba89d9"

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

Python ​

python
import requests

task_id = "02031624-0696-0107-0000-ee2653ba89d9"
url = f"https://api.seermartech.cn/v3/keywords_data/google_ads/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 ​

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/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);
});

响应示例 ​

以下为简化后的响应结构示例，完整结果中 result 可能大量建议。

json
{
 "version": "0.1.20231117",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "02031624-0696-0107-0000-ee2653ba89d9",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0 sec.",
 "cost": 0,
 "result_count": 1,
 "path": [
 "v3",
 "keywords_data",
 "google_ads",
 "keywords_for_keywords",
 "task_get",
 "02031624-0696-0107-0000-ee2653ba89d9"
 ],
 "data": {
 "api": "keywords_data",
 "function": "keywords_for_keywords",
 "se": "google_ads",
 "location_code": 2840,
 "keywords": [
 "qualified leads"
 ],
 "include_adult_keywords": true
 },
 "result": [
 {
 "keyword": "qualified leads",
 "location_code": 2840,
 "language_code": null,
 "search_partners": false,
 "competition": "LOW",
 "competition_index": 11,
 "search_volume": 1300,
 "low_top_of_page_bid": 3.33,
 "high_top_of_page_bid": 26.48,
 "cpc": 14.33,
 "monthly_searches": null,
 "keyword_annotations": {
 "concepts": []
 }
 },
 {
 "keyword": "get qualified leads",
 "location_code": 2840,
 "language_code": null,
 "search_partners": false,
 "competition": "HIGH",
 "competition_index": 68,
 "search_volume": 10,
 "low_top_of_page_bid": 9.77,
 "high_top_of_page_bid": 28,
 "cpc": null,
 "monthly_searches": null,
 "keyword_annotations": {
 "concepts": []
 }
 },
 {
 "keyword": "find prospects",
 "location_code": 2840,
 "language_code": null,
 "search_partners": false,
 "competition": "LOW",
 "competition_index": 33,
 "search_volume": 30,
 "low_top_of_page_bid": 6.01,
 "high_top_of_page_bid": 16.81,
 "cpc": 31.26,
 "monthly_searches": null,
 "keyword_annotations": {
 "concepts": []
 }
 }
 ]
 }
 ]
}

状态码与错误处理 ​

  • 顶层 status_code 表示整次请求的通用执行状态。
  • tasks[].status_code 表示单个任务的处理状态。
  • 建议同时校验：
  • HTTP 状态码
  • 顶层 status_code
  • 任务级 tasks[].status_code
  • result 是否为空

常见处理建议：

场景建议
status_code = 20000请求成功，可继续解析 tasks。
tasks[].status_code >= 40000任务级错误，建议记录 status_message 并重试或排查参数。
result = null 或空数组任务可能尚未完成，或对应在指定条件下无可用数据。
任务 ID过 30 天结果可能不可再获取，建议重新创建任务。

结果解读建议 ​

  • competition 和 competition_index 更适合用于评估付费投放竞争强度，不应直接等同于自然搜索 SEO 难度。
  • search_volume 可用于判断需求规模。
  • low_top_of_page_bid、high_top_of_page_bid 与 cpc 可用于评估商业价值和广告投放成本。
  • monthly_searches 适合进一步分析季节性波动。
  • keyword_annotations.concepts 可进行语义聚类和主题扩展。

实用场景 ​

  • 扩展投放词库：核心业务词，获取 Google Ads 词建议，快速补 SEM 投放池。
  • 筛选高价值：结合 search_volume、cpc 和顶部出价指标，优识别需求与商业价值的。
  • 评估竞价难度：利用 competition 和 competition_index 判断广告位竞争强度，预算分与出价策略制定。
  • 分析搜索趋势波动：通过 monthly_searches 观察近 12 个月需求变化，支持季节性与广告排期。
  • 做语义主题聚类：利用 keyword_annotations 中的概念信息，对词进行分组，支持专题页、集群或广告组搭建。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API