SeerMarTech API 文档

主题

数据 Google 广告流量按设备平台任务创建 ​

接口概述 ​

该接口用于创建 Google 广告流量按平台（desktop / mobile / tablet） 的异步任务。提交一组后，本平台会基于指定出价与匹类型，返回这组的整体广告流量估算数据：

  • 日均展示量预估
  • CPC 预估
  • 点击量预估
  • 按设备平台拆分的数据：桌面端 / 移动端 / 平板端

与 /v3/keywords_data/google/ad_traffic_by_keywords/task_post/ 不同，本接口返回的是整组的汇总结果，而不是按单个分别返回。

这是标准异步获取方式，适合不要求实时返回的场景： 创建任务，系统处理完成后，再通过结果接口、postback_url 或 pingback_url 获取结果。

如果你需要即时返回结果，建议使用 实时（Live）接口：/v3/keywords_data/google/ad_traffic_by_platforms/live/。

此外，你还可以通过 /v3/keywords_data/google/adwords_status/ 查看平台广告数据更新状态。

容性说明 ​

Google AdWords Keywords Data API 属于旧版能力，当前已由 Google Ads API 替代。若你正在使用旧版能力，建议迁移到新接口体系。

请求地址 ​

POST https://api.seermartech.cn/v3/keywords_data/google/ad_traffic_by_platforms/task_post

计费说明 ​

该接口按创建任务计费。

  • 单次任务参考价约 ¥0.8000 / 次
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

补限制：

  • 每分钟最多可发送 2000 次 API 调用
  • 每次 POST 最多 100 个任务 -过 100 个任务的部分会返回错误 40006
  • 单个 keywords 数组最多可传 2500 个
  • 无论数组中是 1 个还是 2500 个，单次请求价格相同

请求格式 ​

所有 POST 数据使用 JSON（UTF-8 编码）提交。

请求体格式为 JSON 数组：

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

请求参数 ​

任务对象字段说明 ​

字段名类型说明
keywordsarray填。数组。最多 2500 个；每个最长 80 个字符；每个词组最多 10 个单词。提交后系统会自动转为小写，结果按独立数组返回。
bidfloat填。自定义最高出价。采集结果将基于该值估算。你愿意支付的广告出价越高，通常可获得越高广告位与更高价格区间。
matchstring填。匹类型，可选值：exact、broad、phrase。
location_namestring可选。搜索引擎地域完整名称。若使用该字段，则无需传 location_code 或 location_coordinate。可通过 /v3/keywords_data/google/locations 获取可用地域列表。忽略该字段则返回数据。示例：London,England,United Kingdom
location_codeinteger可选。搜索引擎地域编码。若使用该字段，则无需传 location_name 或 location_coordinate。可通过 /v3/keywords_data/google/locations 获取可用地域编码。忽略该字段则返回数据。示例：2840
location_coordinatestring可选。地理坐标，格式为 "latitude,longitude"。若使用该字段，则无需传 location_name 或 location_code。结果将按该坐标所属国家返回。忽略该字段则返回数据。示例：52.6178549,-155.352142
language_namestring当未提供 language_code 时填。搜索引擎语言完整名称。若使用该字段，则无需传 language_code。可通过 /v3/keywords_data/google/languages 获取语言列表。示例：English
language_codestring当未提供 language_name 时填。搜索引擎语言代码。若使用该字段，则无需传 language_name。可通过 /v3/keywords_data/google/languages 获取语言代码。示例：en
postback_urlstring可选。任务完成后，系统会将结果以 gzip 压缩的 POST 请求发送到该地址。可在 URL 中使用 $id 作为任务 ID 变量，$tag 作为 URL 编码后的标签变量。示例：http://your-server.com/postbackscript?id=$id
pingback_urlstring可选。任务完成后，系统会向该地址发送 GET 请求通知。同样支持 $id 与 $tag 变量。示例：http://your-server.com/pingscript?id=$id&tag=$tag
tagstring可选。自定义任务标识，最长 255 个字符。便于你将任务结果与业务系统进行。该值会在响应的 data 对象中返回。

回调说明 ​

你可以通过以下方式获取结果：

  1. 使用任务唯一标识 id 主动获取结果
  2. 创建任务时传 postback_url
  3. 创建任务时传 pingback_url

