数据 / Google / 按获取广告流量预估 / 创建任务

POST /v3/keywords_data/google/ad_traffic_by_keywords/task_post

接口概述

/v3/keywords_data/google/ad_traffic_by_keywords/task_post 用于提交“按获取广告流量预估”任务。

该接口可返回指定的广告流量预估数据：

• 日均展示量（impressions）
• 平均点击价格预估（CPC）
• 点击量预估（clicks）

这类数据适合用于评估的真实广告需求。相比常规搜索量数据通常基于相近词组的广泛匹估算，本接口返回的级广告流量预估通常更适合投放测算与商业价值判断。

这是标准异步任务模式：

1. 调用本接口创建任务；
2. 等平台处理完成；
3. 再通过对应结果接口、任务 ID，或回调方式获取结果。

如果你需要实时返回结果，建议改用 实时（Live）方式：/v3/keywords_data/google/ad_traffic_by_keywords/live/。

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

说明：该能力属于旧版广告数据接口体系，已逐步由新版 Google Ads 接口替代；如为新接，建议优评估新版容接口。

请求信息

POSThttps://api.seermartech.cn/v3/keywords_data/google/ad_traffic_by_keywords/task_post

计费说明

本接口在成功创建任务时扣费。

• 单任务平台价格示例：USD 0.05
• 参考价约：¥0.8000 / 次
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

计费按请求中的任务数计算，而不是按 keywords 数组中的数量计算。 单个任务中无论提交 1 个还是 2500 个，任务价格一致。

使用限制

• 每分钟最多可发送 2000 次 API 调用
• 每次 POST 最多 100 个任务
• 如果单次 POST 中任务数 100，出的任务将返回错误 40006
• 单个任务的 keywords 数组最多支持 2500 个
• 单个最大 80 个字符
• 单个短语最多 10 个单词

回调与结果获取

任务提交后，你可以通过以下方式获取结果：

• 使用任务唯一 ID 获取结果
• 设置 postback_url，任务完成后平台将以 POST 方式推送结果
• 设置 pingback_url，任务完成后平台将以 GET 方式发送通知

注意事项：

• 如果你的服务器在 10 秒未响应，连接会时中断
• 未成功投递的任务会 /v3/keywords_data/google/ad_traffic_by_keywords/tasks_ready/ 列表，供后续拉取
• 实错误码和错误信息取决于你的服务端
• postback_url 与 pingback_url 中的特殊字符会进行 URL 编码，例如 # 会被编码为 %23

请求体格式

POST 请求体为 JSON 数组，格式如下：

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

---

请求参数

任务对象字段说明

字段名	类型	填	说明
keywords	array	是	数组。最多 2500 个；每个最多 80 个字符；每个短语最多 10 个单词。提交后会自动转为小写，返回结果会按单个分别给出。
bid	float	是	自定义最高出价。平台将基于该出价值采集并估算数据。通常出价越高，可对应更高广告位与更高价格区间。
match	string	是	匹类型，可选值：exact、broad、phrase
location_name	string	否	搜索引擎地区完整名称。使用该字段时，无需再传 location_code 或 location_coordinate。忽略时默认返回数据。示例：London,England,United Kingdom
location_code	integer	否	搜索引擎地区编码。使用该字段时，无需再传 location_name 或 location_coordinate。忽略时默认返回数据。示例：2840
location_coordinate	string	否	地理坐标，格式为 latitude,longitude。使用该字段时，无需再传 location_name 或 location_code。返回数据对应坐标所属国家。示例：52.6178549,-155.352142
language_name	string	条件填	搜索引擎语言完整名称；当未传 language_code 时填。使用该字段时，无需再传 language_code。示例：English
language_code	string	条件填	搜索引擎语言代码；当未传 language_name 时填。使用该字段时，无需再传 language_name。示例：en
postback_url	string	否	任务完成后，平台将以 POST 请求把结果（gzip 压缩）发送到该地址。支持使用 $id 和 $tag 变量。示例：http://your-server.com/postbackscript?id=$id&tag=$tag
pingback_url	string	否	任务完成后，平台将以 GET 请求通知该地址。支持使用 $id 和 $tag 变量。示例：http://your-server.com/pingscript?id=$id&tag=$tag
tag	string	否	用户自定义任务标识，最长 255 个字符。可用于请求结果对账与业务追踪，返回时会出现在响应 data 对象中。

地区与语言接口

如需获取可用的地区和语言列表，可调用以下容路径：

• 地区列表：/v3/keywords_data/google/locations
• 语言列表：/v3/keywords_data/google/languages

---

响应结构

接口返回 JSON，顶层 tasks 数组，每个任务对应一个结果对象。

顶层响应字段

字段名	类型	说明
version	string	当前 API 版本
status_code	integer	通用状态码
status_message	string	通用状态信息
time	string	请求处理耗时，单位秒
cost	float	本次请求总成本，单位 USD
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	返回错误的任务数量
tasks	array	任务结果数组

tasks[] 字段

字段名	类型	说明
id	string	平台任务唯一标识，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000
status_message	string	任务状态说明
time	string	任务处理耗时，单位秒
cost	float	该任务成本，单位 USD
result_count	integer	result 数组中的数量
path	array	接口路径信息
data	object	回显你在请求中提交的任务参数
result	array / null	结果数组。对于创建任务接口，此处通常为 null

建议在接时对 status_code、任务级错误以及异常场景进行完整处理。错误码详见 /v3/appendix/errors

---

请求示例

cURL

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.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"
 }
]'

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"
}

data = [
 {
 "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"
 }
]

response = requests.post(url, headers=headers, json=data)
print(response.status_code)
print(response.json)

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({
 method: "post",
 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"
 },
 data: postData
})
 .then((response) => {
 // 输出接口返回结果
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error.response?.data || error.message);
 });

---

响应示例

{
 "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",
 "ad_traffic_by_keywords",
 "task_post"
 ],
 "data": {
 "api": "keywords_data",
 "function": "ad_traffic_by_keywords",
 "se": "google",
 "location_name": "United States",
 "bid": 999,
 "match": "exact",
 "keywords": [
 "seo marketing"
 ]
 },
 "result": null
 },
 {
 "id": "01301455-1535-0111-0000-0e193f50bc51",
 "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_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-1a12b9e9ee45",
 "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_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
 }
 ]
}

---

状态码说明

常见顶层状态码

状态码	含义
20000	请求成功
40006	单次请求中的任务数 100

常见任务状态码

状态码	含义
20100	任务创建成功

完整错误码与状态说明请参考 /v3/appendix/errors。

接建议

• 数量较大时，优在单任务批量提交，以降低调用次数
• 需要异步自动化处理时，优 postback_url 或 pingback_url
• 如需按国家、城市或坐标精细化评估广告需求，建议显式传地区参数
• bid 会影响采集与估算结果，应按投放策略设置，不建议盲目使用极端值
• 提交前建议统一洗长度、词数和重复项，无效任务

实用场景

• 评估商业价值：对候选批量获取展示量、CPC 和点击预估，帮助判断哪些词更适合投放和优级名单。
• 筛选高转化潜力词：结合 exact、phrase、broad 不同匹方式，识别需求明确且点击成本可接受的词，提升投放 ROI。
• 比较不同地区投放机会：按 location_name、location_code 或坐标提交同一批，分析区域间广告需求差异，支持本地化营销决策。
• 建立分级模型：将广告流量预估与自然搜索数据结合，为打上高价值、低成本、竞争激烈等标签， SEO 与 SEM 协同。
• 自动化广告选词监控：通过异步任务加回调机制，定时刷新核心词流量预估数据，及时发现 CPC 波动和需求变化。