按设置广告流量预测任务

POST /v3/keywords_data/google_ads/ad_traffic_by_keywords/task_post

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

/v3/keywords_data/google_ads/ad_traffic_by_keywords/task_post

通过本接口可以创建“按获取广告流量预测”任务，返回用于估算平均每次点击费用（CPC）、点击量及广告成本等指标的数据。相比常规搜索量，此类预测数据更适合评估的真实广告需求，因为常规搜索量通常基于相似的广泛匹估算。

> 自 6 月 1 日起，本接口返回整个广告系列的批量数据，即创建任务时指定的对应的数据。

本接口基于最新版 Google Ads API。预测结果与广告账户历史、账户中已有的广告素材及账户因素。建议使用较高的 bid，以降低这些因素对结果的影响。

预测时间范围

可以通过以下两种方式指定预测时间范围：

使用 date_from 和 date_to 指定明确的未来日期；
使用 date_interval 指定预设时间范围：
- next_week：未来一周
- next_month：未来一个月
- next_quarter：未来一个季度

如果未指定上述任一方式，默认使用 next_month。

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

使用本接口创建任务；
通过任务 ID 查询结果，或回调地址接收结果。

如果业务需要同步获取结果，可使用 Live 模式接口：

/v3/keywords_data/google_ads/ad_traffic_by_keywords/live

计费说明

在成功创建任务时计费，数组中 1 个或 1000 个的单次请求，计费方式相同。

参考价约 ¥0.36 / 任务。批量提交多个任务时，将任务数量计费；扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求限制

请求体使用 UTF-8 编码的 JSON。
请求体格式为 JSON 数组：[{ ... }]。平台限流以认证说明中的 30/60/120 次/分钟规则为准。
单次 POST 请求最多 100 个任务。 -过 100 个任务的部分会返回错误码 40006。
单个任务的 keywords 数组最多 1000 个。

请求参数

任务字段

字段	类型	填	说明
`keywords`	array	是	要预测的列表。最多 1000 个；每个最多 80 个字符、最多 10 个单词。提交后会转换为小写格式。
`bid`	float	是	自定义最高出价，表示愿意为一次广告点击支付的最高金额。该值越高，返回指标中的预测值通常越高。
`match`	string	是	匹类型。可选值：`exact`、`broad`、`phrase`。
`location_name`	string	否	搜索引擎位置的完整名称，例如 `London,England,United Kingdom`。未指定时返回范围结果。使用此字段后，无需再指定 `location_code` 或 `location_coordinate`。
`location_code`	integer	否	搜索引擎位置编码，例如 `2840`。未指定时返回范围结果。使用此字段后，无需再指定 `location_name` 或 `location_coordinate`。
`location_coordinate`	string	否	位置 GPS 坐标，格式为 `"纬度,经度"`，例如 `52.6178549,-155.352142`。数据将该坐标所属国家返回。使用此字段后，无需再指定 `location_name` 或 `location_code`。
`language_name`	string	否	搜索引擎语言的完整名称，例如 `English`。
`language_code`	string	否	搜索引擎语言代码，例如 `en`。
`date_from`	string	条件填	预测时间范围的起始日期。指定 `date_to` 时同时指定。格式为 `yyyy-mm-dd`。如果同时指定 `date_from` 和 `date_to`，无需指定 `date_interval`。
`date_to`	string	条件填	预测时间范围的结束日期。指定 `date_from` 时同时指定。格式为 `yyyy-mm-dd`。如果同时指定 `date_from` 和 `date_to`，无需指定 `date_interval`。
`date_interval`	string	否	预设预测时间范围。可选值：`next_week`、`next_month`、`next_quarter`。默认值为 `next_month`。指定后无需设置 `date_from` 和 `date_to`。
`sort_by`	string	否	结果排序字段。可选值：`relevance`、`average_cpc`、`cost`、`clicks`。结果按降序排列。默认值为 `relevance`。
`postback_url`	string	否	任务完成后接收结果的 URL。本平台会向该地址发送结果的 gzip 压缩 POST 请求。
`pingback_url`	string	否	任务完成通知 URL。任务完成后，本平台会向该地址发送 GET 请求。
`tag`	string	否	用户自定义任务标识，最多 255 个字符。可用于任务与结果，提交的值会出现在响应的 `data` 对象中。

限制

某些组合可能没有可用数据。
对于相似，广告平台可能返回合并后的搜索量。
如需分别获取相似的搜索量，建议将拆分到不同请求中。
不支持部分特殊符号和字符，例如某些 Unicode 符号及表符号。
请确保符合广告平台的字符、长度和格式限制。

地区参数说明

