推荐任务创建

接口说明

该接口用于为指定词组获取推荐。你最多可以在 keywords 数组中提交 20 个，系统会基于 Google Ads 数据返回建议。单次请求最多可获得 20,000 条推荐，并附带核心指标。

这是标准异步任务模式：创建任务，再在任务完成后获取结果。若你的业务不要求实时返回，这通常是更稳妥、成本更可控的方式。任务执行时间取决于系统负载。

如需即时结果，可改用对应的 Live 端点；Live 模式无需拆分 POST/GET 两步。

历史数据最长支持近 4 年。

请求地址

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

计费说明

该接口按创建任务计费。

原文未给出固定单价，因此无法直接换算参考人民币价格。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求规范

请求体为 UTF-8 编码的 JSON
POST 请求体格式为 JSON 数组：[{ ... }]
每分钟最多可发起 2000 次 API 调用
单次 POST 最多 100 个任务
若单次 POST过 100 个任务，出部分会返回错误 40006

你也可以通过任务唯一标识 id 获取已完成任务的结果。如果在创建任务时传 postback_url 或 pingback_url，本平台可在结果就绪后主动通知你的系统。

注意：
如果你的服务器在 10 秒未响应回调请求，连接会因时中断
对应任务会被转移到 tasks_ready 列表中
错误码与错误信息取决于你的服务器

请求参数

任务级参数

字段	类型	填	说明
`keywords`	array	是	数组。最多 20 个；每个最多 80 个字符；系统会自动转为小写。注意：某些组可能无返回数据；同时 Google Ads 不部分符号或字符（如部分 UTF 符号、emoji），这些不能用于创建任务。
`target`	string	否	目标网站或 URL。用于获取与该网站的列表。注意：即使传的是页面 URL，返回结果仍可能基于整个站点性。
`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	否	搜索语言名。示例：`English`
`language_code`	string	否	搜索语言代码。示例：`en`
`search_partners`	boolean	否	是否 Google 搜索合作伙伴流量。`true` 表示 Google 及合作搜索网络；默认 `false`，返回 Google 搜索站点数据。
`date_from`	string	否	时间范围起始日期，格式 `"yyyy-mm-dd"`。最早可设为当前日期往前 4 年。默认返回过去 12 个月数据。该日期不能晚于 `date_to`，也不能晚于昨天。若状态接口 `/v3/keywords_data/google_ads/status/` 中 `actual_data=false`，则最晚可设到上上月；若 `actual_data=true`，则最晚可设到上月。
`date_to`	string	否	时间范围结束日期，格式 `"yyyy-mm-dd"`。不能晚于昨天；不传时默认取昨天。示例：`2022-11-30`
`sort_by`	string	否	结果排序方式，按降序排序。可选值：`relevance`、`search_volume`、`competition_index`、`low_top_of_page_bid`、`high_top_of_page_bid`。默认：`relevance`
`include_adult_keywords`	boolean	否	是否成人。设为 `true` 时会尝试返回词；默认 `false`。注意：受 Google Ads 限制，这类词可能仍无数据。
`postback_url`	string	否	结果推送地址。任务完成后，本平台会向该地址发送 gzip 压缩的 POST 结果。可在 URL 中使用 `$id` 作为任务 id 变量、`$tag` 作为 URL 编码后的 tag 变量。示例：`http://your-server.com/postbackscript?id=$id`
`pingback_url`	string	否	完成通知地址。任务完成后，本平台会向该地址发起 GET 请求。可使用 `$id` 和 `$tag` 变量。示例：`http://your-server.com/pingscript?id=$id&tag=$tag`
`tag`	string	否	自定义任务标识，最长 255 字符。可用于业务侧请求与结果；返回时会出现在响应的 `data` 对象中。

地域与语言列表查询

如需获取可用地域或语言，请调用以下容路径：

地域列表：/v3/keywords_data/google_ads/locations
语言列表：/v3/keywords_data/google_ads/languages

响应结构

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

顶层字段

