SeerMarTech API 文档

主题

按任务 ID 获取 Google 广告平台流量估算结果 ​

接口说明 ​

GET /v3/keywords_data/google/ad_traffic_by_platforms/task_get/$id

本接口用于根据任务 ID 获取 Google 广告平台流量估算结果。对于一组，接口会分别返回桌面端、移动端和平板端的以下数据：

  • 广告展示位置
  • 平均每次点击费用（CPC）
  • 日均展示次数
  • 日均点击次数
  • 日均广告费用

该接口属于旧版 Google AdWords 数据接口，建议新项目优评估使用 Google Ads API。由于广告历史、账户素材及账户因素的影响，接口返回的估算值可能与规划中的数据不同。设置较高的 bid 有助于降低部分因素对估算结果的影响。

请求信息 ​

请求方法与路径 ​

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

路径参数 ​

参数类型说明
idstring任务唯一标识符，使用 UUID 格式。任务提交后，可在 30 天重复使用该 ID 获取结果。

请求头 ​

http
Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

本接口无需请求体。

计费说明 ​

  • 在提交任务时计费。
  • 任务结果可在任务提交后的 30 天查询。
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
  • 响应中的 cost 字段（平台原始 USD 成本兼容字段）表示任务成本，金额以本平台返回的人民币计费信息为准。

响应结构 ​

接口返回 JSON 数据，顶层 tasks 数组。每个任务对象任务状态、请求参数及对应结果。

顶层响应字段 ​

字段类型说明
versionstring当前 API 版本。
status_codeinteger通用响应状态码。建议根据状态码处理异常和错误。
status_messagestring通用状态说明。
timestring请求执行耗时，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_countintegertasks 数组中的任务数量。
tasks_errorintegertasks 数组中返回错误的任务数量。
tasksarray任务结果数组。

tasks 中的任务字段 ​

字段类型说明
idstring任务唯一标识符，UUID 格式。
status_codeinteger当前任务的状态码，通常在 10000 至 60000 范围。
status_messagestring当前任务的状态说明。
timestring任务执行耗时，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_countintegerresult 数组中的数量。
patharray请求 URL 路径。
dataobject创建任务时提交的参数。
resultarray广告流量估算结果。

data 字段 ​

data 字段通常创建任务时提交的原始参数，例如：

字段类型说明
apistringAPI 类型，例如 keywords_data。
functionstring接口功能名称，例如 ad_traffic_by_platforms。
sestring搜索引擎，例如 google。
language_codestring语言代码。
location_codeinteger地理位置代码。
bidfloat创建任务时设置的最高自定义出价。
matchstring匹类型。
keywordsarray请求中的列表。
tagstring用户自定义任务标签。

result 结果字段 ​

每个结果项通常 desktop、mobile 和 tablet 三个平台对象。

平台结果对象 ​

以下字段适用于：

  • desktop：桌面端结果
  • mobile：移动端结果
  • tablet：平板端结果
字段类型说明
location_codeinteger请求中的地理位置代码。无数据时为 null。
language_codestring请求中的语言代码。无数据时为 null。
bidfloat创建任务时设置的最高自定义出价，表示愿意为一次广告点击支付的最高价格。出价越高，通常可能获得更高的广告位置和对应费用。
keywordstring请求中的。移动端和平板端结果中的会对编码进行解码，+ 符号会被解码为空格。
matchstring匹类型，可取 exact、broad 或 phrase。
ad_position_minfloat最低广告位置。无数据时为 null。
ad_position_maxfloat最高广告位置。无数据时为 null。
ad_position_averagefloat平均广告位置。无数据时为 null。
cpc_minfloat历史最低平均每次点击费用，原始数据以计。无数据时为 null。
cpc_maxfloat历史最高平均每次点击费用，原始数据以计。无数据时为 null。
cpc_averagefloat历史平均每次点击费用，原始数据以计。无数据时为 null。
daily_impressions_minfloat预估最低日均展示次数。无数据时为 null。
daily_impressions_maxfloat预估最高日均展示次数。无数据时为 null。
daily_impressions_averagefloat预估平均日均展示次数。无数据时为 null。
daily_clicks_minfloat预估最低日均点击次数。无数据时为 null。
daily_clicks_maxfloat预估最高日均点击次数。无数据时为 null。
daily_clicks_averagefloat预估平均日均点击次数。无数据时为 null。
daily_cost_minfloat预估最低日均广告费用，原始数据以计。无数据时为 null。
daily_cost_maxfloat预估最高日均广告费用，原始数据以计。无数据时为 null。
daily_cost_averagefloat预估平均日均广告费用，原始数据以计。无数据时为 null。

