SeerMarTech API 文档

主题

Google 广告流量任务创建 ​

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

/v3/keywords_data/google/ad_traffic_by_keywords/task_post

本接口用于创建 Google 广告流量估算任务，返回指定的预计日均展示次数、每次点击费用（CPC）和点击次数等数据。与常规搜索量数据相比，该结果基于和出价条件进行估算，更适合评估单个的真实广告需求。

> 说明：本接口属于旧版 Google 广告数据能力，建议新项目优使用 Google Ads API 对应能力。

使用方式 ​

本接口采用异步任务模式：

  1. 通过本接口提交任务。
  2. 使用响应中的任务 ID 获取任务结果。
  3. 也可以在创建任务时 postback_url 或 pingback_url，由本平台在任务完成后主动通知。

如果业务需要实时返回结果，可使用 Live 方法对应接口，而无需分别调用任务创建和结果获取接口。

任务执行时间取决于系统负载。每个的结果会以数组形式返回。

请求限制 ​

  • 请求体使用 UTF-8 编码的 JSON。
  • 请求体格式为 JSON 数组：[{ ... }]。 平台限流以认证说明中的 30/60/120 次/分钟规则为准。
  • 每次请求最多 100 个任务。 -过 100 个任务的部分将返回错误码 40006。
  • 单个任务的 keywords 数组最多 2500 个。
  • 无论一个任务 1 个还是 2500 个，均按任务请求计费，而不是按数量计费。
  • 长度最多 80 个字符。
  • 每个短语最多 10 个单词。
  • 平台会将提交的转换为小写，并在结果中按独立数组返回。

计费说明 ​

创建任务时即产生费用，后续获取结果不会重复收取任务创建费用。

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。响应中的 cost 字段（平台原始 USD 成本兼容字段）表示本次任务或任务集合的费用，金额单位为人民币。

请求参数 ​

参数类型填说明
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。
postback_urlstring否任务完成后的结果回调地址。本平台会向该地址发送 POST 请求，结果以 gzip 格式压缩。
pingback_urlstring否任务完成通知地址。本平台会向该地址发送 GET 请求。
tagstring否用户自定义任务标识，最多 255 个字符。可用于任务和结果，提交的值会出现在响应的 data 对象中。

地域参数说明 ​

location_name、location_code 和 location_coordinate 三只能选择一。

可通过以下接口获取可用地域：

GET https://api.seermartech.cn/v3/keywords_data/google/locations

示例：

  • location_name：London,England,United Kingdom
  • location_code：2840
  • location_coordinate：52.6178549,-155.352142

语言参数说明 ​

language_name 和 language_code须二选一。

可通过以下接口获取可用语言：

GET https://api.seermartech.cn/v3/keywords_data/google/languages

示例：

  • language_name：English
  • language_code：en

回调参数说明 ​

postback_url 和 pingback_url 支持以下占位符：

  • $id：任务 ID
  • $tag：经过 URL 编码的任务标签

本平台会在发送请求前替换这些占位符。

postback_url 示例：

text
https://your-server.com/postbackscript?id=$id&tag=$tag

任务完成后，本平台会向该地址发送 POST 请求，并在请求体中提供 gzip 压缩后的结果。

pingback_url 示例：

text
https://your-server.com/pingscript?id=$id&tag=$tag

任务完成后，本平台会向该地址发送 GET 请求。

> 注意：回调地址中的特殊字符会进行 URL 编码，例如 # 会编码为 %23。如果接收服务器在 10 秒未响应，连接将因时中断，任务会转处理任务列表。错误码和错误信息取决于接收服务器的。

请求示例 ​

curl ​

bash
curl --location --request POST \
  "https://api.seermartech.cn/v3/keywords_data/google/ad_traffic_by_keywords/task_post" \
  --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"
      ]
    },
    {
      "language_code": "en",
      "location_code": 2840,
      "bid": 999.00,
      "match": "exact",
      "keywords": [
        "seo marketing"
      ],
      "tag": "some_string_123",
      "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
    },
    {
      "location_name": "United States",
      "language_name": "English",
      "bid": 999.00,
      "match": "exact",
      "keywords": [
        "seo marketing"
      ],
      "postback_url": "https://your-server.com/postbackscript"
    }
  ]'

Python ​

python
import requests

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

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

post_data = [
    {
        "location_name": "United States",
        "language_name": "English",
        "bid": 999.00,
        "match": "exact",
        "keywords": ["seo marketing"],
    },
    {
        "language_code": "en",
        "location_code": 2840,
        "bid": 999.00,
        "match": "exact",
        "keywords": ["seo marketing"],
        "tag": "some_string_123",
        "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag",
    },
    {
        "location_name": "United States",
        "language_name": "English",
        "bid": 999.00,
        "match": "exact",
        "keywords": ["seo marketing"],
        "postback_url": "https://your-server.com/postbackscript",
    },
]

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

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败，错误码：{}，错误信息：{}".format(
            result.get("status_code"),
            result.get("status_message"),
        )
    )

