获取 Keywords For Site 任务结果

接口说明

该接口用于按任务 id 获取 Keywords For Site 的执行结果。

基于指定域名，本接口会返回与该网站的列表，以及每个的核心广告与搜索数据：

• 出价区间
• 最近一个月搜索量
• 过去 12 个月搜索趋势
• 竞争度与竞争指数
• CPC（单次点击费用）
• 语义注解

单次任务最多可返回 2000 个建议。 无论返回多少，计费都以任务提交为准；任务结果在提交后 30 天 可反复获取。

说明：Google Ads 数据基于新版 Google Ads API。若你仍在使用旧版 Google AdWords 接口，建议迁移到 /v3/keywords_data/google_ads/ 路径下的接口体系。

请求地址

GET https://api.seermartech.cn/v3/keywords_data/google_ads/keywords_for_site/task_get/$id

计费说明

该接口本身用于读取已创建任务的结果，不会重复扣费；费用发生在任务创建阶段。

扣费以响应头 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_code 建立统一异常处理机制。

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	结果列表

tasks[].result[] 字段

字段	类型	说明
keyword	string	返回的
location_code	integer	创建任务时指定的地区编码；无数据时为 null
language_code	string	创建任务时指定的语言编码；无数据时为 null
search_partners	boolean	是否 Google 搜索合作伙伴数据
competition	string	付费搜索竞争度，可选值：LOW、MEDIUM、HIGH；未知时为 null
competition_index	integer	竞争指数，范围 0-100；若数据不足则为 null
search_volume	integer	月均搜索量；无数据时为 null
low_top_of_page_bid	float	广告出现在首页顶部位置的较低参考出价
high_top_of_page_bid	float	广告出现在首页顶部位置的较高参考出价
cpc	float	单次点击费用，单位 USD
monthly_searches	array	过去 12 个月的月度搜索量趋势；无数据时为 null
keyword_annotations	object	注解信息

monthly_searches[] 字段

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

keyword_annotations 字段

字段	类型	说明
concepts	array	概念列表

keyword_annotations.concepts[] 字段

字段	类型	说明
name	string	所属概念名称
concept_group	object	概念分组信息

keyword_annotations.concepts[].concept_group 字段

字段	类型	说明
name	string	概念分组名称
type	string	概念分组类型

请求示例

cURL

id="02031614-0696-0108-0000-b26a2a6c7e17"

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

Python

import requests

task_id = "02031614-0696-0108-0000-b26a2a6c7e17"
url = f"https://api.seermartech.cn/v3/keywords_data/google_ads/keywords_for_site/task_get/{task_id}"

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

resp = requests.get(url, headers=headers)
print(resp.status_code)
print(resp.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/keywords_for_site/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.20210917",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "3.6321 sec.",
 "cost": 0.075,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "keywords_data",
 "function": "keywords_for_site",
 "se": "google_ads",
 "target": "example.com",
 "location_code": 2840,
 "search_partners": true
 },
 "result": [
 {
 "keyword_annotations": {
 "concepts": []
 }
 },
 {
 "keyword": "example brand",
 "location_code": 2840,
 "language_code": null,
 "search_partners": true,
 "competition": "LOW",
 "competition_index": 12,
 "search_volume": 110,
 "low_top_of_page_bid": 104.34,
 "high_top_of_page_bid": 264.96,
 "cpc": 3.94,
 "monthly_searches": [],
 "keyword_annotations": {
 "concepts": []
 }
 },
 {
 "keyword": "best seo tools",
 "location_code": 2840,
 "language_code": null,
 "search_partners": true,
 "competition": "MEDIUM",
 "competition_index": 41,
 "search_volume": 2900,
 "low_top_of_page_bid": 130.17,
 "high_top_of_page_bid": 780.74,
 "cpc": 3.94,
 "monthly_searches": [],
 "keyword_annotations": {
 "concepts": []
 }
 },
 {
 "keyword": "top seo tools",
 "location_code": 2840,
 "language_code": null,
 "search_partners": true,
 "competition": "LOW",
 "competition_index": 24,
 "search_volume": 1300,
 "low_top_of_page_bid": 113.83,
 "high_top_of_page_bid": 481.14,
 "cpc": 3.94,
 "monthly_searches": [],
 "keyword_annotations": {
 "concepts": []
 }
 },
 {
 "keyword": "seo tools list",
 "location_code": 2840,
 "language_code": null,
 "search_partners": true,
 "competition": "LOW",
 "competition_index": 18,
 "search_volume": 260,
 "low_top_of_page_bid": 148.09,
 "high_top_of_page_bid": 474.29,
 "cpc": 3.94,
 "monthly_searches": [],
 "keyword_annotations": {
 "concepts": []
 }
 }
 ]
 }
 ]
}

状态码说明

状态码	说明
20000	请求成功，结果已返回
10000-60000	任务级状态码范围，表示处理中、成功或失败等不同状态

完整错误码与状态信息请参考错误码文档。接时，建议同时校验顶层 status_code、tasks[].status_code 以及 result 是否为空。

使用建议

• 通过对应的任务创建接口提交站点分析任务；
• 记录返回的任务 id； -任务完成后，调用本接口按 id 获取结果；
• 若需要批量拉取已完成任务，可合 /v3/keywords_data/google_ads/v2/tasks_ready 使用。

实用场景

• 挖掘站点词：基于目标域名获取高，快速补 SEO选题与词库建设。
• 评估商业价值：结合 cpc、首页顶部出价和竞争度，筛选更投放价值的。
• 识别流量机会：通过 search_volume 与 monthly_searches 找出高需求、趋势上升的主题。
• 拓展竞价词：围绕品牌站点或行业站点生成建议，用于 Google Ads 广告组扩展。
• 进行市场洞察：通过概念注解与竞争指标，分析某一网站所在领域的搜索需求结构。