Google Ads 搜索量任务创建

本接口用于批量提交 Google Ads 搜索量查询任务。单次任务最多可提交 1000 个，返回搜索量、月度搜索趋势、竞争度及竞价数据等。

这是异步标准模式：通过 POST 创建任务，系统处理完成后，再通过对应结果接口获取数据。若你需要实时返回结果，建议使用 Live 模式接口，而不是分别调用 POST 和 GET。

该接口支持最长 4 年的历史数据查询。

接口地址

POST https://api.seermartech.cn/v3/keywords_data/google_ads/search_volume/task_post

计费说明

该接口按“创建任务”计费，而不是按个数计费。也就是说，同一个请求中传 1 个与传 1000 个，任务单价相同。

参考价约 ¥0.8000 / 次扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

使用说明

请求体为 UTF-8 编码的 JSON 数组：[{ ... }]
单次 POST 最多可 100 个任务
接口调用频率上限为每分钟 2000 次
若单次 POST 中任务数 100，出部分将返回错误 40006
每个 keywords 数组最多可传 1000 个
系统会对提交的统一转为小写
结果会按逐项返回
如未指定地域参数，将返回范围数据
可通过任务 id 异步获取结果
也可在创建任务时指定 postback_url 或 pingback_url，由系统在任务完成后主动通知
若你的回调服务 10 秒未响应，请求会因时中断，任务将对应的 ready 列表你主动拉取

与旧版接口的

本接口基于平台最新版 Google Ads 数据体系。如你仍在使用旧版 Google AdWords 接口，建议升级到当前 Google Ads 路径。

请求参数

以下为创建任务时可用字段说明。

字段名	类型	填	说明
`keywords`	array	是	列表。最多 1000 个；每个最长 80 个字符；每个短语最多 10 个单词。提交后会自动转为小写。
`location_name`	string	否	搜索引擎地域名。示例：`London,England,United Kingdom`。使用该字段时，无需再传 `location_code` 或 `location_coordinate`。
`location_code`	integer	否	搜索引擎地域编码。示例：`2840`。使用该字段时，无需再传 `location_name` 或 `location_coordinate`。
`location_coordinate`	string	否	地理坐标，格式为 `"latitude,longitude"`。示例：52.6178549,-155.352142``。使用该字段时，无需再传 location_name`或`location_code`。返回数据将基于该坐标所属国家。
`language_name`	string	否	搜索语言名。示例：`English`。
`language_code`	string	否	搜索语言编码。示例：`en`。
`search_partners`	boolean	否	是否 Google 搜索合作伙伴数据。`true` 表示 Google 及合作伙伴站点；默认 `false`，返回 Google 搜索站点数据。
`date_from`	string	否	时间范围起始日期，格式：`yyyy-mm-dd`。最早可追溯至当前日期前 4 年。默认返回最近 12 个月数据。该日期不能晚于 `date_to`，也不能晚于昨日。若状态接口中的 `actual_data=false`，则最晚可设为上上月；若 `actual_data=true`，则最晚可设为上月。
`date_to`	string	否	时间范围结束日期，格式：`yyyy-mm-dd`。不能大于上月，因为当前月数据不可用。未传时默认使用昨日日期。示例：`2022-11-30`
`include_adult_keywords`	boolean	否	是否成人。设为 `true` 时尝试返回数据；默认 `false`。受平台平台限制，这类可能仍无数据返回。
`sort_by`	string	否	结果排序字段，按降序排序。可选：`relevance`、`search_volume`、`competition_index`、`low_top_of_page_bid`、`high_top_of_page_bid`。默认 `relevance`。
`postback_url`	string	否	任务完成后，系统将以 `POST` 方式把 gzip 压缩结果推送到该地址。可使用 `$id` 和 `$tag` 变量占位。示例：`https://your-server.com/postbackscript?id=$id&tag=$tag`
`pingback_url`	string	否	任务完成后，系统将以 `GET` 方式通知该地址。可使用 `$id` 和 `$tag` 变量占位。示例：`https://your-server.com/pingscript?id=$id&tag=$tag`
`tag`	string	否	用户自定义任务标识，最长 255 字符。可用于将返回结果与业务侧任务。

参数注意事项

`keywords` 字段限制

最多 1000 个
每个最多 80 个字符
每个短语最多 10 个单词
提交后统一转为小写

补说明：

某些组可能不会返回数据，这是平台广告平台的限制。
相近可能会返回合并后的搜索量，而不是逐词独立的数据。
若希望更准确比较相似词的搜索量，建议拆分为不同请求分别提交。
某些特殊符号、UTF 字符、emoji 等不用于任务提交。

地域字段互斥

以下三个字段三选一即可：

location_name
location_code
location_coordinate

如果都不传，则返回范围数据。

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

/v3/keywords_data/google_ads/locations

语言字段

可使用以下任一字段指定语言：

language_name
language_code

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