可以通过位置列表接口获取可用的地区名称和地区编码：

/v3/keywords_data/google_ads/locations

地区字段三选一：

location_name
location_code
location_coordinate

如果未提供任何地区字段，接口将返回范围结果。

语言参数说明

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

/v3/keywords_data/google_ads/languages

语言字段可使用：

language_name
language_code

日期参数规则

使用明确日期

当同时设置 date_from 和 date_to 时：

date_from 不得晚于 date_to；
date_from 的最小值通常为明天；
date_to 至少为 date_from 加 1 天；
date_to 的最大范围为当前日期至下一年同月；
日期格式为 yyyy-mm-dd。

示例：

json

{
  "date_from": "2021-10-30",
  "date_to": "2022-10-30"
}

使用预设区间

json

{
  "date_interval": "next_month"
}

如果未设置 date_from、date_to 或 date_interval，系统默认使用：

text

next_month

回调通知

`postback_url`

任务完成后，本平台会向 postback_url 发送 POST 请求，正文为 gzip 压缩格式。

可以在 URL 中使用以下变量：

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

示例：

text

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

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

`pingback_url`

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

示例：

text

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

如果回调服务器在 10 秒未返回响应，连接将因时中止，任务会转移到处理任务列表：

/v3/keywords_data/google_ads/ad_traffic_by_keywords/tasks_ready

请求示例

curl

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/keywords_data/google_ads/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_code": "en",
      "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_ads/ad_traffic_by_keywords/task_post"

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

# 请求体是 JSON 数组
payload = [
    {
        "location_name": "United States",
        "language_code": "en",
        "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=payload, timeout=30)
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 endpoint =
  "https://api.seermartech.cn/v3/keywords_data/google_ads/ad_traffic_by_keywords/task_post";

// 请求体是 JSON 数组
const payload = [
  {
    location_name: "United States",
    language_code: "en",
    bid: 999.0,
    match: "exact",
    keywords: ["seo marketing"],
  },
  {
    location_code: 2840,
    language_code: "en",
    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(endpoint, payload, {
    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 数组每个对应一个已提交任务。

顶层响应字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	请求级状态码。`20000` 表示请求成功。
`status_message`	string	请求级状态说明。
`time`	string	请求执行耗时，例如 `0.1169 sec.`。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务总数。
`tasks_error`	integer	返回错误的任务数量。
`tasks`	array	任务结果数组。

任务字段

字段	类型	说明
`id`	string	任务唯一标识，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.1169 sec.",
  "cost": 0.15,
  "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.05,
      "result_count": 0,
      "path": [
        "v3",
        "keywords_data",
        "google_ads",
        "ad_traffic_by_keywords",
        "task_post"
      ],
      "data": {
        "api": "keywords_data",
        "function": "ad_traffic_by_keywords",
        "se": "google_ads",
        "location_name": "United States",
        "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.05,
      "result_count": 0,
      "path": [
        "v3",
        "keywords_data",
        "google_ads",
        "ad_traffic_by_keywords",
        "task_post"
      ],
      "data": {
        "api": "keywords_data",
        "function": "ad_traffic_by_keywords",
        "se": "google_ads",
        "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，并使用该 ID 查询任务结果。也可以通过 postback_url 或 pingback_url 接收完成通知。

实用场景

预测广告点击量：在投放前估算目标的潜在点击量，制定预算和投放规模。
比较不同出价策略：使用不同的 bid 创建预测任务，评估出价变化对 CPC、成本和点击量的影响。
筛选高价值：按 average_cpc、cost 或 clicks 对结果排序，优选择流量和成本更符合目标的。
规划地区化广告投放：结合 location_name、location_code 或坐标，对不同国家、城市或市场进行广告需求预测。
批量生成广告预算模型：一次提交多组和匹类型，批量获取整组广告系列的预测数据，为 SEO 与付费搜索协同规划提供依据。

按设置广告流量预测任务 ​

预测时间范围 ​

计费说明 ​

请求限制 ​

请求参数 ​

任务字段 ​

限制 ​

地区参数说明 ​

语言参数说明 ​

日期参数规则 ​

使用明确日期 ​

使用预设区间 ​

回调通知 ​

postback_url ​

pingback_url ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应说明 ​

顶层响应字段 ​

任务字段 ​

响应示例 ​

实用场景 ​

按设置广告流量预测任务

预测时间范围

计费说明

请求限制

请求参数

任务字段

限制

地区参数说明

语言参数说明

日期参数规则

使用明确日期

使用预设区间

回调通知

`postback_url`

`pingback_url`

请求示例

curl

Python

TypeScript

响应说明

顶层响应字段

任务字段

响应示例

实用场景