设置 Google 广告按平台流量预估任务

接口说明

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

Google AdWords 数据接口属于旧版接口，建议迁移至 Google Ads API。

本接口用于为一组创建广告流量预估任务，并返回桌面端、移动端和平板端的预估数据：

每日展示次数
每次点击费用（CPC）
每日点击次数

与按分别返回数据的 ad_traffic_by_keywords 接口不同，本接口返回整组的汇总数据。

本接口采用标准任务模式：

通过 POST 请求创建任务；
获取任务 ID；
使用任务 ID 查询结果，或通过 postback_url / pingback_url 接收任务完成通知。

如果业务需要实时返回结果，可使用对应的 Live 接口。

计费说明

在成功创建任务时计费。
一个任务最多 2500 个，无论数量是 1 个还是 2500 个，单次请求价格相同。
参考价约 ¥0.36 / 任务。
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。平台限流以认证说明中的 30/60/120 次/分钟规则为准。
单次 POST 请求最多 100 个任务； 100 个任务的部分将返回错误码 40006。

请求格式

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

json

[
  {
    "keywords": ["seo marketing"],
    "bid": 999.00,
    "match": "exact",
    "location_name": "United States",
    "language_code": "en"
  }
]

请求参数

参数	类型	填	说明
`keywords`	array	是	数组。最多 2500 个；每个最多 80 个字符、10 个单词。系统会将转换为小写，并在结果中以独立数组返回。
`bid`	float	是	最高自定义出价。系统将基于该值计算广告数据。出价越高，预计广告排名和费用通常越高。
`match`	string	是	匹类型。可选值：`exact`、`broad`、`phrase`。
`location_name`	string	否	搜索引擎位置的完整名称。使用此参数时，不要同时传 `location_code` 或 `location_coordinate`。省略时返回结果。
`location_code`	integer	否	搜索引擎位置代码。使用此参数时，不要同时传 `location_name` 或 `location_coordinate`。省略时返回结果。
`location_coordinate`	string	否	位置的 GPS 坐标，格式为 `纬度,经度`。数据将该坐标所属国家计算。使用此参数时，不要同时传 `location_name` 或 `location_code`。
`language_name`	string	条件填	搜索引擎语言名称。未传 `language_code` 时填。使用此参数时，不要同时传 `language_code`。
`language_code`	string	条件填	搜索引擎语言代码。未传 `language_name` 时填。使用此参数时，不要同时传 `language_name`。
`postback_url`	string	否	任务完成后接收结果的回调地址。本平台将向该地址发送任务结果的 gzip 压缩 POST 请求。
`pingback_url`	string	否	任务完成后的通知地址。本平台将向该地址发送 GET 请求。
`tag`	string	否	自定义任务标识，最多 255 个字符。可用于匹任务与结果，指定的值会在响应的 `data` 对象中返回。

地理位置参数

可以通过以下接口获取可用的位置名称和位置代码：

text

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

示例：

text

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

语言参数

可以通过以下接口获取可用的语言名称和语言代码：

text

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

示例：

text

language_name: English
language_code: en

回调地址参数

postback_url 和 pingback_url 支持以下变量：

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

示例：

text

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

回调地址中的特殊字符会进行 URL 编码，例如 # 会编码为 %23。

如果回调服务器在 10 秒未响应，连接将因时中断，任务会转移至任务就绪列表。服务器返回的错误码和错误信息取决于回调服务端。

认证方式

请求头使用 Bearer Token：

http

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

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"
      ]
    },
    {
      "location_code": 2840,
      "language_code": "en",
      "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",
}

post_data = [
    {
        "location_name": "United States",
        "language_name": "English",
        "bid": 999.00,
        "match": "exact",
        "keywords": ["seo marketing"],
    },
    {
        "location_code": 2840,
        "language_code": "en",
        "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(
        "请求失败。错误码：%s，错误信息：%s"
        % (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.00,
    match: "exact",
    keywords: ["seo marketing"],
  },
  {
    location_code: 2840,
    language_code: "en",
    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",
  },
];

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

PHP 示例

php

<?php

$url = "https://api.seermartech.cn/v3/keywords_data/google/ad_traffic_by_platforms/task_post";

$postData = [
    [
        "location_name" => "United States",
        "language_name" => "English",
        "bid" => 999.00,
        "match" => "exact",
        "keywords" => ["seo marketing"]
    ],
    [
        "location_code" => 2840,
        "language_code" => "en",
        "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"
    ]
];

$ch = curl_init($url);

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer smt_live_YOUR_KEY",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode($postData, JSON_UNESCAPED_UNICODE)
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);

if (($result["status_code"] ?? null) === 20000) {
    print_r($result);
} else {
    echo "请求失败：";
    print_r($result);
}

响应结构

接口返回 JSON 对象 tasks 数组。

顶层字段

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

任务字段

字段	类型	说明
`id`	string	系统生成的唯一任务 ID，采用 UUID 格式。
`status_code`	integer	任务状态码，通常位于 `10000` 至 `60000` 范围。
`status_message`	string	任务状态信息。
`time`	string	任务执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量。创建任务时通常为 `0`。
`path`	array	任务的 URL 路径信息。
`data`	object	创建任务时提交的参数，同时接口上下文信息。
`result`	array/null	任务结果。创建任务成功后为 `null`，需要后续获取任务结果。

成功响应示例

json

{
  "version": "3.20191128",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.1103 sec.",
  "cost": 1.08,
  "tasks_count": 3,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01301300-1535-0112-0000-ce63ea88b374",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0021 sec.",
      "cost": 0.36,
      "result_count": 0,
      "path": [],
      "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"
        ]
      },
      "result": null
    },
    {
      "id": "01301300-1535-0112-0000-ce63ea88b375",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0021 sec.",
      "cost": 0.36,
      "result_count": 0,
      "path": [],
      "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.36,
      "result_count": 0,
      "path": [],
      "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
    }
  ]
}

状态码与错误处理

20000：请求成功。
20100：任务已创建。
40006：单次请求中的任务数量 100 个。
错误码：请根据响应中的 status_code 和 status_message 进行处理。

建议客户端对以下进行容错：

HTTP 请求时或网络中断；
顶层 status_code 或任务级 status_code 非成功状态；
tasks_error 大于 0；
回调服务器未在 10 秒响应；
任务结果为空或暂未生成。

实用场景

比较桌面端、移动端和平板端的广告流量潜力，帮助 SEO 和投放团队确定优优化的平台。
批量评估一组的广告展示、点击和 CPC 预估，支持拓展与投放预算规划。
按国家、城市和语言创建区域化任务，为多地区 SEO 策略和本地广告市场分析提供数据依据。
使用不同匹类型和出价进行组合测试，评估精确匹、词组匹和广泛匹对流量及成本的影响。
通过回调地址自动接收任务完成通知，减少轮询开销并加快研究和竞品分析流程。

设置 Google 广告按平台流量预估任务 ​

接口说明 ​

计费说明 ​

请求格式 ​

请求参数 ​

地理位置参数 ​

语言参数 ​

回调地址参数 ​

认证方式 ​

curl 示例 ​

Python 示例 ​

TypeScript 示例 ​

PHP 示例 ​

响应结构 ​

顶层字段 ​

任务字段 ​

成功响应示例 ​

状态码与错误处理 ​

实用场景 ​

设置 Google 广告按平台流量预估任务

接口说明

计费说明

请求格式

请求参数

地理位置参数

语言参数

回调地址参数

认证方式

curl 示例

Python 示例

TypeScript 示例

PHP 示例

响应结构

顶层字段

任务字段

成功响应示例

状态码与错误处理

实用场景