TypeScript ​

typescript
import axios from "axios";

const postData = [
  {
    location_name: "United States",
    language_name: "English",
    bid: 999.0,
    match: "exact",
    keywords: ["seo marketing"],
  },
  {
    language_code: "en",
    location_code: 2840,
    bid: 999.0,
    match: "exact",
    keywords: ["seo marketing"],
    tag: "some_string_123",
    pingback_url:
      "https://your-server.com/pingscript?id=$id&tag=$tag",
  },
  {
    location_name: "United States",
    language_name: "English",
    bid: 999.0,
    match: "exact",
    keywords: ["seo marketing"],
    postback_url: "https://your-server.com/postbackscript",
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/keywords_data/google/ad_traffic_by_keywords/task_post",
    postData,
    {
      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 对象任务集合 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 数组中的数量。任务刚创建时通常为 0。
patharray请求路径信息。
dataobject创建任务时提交的参数，以及系统补的接口信息。
resultarray/null任务结果。任务创建成功但尚未完成时为 null。

错误码和状态信息请参考错误码文档。

响应示例 ​

json
{
  "version": "3.20191128",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.1169 sec.",
  "cost": 1.08,
  "tasks_count": 3,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01301455-1535-0111-0000-0e193f50bc50",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0021 sec.",
      "cost": 0.36,
      "result_count": 0,
      "path": [
        "v3",
        "keywords_data",
        "google",
        "ad_traffic_by_keywords",
        "task_post"
      ],
      "data": {
        "api": "keywords_data",
        "function": "ad_traffic_by_keywords",
        "se": "google",
        "location_name": "United States",
        "language_name": "English",
        "bid": 999,
        "match": "exact",
        "keywords": [
          "seo marketing"
        ]
      },
      "result": null
    },
    {
      "id": "01301455-1535-0111-0000-1a12b9e9ee45",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0020 sec.",
      "cost": 0.36,
      "result_count": 0,
      "path": [
        "v3",
        "keywords_data",
        "google",
        "ad_traffic_by_keywords",
        "task_post"
      ],
      "data": {
        "api": "keywords_data",
        "function": "ad_traffic_by_keywords",
        "se": "google",
        "language_code": "en",
        "location_code": 2840,
        "bid": 999,
        "match": "exact",
        "keywords": [
          "seo marketing"
        ],
        "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag",
        "tag": "some_string_123"
      },
      "result": null
    },
    {
      "id": "01301455-1535-0111-0000-2b23c6a0ee56",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0020 sec.",
      "cost": 0.36,
      "result_count": 0,
      "path": [
        "v3",
        "keywords_data",
        "google",
        "ad_traffic_by_keywords",
        "task_post"
      ],
      "data": {
        "api": "keywords_data",
        "function": "ad_traffic_by_keywords",
        "se": "google",
        "location_name": "United States",
        "language_name": "English",
        "bid": 999,
        "match": "exact",
        "keywords": [
          "seo marketing"
        ],
        "postback_url": "https://your-server.com/postbackscript"
      },
      "result": null
    }
  ]
}

> 上述响应中的金额为示例值。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

状态码与异常处理 ​

  • 20000：请求成功。
  • 20100：任务创建成功。
  • 40006：单次请求提交的任务数量 100 个。
  • 状态码：请根据响应中的 status_code 和 status_message 处理异常。

建议客户端对以下进行处理：

  • HTTP 请求时或网络异常。
  • 顶层请求失败。
  • 个别任务创建失败。
  • 回调服务器未在 10 秒返回响应。
  • 任务结果为空或仍处于处理中。

实用场景 ​

  • 评估广告需求：根据指定出价、地域和语言获取展示量、CPC 与点击量估算，为 SEO 与广告预算分提供依据。
  • 筛选高潜力：批量提交最多 2500 个，对比不同的广告流量预估，优建设搜索需求高且竞争可控的主题。
  • 制定地域化 SEO 策略：按国家、城市或坐标提交任务，识别不同市场的需求差异，支持本地化落地页和区域规划。
  • 比较匹类型效果：分别使用 exact、phrase 和 broad 匹类型，分析覆盖范围与预估流量差异，优化分组策略。
  • 构建异步数据管道：通过 postback_url 或 pingback_url 接收任务完成通知，将广告流量估算结果自动写库、报表系统或 SEO 决策平台。

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

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