按任务 ID 获取 Google Ads 广告流量结果

自 6 月 1 日起，「按获取广告流量」接口返回整个广告系列的批量数据，即创建任务时提交的结果。

本接口基于新版 Google Ads API。通过查询任务结果，可获取用于估算点击量、平均点击费用（CPC）和广告成本的指标。与针对相似集合的常规搜索量估算相比，该数据更适合评估单个的广告需求。

接口信息

GET /v3/keywords_data/google_ads/ad_traffic_by_keywords/task_get/$id

完整请求地址：

text

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

$id 为创建任务时返回的任务 ID。

计费说明

在提交任务时产生费用。
任务完成后，可在 30 天查询任务结果。
查询结果接口本身不重复扣费。
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

该接口使用路径参数，不需要请求体。

参数	类型	说明
`id`	string	任务唯一标识符，采用 UUID 格式。任务创建后 30 天可使用该 ID 随时查询结果。

响应结构

接口返回 JSON 数据 tasks 数组。

顶层字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	请求整体状态码。详细状态码请参考错误码文档。
`status_message`	string	请求整体说明信息。
`time`	string	接口执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务数量。
`tasks_error`	integer	`tasks` 数组中返回错误的任务数量。
`tasks`	array	任务结果数组。

`tasks` 中的任务字段

字段	类型	说明
`id`	string	任务唯一标识符，采用 UUID 格式。
`status_code`	integer	任务状态码，通常位于 `10000` 至 `60000` 范围。
`status_message`	string	任务状态说明。
`time`	string	任务执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的结果数量。
`path`	array	请求路径信息。
`data`	object	创建任务时提交的参数。
`result`	array	广告流量结果数组。

`result` 结果字段

字段	类型	说明
`keyword`	string	创建任务时提交的。指标会针对请求中的返回。
`location_code`	integer	创建任务时提交的地区代码。没有数据时返回 `null`。
`language_code`	string	创建任务时提交的语言代码。没有数据时返回 `null`。
`date_interval`	string	创建任务时提交的预测日期区间。
`search_partners`	boolean	是否 Google 搜索合作伙伴数据。该接口固定返回 `false`。
`bid`	float	创建任务时设置的最高自定义出价，表示广告主愿意为广告支付的最高金额。出价越高，通常可获得的指标范围越大，任务成本也可能越高。
`match`	string	匹类型，可选值为 `exact`、`broad`、`phrase`。
`impressions`	float	预测广告展示次数。该字段已弃用，固定返回 `null`。
`ctr`	float	预测广告点击率，即预测点击次数除以预测展示次数。该字段已弃用，固定返回 `null`。
`average_cpc`	float	平均每次点击费用，基于指定日期区间和历史数据估算，单位为人民币。没有数据时返回 `null`。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`clicks`	float	指定日期区间的预测广告点击次数。没有数据时返回 `null`。

请求示例

cURL

bash

task_id="02031634-0696-0111-0000-61c2471b87fc"

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

Python

python

import requests

task_id = "02031634-0696-0111-0000-61c2471b87fc"
url = (
    "https://api.seermartech.cn/v3/keywords_data/google_ads/"
    f"ad_traffic_by_keywords/task_get/{task_id}"
)

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

response = requests.get(url, headers=headers, timeout=60)
response.raise_for_status()

data = response.json()

if data.get("status_code") == 20000:
    print(data)
else:
    print(
        f"请求失败，状态码：{data.get('status_code')}，"
        f"信息：{data.get('status_message')}"
    )

TypeScript

typescript

import axios from "axios";

const taskId = "02231934-2604-0066-2000-570459f04879";

axios
  .get(
    `https://api.seermartech.cn/v3/keywords_data/google_ads/` +
      `ad_traffic_by_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);
  });

响应示例

json

{
  "version": "0.1.20221214",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "06021415-1535-0111-0000-76d1e6dff5bc",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "keywords_data",
        "google_ads",
        "ad_traffic_by_keywords",
        "task_get",
        "06021415-1535-0111-0000-76d1e6dff5bc"
      ],
      "data": {
        "api": "keywords_data",
        "function": "ad_traffic_by_keywords",
        "se": "google_ads",
        "id": "06021415-1535-0111-0000-76d1e6dff5bc",
        "language_code": "en",
        "location_code": 2840,
        "bid": 999,
        "match": "exact",
        "keywords": [
          "seo tools"
        ]
      },
      "result": [
        {
          "keyword": "seo tools",
          "location_code": 2840,
          "language_code": "en",
          "date_interval": "next_month",
          "search_partners": false,
          "bid": 999,
          "match": "exact",
          "impressions": null,
          "ctr": null,
          "average_cpc": 12.35,
          "cost": 1235.0,
          "clicks": 100.0
        }
      ]
    }
  ]
}

状态码处理建议

建议根据顶层 status_code 和任务级别的 tasks[].status_code 分别处理请求异常：

20000：请求或任务处理成功。
任务级状态码异常时，应读取 tasks[].status_message。
当 result 为 null 或 result_count 为 0 时，应视为当前任务没有可用结果，并结合状态信息进行重试或排查。
生产环境建议记录任务 ID、状态码、状态信息和请求时间，便于追踪异步任务。

实用场景

评估广告需求：根据预测点击量、平均 CPC 和广告成本筛选高潜力，制定投放预算。
比较不同匹类型：对比 exact、phrase 和 broad 匹结果，确定顾流量规模与成本的匹策略。
制定地区化投放方案：按地区代码查询广告流量，识别不同市场的点击潜力和获客成本。
预测广告系列表现：批量获取整个广告系列的指标，提前估算点击量和预算消耗，支持投放计划评审。
优化 SEO 与付费搜索协同：将广告点击成本与自然搜索数据结合，识别适合通过 SEO 降低长期获客成本的。

按任务 ID 获取 Google Ads 广告流量结果 ​

接口信息 ​

计费说明 ​

请求参数 ​

响应结构 ​

顶层字段 ​

tasks 中的任务字段 ​

result 结果字段 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

状态码处理建议 ​

实用场景 ​