字段	类型	说明
`version`	string	API 当前版本
`status_code`	integer	接口通用状态码
`status_message`	string	接口通用状态信息
`time`	string	执行耗时，单位秒
`cost`	float	本次请求总费用
`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	当前任务费用
`result_count`	integer	`result` 数组数
`path`	array	请求路径信息
`data`	object	回显你在 POST 请求中提交的参数
`result`	array \| null	任务结果。对于 `task_post`，此处通常为 `null`，数据需在任务完成后获取

状态码说明

20000：请求成功
20100：任务创建成功
40006：单次 POST 中提交的任务数 100 个

完整错误码体系请参考 /v3/appendix/errors。建议在接时实现统一的异常处理与重试机制。

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/keywords_data/google_ads/keywords_for_keywords/task_post" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "location_name": "United States",
 "keywords": [
 "seo tools",
 "keyword research",
 "backlink checker"
 ],
 "sort_by": "relevance",
 "tag": "campaign_kw_seed_001"
 }
]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/keywords_data/google_ads/keywords_for_keywords/task_post"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
payload = [
 {
 "location_name": "United States",
 "keywords": [
 "seo tools",
 "keyword research",
 "backlink checker"
 ],
 "sort_by": "relevance",
 "tag": "campaign_kw_seed_001"
 }
]

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

TypeScript

typescript

import axios from "axios";

const payload = [
 {
 location_name: "United States",
 keywords: [
 "seo tools",
 "keyword research",
 "backlink checker"
 ],
 sort_by: "relevance",
 tag: "campaign_kw_seed_001"
 }
];

axios.post(
 "https://api.seermartech.cn/v3/keywords_data/google_ads/keywords_for_keywords/task_post",
 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

{
 "version": "0.1.20200130",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0683 sec.",
 "cost": 0.15,
 "tasks_count": 3,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "01301831-1535-0107-0000-1a2b3c4d5e6f",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0021 sec.",
 "cost": 0.05,
 "result_count": 0,
 "path": [
 "v3",
 "keywords_data",
 "google_ads",
 "keywords_for_keywords",
 "task_post"
 ],
 "data": {
 "api": "keywords_data",
 "function": "keywords_for_keywords",
 "se": "google_ads",
 "location_name": "United States",
 "keywords": [
 "seo tools",
 "keyword research",
 "backlink checker"
 ]
 },
 "result": null
 },
 {
 "id": "01301831-1535-0107-0000-21cc045291e0",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0020 sec.",
 "cost": 0.05,
 "result_count": 0,
 "path": [
 "v3",
 "keywords_data",
 "google_ads",
 "keywords_for_keywords",
 "task_post"
 ],
 "data": {
 "api": "keywords_data",
 "function": "keywords_for_keywords",
 "se": "google_ads",
 "location_code": 2840,
 "keywords": [
 "running shoes",
 "trail shoes"
 ],
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag",
 "tag": "some_string_123"
 },
 "result": null
 },
 {
 "id": "01301831-1535-0107-0000-77a3219d7e0b",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0022 sec.",
 "cost": 0.05,
 "result_count": 0,
 "path": [
 "v3",
 "keywords_data",
 "google_ads",
 "keywords_for_keywords",
 "task_post"
 ],
 "data": {
 "api": "keywords_data",
 "function": "keywords_for_keywords",
 "se": "google_ads",
 "language_name": null,
 "location_name": "United States",
 "keywords": [
 "content marketing",
 "technical seo"
 ],
 "postback_url": "https://your-server.com/postbackscript"
 },
 "result": null
 }
 ]
}

使用说明补

1.异步结果获取

task_post 负责创建任务，响应中的 result 一般为 null。你需要通过后续结果查询接口，或使用 postback_url / pingback_url 获取任务完成通知与结果。

2.限制

最多 20 个
每个最多 80 个字符
自动转为小写
部分因平台广告平台限制，可能无搜索量或无推荐结果
某些特殊字符、表符号、UTF 特殊字符不能使用

3.日期范围

默认返回过去 12 个月数据
最长支持近 4 年历史数据
date_to 默认是昨天
是否可以查询最近一个月的数据，取决于 /v3/keywords_data/google_ads/status/ 返回的 actual_data 状态

实用场景

扩展种子词库：核心业务词，批量获取建议，快速丰富 SEO 或投放账户的候选词池。
按国家或地区做本地化选词：结合 location_name、location_code 或坐标参数，挖掘不同市场下的偏好，支持海外站点本地化运营。
围绕竞品或目标站点找词：传 target 网站，发现与该站点主题高度的搜索词，用于栏目规划和竞品词覆盖分析。
筛选高价值广告词：使用 sort_by 按搜索量、竞争度或首页出价排序，优识别更商业价值的投放。
构建异步大批量采集流程：通过 task_post 搭 pingback_url 或 postback_url，实现推荐任务的批量提交与自动回传，适合定时跑库和数据平台接。

推荐任务创建 ​

接口说明 ​

计费说明 ​

请求规范 ​

请求参数 ​

任务级参数 ​

地域与语言列表查询 ​

响应结构 ​

顶层字段 ​

tasks[] 字段 ​

状态码说明 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

使用说明补 ​

1.异步结果获取 ​

2.限制 ​

3.日期范围 ​

实用场景 ​