/v3/keywords_data/google_ads/languages

回调说明

pingback_url：任务完成后发送 GET 通知
postback_url：任务完成后发送 POST 结果，为 gzip 压缩数据
URL 中的特殊字符会进行 URL 编码，例如 # 会被编码为 %23
可在 URL 中使用 $id、$tag 占位，系统回调时会替换为真实值

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/keywords_data/google_ads/search_volume/task_post" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "location_name": "United States",
 "keywords": [
 "buy laptop",
 "cheap laptops for sale",
 "purchase laptop"
 ]
 },
 {
 "location_code": 2840,
 "keywords": [
 "buy laptop",
 "cheap laptops for sale",
 "purchase laptop"
 ],
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 "location_name": "United States",
 "keywords": [
 "buy laptop",
 "cheap laptops for sale",
 "purchase laptop"
 ],
 "postback_url": "https://your-server.com/postbackscript"
 }
]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/keywords_data/google_ads/search_volume/task_post"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

data = [
 {
 "location_name": "United States",
 "keywords": [
 "buy laptop",
 "cheap laptops for sale",
 "purchase laptop"
 ]
 },
 {
 "location_code": 2840,
 "keywords": [
 "buy laptop",
 "cheap laptops for sale",
 "purchase laptop"
 ],
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 "location_name": "United States",
 "keywords": [
 "buy laptop",
 "cheap laptops for sale",
 "purchase laptop"
 ],
 "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 postData = [
 {
 location_name: "United States",
 keywords: [
 "buy laptop",
 "cheap laptops for sale",
 "purchase laptop"
 ]
 },
 {
 location_code: 2840,
 keywords: [
 "buy laptop",
 "cheap laptops for sale",
 "purchase laptop"
 ],
 tag: "some_string_123",
 pingback_url: "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 location_name: "United States",
 keywords: [
 "buy laptop",
 "cheap laptops for sale",
 "purchase laptop"
 ],
 postback_url: "https://your-server.com/postbackscript"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/keywords_data/google_ads/search_volume/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);
 });

响应说明

接口返回 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	平台唯一任务 ID，UUID 格式
`status_code`	integer	任务状态码，范围通常为 `10000-60000`
`status_message`	string	任务状态信息
`time`	string	任务处理耗时，单位秒
`cost`	float	该任务费用，单位 USD
`result_count`	integer	`result` 数组中的数
`path`	array	当前请求的 API 路径
`data`	object	与提交时一致的请求参数
`result`	array / null	任务创建接口中通常为 `null`，需后续通过结果接口获取数据

响应示例

json

{
 "version": "0.1.20210917",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0890 sec.",
 "cost": 0.05,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "3f4e1c8e-8c8e-4f62-9d3a-1f0d4d3e1234",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0210 sec.",
 "cost": 0.05,
 "result_count": 0,
 "path": [
 "v3",
 "keywords_data",
 "google_ads",
 "search_volume",
 "task_post"
 ],
 "data": {
 "api": "keywords_data",
 "function": "search_volume",
 "se": "google_ads",
 "location_name": "United States",
 "keywords": [
 "buy laptop",
 "cheap laptops for sale",
 "purchase laptop"
 ]
 },
 "result": null
 }
 ]
}

常见状态与错误处理

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

建议你在业务侧建立统一的状态码与异常处理机制，要处理以下：

请求参数格式错误 -出/任务数量限制
回调地址不可达或时
平台平台对特定不返回数据
地域、语言参数无效

完整错误码体系请参考 /v3/appendix/errors。

结果获取方式

创建任务后，可通过以下方式获取数据：

使用任务 id 调用对应结果接口主动拉取
设置 pingback_url，任务完成后接收通知
设置 postback_url，任务完成后直接接收结果数据

如果你的业务需要即时返回，不建议使用本接口，应改用实时（Live）模式。

实用场景

批量评估需求：一次提交大量候选词，快速获取搜索量与竞争度，用于 SEO 选词和优级排序。
分析地区化搜索机会：按 location_name 或 location_code 查询不同国家/城市的搜索量，支持本地化与区域投放决策。
追踪历史趋势变化：结合 date_from 和 date_to 获取近 4 年趋势数据，识别季节性词汇与周期性需求波动。
比较词组商业价值：利用竞争度和页面顶部竞价字段，识别高转化潜力，营销和广告协同投放。
建立异步采集流水线：通过 pingback_url 或 postback_url 对接自动化任务系统，批量处理大规模研究需求。

Google Ads 搜索量任务创建 ​

接口地址 ​

计费说明 ​

使用说明 ​

与旧版接口的 ​

请求参数 ​

参数注意事项 ​

keywords 字段限制 ​

地域字段互斥 ​

语言字段 ​

回调说明 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应说明 ​

顶层响应字段 ​

tasks 数组字段 ​

响应示例 ​

常见状态与错误处理 ​

结果获取方式 ​

实用场景 ​