主题
设置 Google 网站任务
本接口使用 POST 方法，路径为：
/v3/keywords_data/google/keywords_for_site/task_post
本接口用于根据指定网站域名获取，并返回分类、最近一个月搜索量、过去一年搜索量趋势、当前每次点击费用（CPC）以及付费搜索竞争程度等数据。
这是标准任务提交方式。接口提交任务后，系统将在后台采集数据；任务完成后，可通过任务 ID 获取结果，也可以回调地址接收通知。若业务要求实时返回结果，可使用对应的 Live 接口。
该接口属于旧版 Google AdWords 数据能力。新项目建议优评估 Google Ads 接口。
计费与调用限制
- 账户在成功提交任务时计费。
- 每个任务最多返回 700 个及核心数据。
- 无论最终返回 1 个还是 700 个，单个任务的计费标准相同。
- 参考价约 ¥0.36 / 任务；批量提交示例中 3 个任务的参考总价约为 ¥1.08。
- 实扣费以响应头
X-SeerMarTech-Charge-CNY为准。 - 请求体使用 UTF-8 编码的 JSON 格式。 平台限流以认证说明中的 30/60/120 次/分钟规则为准。
- 单次请求最多 100 个任务； 100 个任务的部分将返回错误码
40006。 - 任务完成后，也可以通过任务唯一标识
id获取结果。 - 如果了
postback_url或pingback_url，系统将在任务完成后发送通知。 - 如果回调服务器在 10 秒未响应，连接将因时中断，任务会转移至处理任务列表。
请求参数
请求体是 JSON 数组，每个数组代表一个任务。
| 参数 | 类型 | 填 | 说明 |
|---|---|---|---|
target | string | 是 | 目标网站域名，例如 example.com。 |
location_name | string | 否 | 搜索引擎地域的完整名称，例如 London,England,United Kingdom。使用此参数时，不要同时传 location_code 或 location_coordinate。不传时返回结果。可通过 /v3/keywords_data/google/locations 获取可用地域。 |
location_code | integer | 否 | 搜索引擎地域编码，例如 2840。使用此参数时，不要同时传 location_name 或 location_coordinate。不传时返回结果。 |
location_coordinate | string | 否 | 地域 GPS 坐标，格式为 纬度,经度，例如 52.6178549,-155.352142。数据将按该坐标所属国家提供。不传时返回结果。 |
language_name | string | 否 | 搜索引擎语言的完整名称，例如 English。使用此参数时，不要同时传 language_code。不传时返回所有可用语言的结果。可通过 /v3/keywords_data/google/languages 获取可用语言。 |
language_code | string | 否 | 搜索引擎语言编码，例如 en。使用此参数时，不要同时传 language_name。不传时返回所有可用语言的结果。 |
sort_by | string | 否 | 结果排序字段，可设置为 search_volume 或 relevance。结果按降序排列，默认值为 search_volume。 |
keywords_negative | array | 否 | 需要排除的列表。最多可指定 200 个词组；提交的会被转换为小写，并从结果中排除。 |
postback_url | string | 否 | 任务完成后接收结果的 URL。系统会向该地址发送 Gzip 压缩的 POST 请求。URL 中可使用 $id 和 $tag 占位符，系统发送请求时会替换为值。 |
pingback_url | string | 否 | 任务完成通知 URL。任务完成后，系统会向该地址发送 GET 请求。URL 中可使用 $id 和 $tag 占位符。 |
tag | string | 否 | 用户自定义任务标识，最长 255 个字符。可用于任务与结果，提交的值会在响应的 data 对象中返回。 |
回调地址说明
postback_url 示例：
text
https://your-server.com/postbackscript?id=$id
https://your-server.com/postbackscript?id=$id&tag=$tagpingback_url 示例：
text
https://your-server.com/pingscript?id=$id
https://your-server.com/pingscript?id=$id&tag=$tag回调地址中的特殊字符会进行 URL 编码，例如 # 会编码为 %23。
请求示例
cURL
bash
curl --location --request POST \
"https://api.seermartech.cn/v3/keywords_data/google/keywords_for_site/task_post" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
{
"target": "example.com",
"location_name": "United States",
"language_code": "en",
"sort_by": "search_volume",
"tag": "site-keywords-us"
},
{
"target": "example.com",
"location_code": 2840,
"language_code": "en",
"keywords_negative": [
"free",
"job"
],
"pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag",
"tag": "site-keywords-ping"
},
{
"target": "example.com",
"location_name": "United States",
"language_name": "English",
"postback_url": "https://your-server.com/postbackscript?id=$id",
"tag": "site-keywords-post"
}
]'Python
python
import requests
url = "https://api.seermartech.cn/v3/keywords_data/google/keywords_for_site/task_post"
headers = {
"Authorization": "Bearer smt_live_YOUR_KEY",
"Content-Type": "application/json",
}
tasks = [
{
"target": "example.com",
"location_name": "United States",
"language_code": "en",
"tag": "site-keywords-us",
},
{
"target": "example.com",
"location_code": 2840,
"language_code": "en",
"tag": "site-keywords-ping",
"pingback_url": (
"https://your-server.com/pingscript"
"?id=$id&tag=$tag"
),
},
{
"target": "example.com",
"location_name": "United States",
"language_name": "English",
"tag": "site-keywords-post",
"postback_url": "https://your-server.com/postbackscript?id=$id",
},
]
response = requests.post(url, headers=headers, json=tasks, 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 tasks = [
{
target: "example.com",
location_name: "United States",
language_code: "en",
tag: "site-keywords-us",
},
{
target: "example.com",
location_code: 2840,
language_code: "en",
tag: "site-keywords-ping",
pingback_url:
"https://your-server.com/pingscript?id=$id&tag=$tag",
},
{
target: "example.com",
location_name: "United States",
language_name: "English",
tag: "site-keywords-post",
postback_url:
"https://your-server.com/postbackscript?id=$id",
},
];
axios
.post(
"https://api.seermartech.cn/v3/keywords_data/google/keywords_for_site/task_post",
tasks,
{
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 | 请求执行耗时，单位为秒。 |
cost | float | 平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。 |
tasks_count | integer | tasks 数组中的任务总数。 |
tasks_error | integer | tasks 数组中返回错误的任务数量。 |
tasks | array | 任务结果数组。 |
任务字段
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 任务唯一标识，UUID 格式。后续可使用该 ID 获取任务结果。 |
status_code | integer | 当前任务状态码，通常位于 10000 至 60000 范围。 |
status_message | string | 当前任务的状态说明。 |
time | string | 任务提交或处理耗时，单位为秒。 |
cost | float | 平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。 |
result_count | integer | result 数组中的数量。任务刚创建时通常为 0。 |
path | array | 请求路径信息。 |
data | object | 本次任务提交时使用的参数。 |
result | array | null | 任务结果。任务创建成功时为 null，需要在任务完成后获取结果。 |
响应示例
json
{
"version": "0.1.20200130",
"status_code": 20000,
"status_message": "Ok.",
"time": "0.1108 sec.",
"cost": 1.08,
"tasks_count": 3,
"tasks_error": 0,
"tasks": [
{
"id": "01301901-1535-0108-0000-daf9eadecca9",
"status_code": 20100,
"status_message": "Task Created.",
"time": "0.0019 sec.",
"cost": 0.36,
"result_count": 0,
"path": [],
"data": {
"api": "keywords_data",
"function": "keywords_for_site",
"se": "google",
"location_name": "United States",
"language_code": "en",
"target": "example.com",
"tag": "site-keywords-us"
},
"result": null
},
{
"id": "01301901-1535-0108-0000-d86ef6dbd3a8",
"status_code": 20100,
"status_message": "Task Created.",
"time": "0.0018 sec.",
"cost": 0.36,
"result_count": 0,
"path": [],
"data": {
"api": "keywords_data",
"function": "keywords_for_site",
"se": "google",
"location_code": 2840,
"language_code": "en",
"target": "example.com",
"pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag",
"tag": "site-keywords-ping"
},
"result": null
},
{
"id": "01301901-1535-0108-0000-daf9eadecca8",
"status_code": 20100,
"status_message": "Task Created.",
"time": "0.0018 sec.",
"cost": 0.36,
"result_count": 0,
"path": [],
"data": {
"api": "keywords_data",
"function": "keywords_for_site",
"se": "google",
"location_name": "United States",
"language_name": "English",
"target": "example.com",
"postback_url": "https://your-server.com/postbackscript?id=$id",
"tag": "site-keywords-post"
},
"result": null
}
]
}状态码与错误处理
- 顶层
status_code为20000：请求处理成功。 - 任务
status_code为20100：任务已创建，系统处理。 tasks_error大于0：至少有一个任务提交失败，应检查对应任务的status_code和status_message。- 单次提交 100 个任务时，出部分返回
40006。 - 建议客户端同时处理 HTTP 错误、顶层状态码以及单任务状态码，因部分任务失败导致整体流程判断错误。
实用场景
- 挖掘竞品网站：提交竞品域名并获取搜索词，扩选题和 SEO 库。
- 评估商业价值：结合搜索量、CPC 和付费竞争程度，筛选适合投放或商业化建设的。
- 构建地域化库：按国家、城市或语言提交任务，比较不同市场的需求，为 SEO 制定本地化策略。
- 排除无效搜索词：通过
keywords_negative过滤品牌不词、招聘词或类词，提升分析结果的可用性。 - 批量监测网站机会：一次提交多个域名任务，并使用
tag、postback_url或pingback_url自动和接收分析结果。