请求示例 ​

curl ​

bash
id="02031639-0696-0112-0000-21d6ab6aa8f9"

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

TypeScript ​

typescript
import axios from "axios";

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

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

Python ​

python
import requests

task_id = "02031639-0696-0112-0000-21d6ab6aa8f9"

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

response = requests.get(
    url,
    headers={
        "Authorization": "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
    },
)

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')}"
    )

响应示例 ​

json
{
  "version": "3.20191128",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "1.6369 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "02031639-0696-0112-0000-21d6ab6aa8f9",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "1.6369 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "keywords_data",
        "google",
        "ad_traffic_by_platforms",
        "task_get"
      ],
      "data": {
        "api": "keywords_data",
        "function": "ad_traffic_by_platforms",
        "se": "google",
        "language_code": "en",
        "location_code": 2840,
        "bid": 999,
        "match": "exact",
        "keywords": [
          "example keyword"
        ],
        "tag": "tag1"
      },
      "result": [
        {
          "desktop": {
            "language_code": "en",
            "location_code": 2840,
            "bid": 999,
            "keyword": "example keyword",
            "match": "exact",
            "ad_position_min": 1.11,
            "ad_position_max": 1,
            "ad_position_average": 1.06,
            "cpc_min": 43.13,
            "cpc_max": 52.72,
            "cpc_average": 47.93,
            "daily_impressions_min": 82.74,
            "daily_impressions_max": 101.13,
            "daily_impressions_average": 91.94,
            "daily_clicks_min": 0.7,
            "daily_clicks_max": 0.86,
            "daily_clicks_average": 0.78,
            "daily_cost_min": 33.69,
            "daily_cost_max": 41.18,
            "daily_cost_average": 37.44
          },
          "mobile": {
            "language_code": "en",
            "location_code": 2840,
            "bid": 999,
            "keyword": "example keyword",
            "match": "exact",
            "ad_position_min": 1.11,
            "ad_position_max": 1,
            "ad_position_average": 1.06,
            "cpc_min": 32.31,
            "cpc_max": 39.49,
            "cpc_average": 35.9,
            "daily_impressions_min": 56.11,
            "daily_impressions_max": 68.58,
            "daily_impressions_average": 62.34,
            "daily_clicks_min": 0.4,
            "daily_clicks_max": 0.49,
            "daily_clicks_average": 0.45,
            "daily_cost_min": 14.44,
            "daily_cost_max": 17.64,
            "daily_cost_average": 16.04
          },
          "tablet": {
            "language_code": "en",
            "location_code": 2840,
            "bid": 999,
            "keyword": "example keyword",
            "match": "exact",
            "ad_position_min": 1.11,
            "ad_position_max": 1,
            "ad_position_average": 1.06,
            "cpc_min": 28.24,
            "cpc_max": 34.51,
            "cpc_average": 31.37,
            "daily_impressions_min": 1.55,
            "daily_impressions_max": 1.9,
            "daily_impressions_average": 1.73,
            "daily_clicks_min": 0.04,
            "daily_clicks_max": 0.04,
            "daily_clicks_average": 0.04,
            "daily_cost_min": 1.12,
            "daily_cost_max": 1.37,
            "daily_cost_average": 1.25
          }
        }
      ]
    }
  ]
}

状态码与异常处理 ​

  • 20000：请求成功。
  • 40000 及以上：任务处理失败或请求存在错误。
  • 应同时检查顶层 status_code、任务级 status_code 以及 status_message。
  • 当 result 为空或 result_count 为 0 时，应按“暂无可用结果”处理，不应直接视为接口异常。
  • 建议对网络时、无效任务 ID、任务尚未完成和任务过期等进行重试或异常记录。

实用场景 ​

  • 比较桌面端、移动端和平板端的广告流量：识别不同设备的展示、点击和成本差异，为设备出价调整提供依据。
  • 评估的广告获客潜力：结合日均展示次数、点击次数和 CPC 估算的潜在流量与投放成本。
  • 规划区域化搜索广告预算：按语言和地理位置获取广告估算结果，支持市场和区域预算分。
  • 优化匹策略：对比 exact、broad 和 phrase 匹类型的广告位置及流量表现，降低无效点击成本。
  • 建立广告投放预测模型：批量采集的最低、最高和平均估算指标，为预算模拟、投放回报预测和 SEO/PPC 协同分析提供数据。

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

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