SeerMarTech API 文档

主题

Google 广告流量估算（实时） ​

本接口使用 POST 方法，路径为：

/v3/keywords_data/google/ad_traffic_by_keywords/live

完整请求地址：

https://api.seermartech.cn/v3/keywords_data/google/ad_traffic_by_keywords/live

本接口用于实时获取 Google 广告的流量预估数据每日展示次数、点击次数、点击单价（CPC）、广告排名及每日费用等指标。与常规搜索量相比，该数据针对单个进行估算，更适合评估的真实商业需求。

该接口为实时接口，提交请求后会直接返回结果，无需另外调用任务查询接口。

> 提示：广告流量估算可能受到广告账户历史、广告素材及账户因素影响。提高 bid 值有助于降低这些因素对估算结果的影响。

如果不要求实时返回结果，可使用标准任务接口：

/v3/keywords_data/google/ad_traffic_by_keywords/task_post

标准接口需要分别提交任务和获取结果，但通常成本更低。

计费说明 ​

  • 每次请求单独计费，与一次请求中的数量无。
  • 单次请求最多提交 2500 个，提交 1 个或 2500 个的请求计费规则相同。
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
  • 单个请求最多返回每个对应的一组估算数据。 平台限流以认证说明中的 30/60/120 次/分钟规则为准。

请求参数 ​

请求体使用 UTF-8 编码的 JSON 数组格式：

json
[
  {
    "keywords": ["seo marketing"],
    "bid": 999.00,
    "match": "exact",
    "location_name": "United States",
    "language_name": "English"
  }
]

任务参数 ​

参数类型填说明
keywordsarray是要查询的列表。最多 2500 个；每个最多 80 个字符、最多 10 个单词。提交的会被转换为小写，结果将在独立数组中返回。
bidfloat是自定义最高出价，表示愿意为广告支付的最高价格。该值越高，预估广告排名和费用通常越高。
matchstring是匹类型。可选值：exact、broad、phrase。
location_namestring否搜索引擎地域的完整名称。使用此参数后，不得同时传 location_code 或 location_coordinate。省略时返回结果。
location_codeinteger否搜索引擎地域编码。使用此参数后，不得同时传 location_name 或 location_coordinate。省略时返回结果。
location_coordinatestring否地理坐标，格式为 纬度,经度。使用此参数后，不得同时传 location_name 或 location_code。数据将以该坐标所属国家为地域范围。省略时返回结果。
language_namestring条件填搜索引擎语言名称。未指定 language_code 时填。使用此参数后，不得同时传 language_code。
language_codestring条件填搜索引擎语言编码。未指定 language_name 时填。使用此参数后，不得同时传 language_name。
tagstring否用户自定义任务标识，最多 255 个字符。可用于请求和结果，提交的值会在响应的 data 对象中返回。

地域参数示例 ​

json
{
  "location_name": "London,England,United Kingdom"
}
json
{
  "location_code": 2840
}
json
{
  "location_coordinate": "52.6178549,-155.352142"
}

可通过以下接口查询可用地域：

/v3/keywords_data/google/locations

语言参数示例 ​

json
{
  "language_name": "English"
}
json
{
  "language_code": "en"
}

可通过以下接口查询可用语言：

/v3/keywords_data/google/languages

响应结构 ​

接口返回 JSON 对象 tasks 数组。

顶层字段 ​

字段类型说明
versionstring当前 API 版本。
status_codeinteger请求总体状态码。20000 表示成功。
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广告流量估算结果。

result 结果字段 ​

字段类型说明
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。

金额字段的货币单位以接口返回及账户结算口径为准；平台请求扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求示例 ​

cURL ​

bash
curl --location --request POST \
  "https://api.seermartech.cn/v3/keywords_data/google/ad_traffic_by_keywords/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "location_name": "United States",
      "language_name": "English",
      "bid": 999.00,
      "match": "exact",
      "keywords": [
        "seo marketing"
      ]
    }
  ]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/keywords_data/google/ad_traffic_by_keywords/live"

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

payload = [
    {
        "location_name": "United States",
        "language_name": "English",
        "bid": 999.00,
        "match": "exact",
        "keywords": [
            "seo marketing"
        ],
    }
]

response = requests.post(url, headers=headers, json=payload)
result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败，状态码：%s，信息：%s"
        % (result.get("status_code"), result.get("status_message"))
    )

TypeScript ​

typescript
import axios from "axios";

const payload = [
  {
    location_name: "United States",
    language_name: "English",
    bid: 999.00,
    match: "exact",
    keywords: ["seo marketing"],
  },
];

axios({
  method: "post",
  url: "https://api.seermartech.cn/v3/keywords_data/google/ad_traffic_by_keywords/live",
  headers: {
    Authorization: "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
  },
  data: payload,
})
  .then((response) => {
    // 处理接口返回结果
    console.log(response.data);
  })
  .catch((error) => {
    console.error("请求失败：", error.response?.data || error.message);
  });

响应示例 ​

json
{
  "version": "3.20191128",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "1.5868 sec.",
  "cost": 0.075,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "1.5000 sec.",
      "cost": 0.075,
      "result_count": 1,
      "path": [
        "v3",
        "keywords_data",
        "google",
        "ad_traffic_by_keywords",
        "live"
      ],
      "data": {
        "api": "keywords_data",
        "function": "ad_traffic_by_keywords",
        "se": "google",
        "language_code": "en",
        "location_code": 2840,
        "bid": 999,
        "match": "exact",
        "keywords": [
          "seo marketing"
        ]
      },
      "result": [
        {
          "location_code": 2840,
          "language_code": "en",
          "bid": 999,
          "keyword": "seo marketing",
          "match": "exact",
          "ad_position_min": 1.0,
          "ad_position_max": 2.0,
          "ad_position_average": 1.5,
          "cpc_min": 1.2,
          "cpc_max": 3.5,
          "cpc_average": 2.1,
          "daily_impressions_min": 100,
          "daily_impressions_max": 500,
          "daily_impressions_average": 300,
          "daily_clicks_min": 5,
          "daily_clicks_max": 25,
          "daily_clicks_average": 15,
          "daily_cost_min": 10,
          "daily_cost_max": 80,
          "daily_cost_average": 45
        }
      ]
    }
  ]
}

错误处理 ​

请根据顶层或任务级别的 status_code 和 status_message 判断请求是否成功：

  • 顶层 status_code 表示整个 API 请求的处理结果。
  • tasks[].status_code 表示单个任务的处理结果。
  • tasks_error 表示返回错误的任务数量。
  • 建议对网络异常、参数校验失败、地域或语言不存在、结果为空等进行单独处理。
  • 完整状态码列表请参考错误码文档。

实用场景 ​

  • 评估广告需求：根据每日展示、点击和 CPC 区间筛选高商业价值，为 SEO 与付费投放确定优级。
  • 测算投放预算：利用每日点击次数与每日费用区间估算广告预算，制定月度获客成本目标。
  • 比较不同地域市场：按 location_name、location_code 或坐标查询同一在不同市场的广告排名和流量差异，支持市场拓展决策。
  • 优化匹策略：对比 exact、phrase 和 broad 三种匹类型的展示、点击与成本预估，降低无效流量占比。
  • 建立商业优级模型：结合广告排名、平均 CPC、日均展示和日均点击等指标，为库生成可量化的投放与建设评分。

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

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