注意：

  • 若你的服务器在 10 秒未响应 回调请求，连接会时中断
  • 任务会被转移到 tasks_ready 列表，供后续主动获取
  • 错误码与错误信息取决于你的服务器

响应结构 ​

接口返回 JSON 对象 tasks 数组。

顶层响应字段 ​

字段名类型说明
versionstringAPI 当前版本
status_codeinteger接口总体状态码
status_messagestring接口总体状态信息
timestring执行耗时，单位秒
costfloat本次请求总费用，单位 USD
tasks_countintegertasks 数组中的任务数量
tasks_errorinteger返回错误的任务数量
tasksarray任务结果数组

tasks 数组字段 ​

字段名类型说明
idstring系统中的唯一任务 ID，UUID 格式
status_codeinteger任务状态码，范围通常为 10000-60000
status_messagestring任务状态信息
timestring当前任务处理耗时
costfloat当前任务费用，单位 USD
result_countintegerresult 数组数量
patharray接口路径
dataobject你在请求中提交的任务参数
resultarray / null结果数组。对于任务创建接口，此处通常为 null

状态码说明 ​

  • 20000：请求成功
  • 20100：任务已创建
  • 40006：单次 POST 中任务数 100 个

建议在业务系统中对状态码和异常做好完整处理。

请求示例 ​

cURL ​

bash
curl --location --request POST "https://api.seermartech.cn/v3/keywords_data/google/ad_traffic_by_platforms/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_platforms/task_post"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

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=data)
print(response.json)

TypeScript ​

typescript
import axios from "axios";

const postArray = [
 {
 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({
 method: "post",
 url: "https://api.seermartech.cn/v3/keywords_data/google/ad_traffic_by_platforms/task_post",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: postArray
})
 .then((response) => {
 // 输出任务创建结果
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应示例 ​

json
{
 "version": "3.20191128",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1103 sec.",
 "cost": 0.15,
 "tasks_count": 3,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "01301300-1535-0112-0000-111111111111",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0020 sec.",
 "cost": 0.05,
 "result_count": 0,
 "path": [
 "v3",
 "keywords_data",
 "google",
 "ad_traffic_by_platforms",
 "task_post"
 ],
 "data": {
 "api": "keywords_data",
 "function": "ad_traffic_by_platforms",
 "se": "google",
 "location_name": "United States",
 "bid": 999,
 "match": "exact",
 "keywords": [
 "seo marketing"
 ]
 },
 "result": null
 },
 {
 "id": "01301300-1535-0112-0000-ce63ea88b374",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0021 sec.",
 "cost": 0.05,
 "result_count": 0,
 "path": [
 "v3",
 "keywords_data",
 "google",
 "ad_traffic_by_platforms",
 "task_post"
 ],
 "data": {
 "api": "keywords_data",
 "function": "ad_traffic_by_platforms",
 "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": "01301300-1535-0112-0000-2ecb01e8443e",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0020 sec.",
 "cost": 0.05,
 "result_count": 0,
 "path": [
 "v3",
 "keywords_data",
 "google",
 "ad_traffic_by_platforms",
 "task_post"
 ],
 "data": {
 "api": "keywords_data",
 "function": "ad_traffic_by_platforms",
 "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
 }
 ]
}

使用建议 ​

  • 需要获取整组在不同设备上的广告流量总览时，优使用本接口
  • 需要按逐条查看广告流量时，使用 /v3/keywords_data/google/ad_traffic_by_keywords/task_post/
  • 如果业务对返回时效要求高，优使用 Live 版本
  • 建议为异步任务统一 tag，便于与投放、报表或策略系统

实用场景 ​

  • 评估设备投放优级：按 desktop / mobile / tablet 查看一组核心词的流量潜力，帮助确定广告预算应优倾斜到哪个终端。
  • 验证组合价值：将同一专题下的多个作为一组提交，快速判断该主题整体是否值得投放或布局。
  • 制定区域化竞价策略：结合 location_name 或 location_code 比较不同地区的广告流量与点击潜力，优化本地化投放方案。
  • 监控大批量异步任务：通过 pingback_url 或 postback_url 批量回收任务结果，适合搭建自动化广告研究与 SEO 数据流水线。
  • 与商业词筛选：通过设置不同 match 和 bid，估算商业词组在各终端的竞争热度，为落地页、专题页和投放词提供依据。

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

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