拓展任务创建

POST /v3/keywords_data/google_ads/keywords_for_keywords/task_post

本接口使用 POST /v3/keywords_data/google_ads/keywords_for_keywords/task_post 创建“拓展”任务。提交最多 20 个后，本平台将从 Google Ads 获取建议及数据；单个任务最多可返回 20,000 条建议。

这是标准异步获取方式：提交任务后，系统完成采集，再通过任务 ID 查询结果。如果业务需要即时返回结果，可使用 Live 接口，无需分别执行 POST 和 GET 请求。

历史数据最长可追溯 4 年。

接口信息

http

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

计费说明

在创建任务时计费。
参考价约 ¥0.36 / 次任务。
批量请求中的每个任务独立计费。
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求限制

请求体使用 UTF-8 编码的 JSON 格式。
每次 POST 请求最多 100 个任务。
每分钟最多可发起 2,000 次 API 请求。
如果单次请求 100 个任务，出部分将返回错误码 40006。
创建任务后，可使用返回的 id 获取结果。
也可以在请求中设置 postback_url 或 pingback_url，在任务完成后接收通知。
如果通知服务器在 10 秒未响应，连接将因时中止，任务会转 tasks_ready 列表。

请求体格式

请求体是 JSON 数组：

json

[
  {
    "keywords": ["seo tools", "keyword research"],
    "location_name": "United States",
    "language_code": "en"
  }
]

请求参数

参数	类型	填	说明
`keywords`	array	是	用于获取的种子数组。最多 20 个；每个最多 80 个字符。提交的会被转换为小写。某些组合可能没有返回数据。Google Ads 不使用部分符号和字符，例如部分 UTF 字符及表符号。
`target`	string	否	目标网站或 URL。用于获取与网站的。即使传 URL，返回结果仍可能覆盖整个网站的。
`location_name`	string	否	搜索引擎地域的完整名称。不指定时返回结果。使用此参数后，不需要同时指定 `location_code` 或 `location_coordinate`。可通过 `/v3/keywords_data/google_ads/locations` 获取可用地域。示例：`London,England,United Kingdom`。
`location_code`	integer	否	搜索引擎地域代码。不指定时返回结果。使用此参数后，不需要同时指定 `location_name` 或 `location_coordinate`。可通过 `/v3/keywords_data/google_ads/locations` 获取地域代码。示例：`2840`。
`location_coordinate`	string	否	地域 GPS 坐标，格式为 `"纬度,经度"`。数据将该坐标所属国家返回。使用此参数后，不需要同时指定 `location_name` 或 `location_code`。示例：`52.6178549,-155.352142`。
`language_name`	string	否	搜索引擎语言的完整名称。可通过 `/v3/keywords_data/google_ads/languages` 获取可用语言。示例：`English`。
`language_code`	string	否	搜索引擎语言代码。可通过 `/v3/keywords_data/google_ads/languages` 获取可用语言代码。示例：`en`。
`search_partners`	boolean	否	是否 Google 搜索合作伙伴网络。设置为 `true` 时，结果 Google 及搜索合作伙伴网站上的网络数据。默认值为 `false`，返回 Google 搜索网站结果。
`date_from`	string	否	数据起始日期，格式为 `yyyy-mm-dd`。最早可设置为当前日期往前 4 年。默认返回过去 12 个月的数据。该日期不能晚于 `date_to` 或昨天。
`date_to`	string	否	数据结束日期，格式为 `yyyy-mm-dd`。不能晚于昨天。未指定时默认为昨天。
`sort_by`	string	否	结果排序字段，支持：`relevance`、`search_volume`、`competition_index`、`low_top_of_page_bid`、`high_top_of_page_bid`。结果按指定字段降序排列。默认值为 `relevance`。
`include_adult_keywords`	boolean	否	是否返回与成人的。默认值为 `false`。即使设置为 `true`，部分仍可能因 Google Ads 政策限制而没有数据。
`postback_url`	string	否	任务完成后，本平台向该地址发送 POST 请求，并以 gzip 格式压缩请求结果。URL 中可使用 `$id` 和 `$tag` 占位符，本平台发送请求时会替换为任务 ID 和经过 URL 编码的标签值。
`pingback_url`	string	否	任务完成后，本平台向该地址发送 GET 请求进行通知。URL 中可使用 `$id` 和 `$tag` 占位符，本平台发送请求时会替换为任务 ID 和经过 URL 编码的标签值。
`tag`	string	否	用户自定义任务标识，最多 255 个字符。可用于匹任务与结果。提交的值会出现在响应任务的 `data` 对象中。

日期参数说明

如果 /v3/keywords_data/google_ads/status 返回的 actual_data 为：

false：date_from 最早可设置为上上个月及更早日期。
true：date_from 可设置为上个月及更早日期。

回调 URL 示例

text

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

text

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

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

响应字段

接口返回 JSON 对象 tasks 数组。

顶层字段

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

`tasks` 子项字段

字段	类型	说明
`id`	string	任务唯一标识，UUID 格式。后续可使用该 ID 获取任务结果。
`status_code`	integer	任务状态码，通常位于 `10000`–`60000` 范围。
`status_message`	string	任务状态信息，例如 `Task Created.`。
`time`	string	任务创建或执行耗时。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量。任务刚创建时通常为 `0`。
`path`	array	与任务的 URL 路径信息。
`data`	object	创建任务时提交的参数及系统补参数。
`result`	array/null	任务结果。创建任务时为 `null`，需在任务完成后获取。

完整状态码可参考错误码文档。

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",
      "language_code": "en",
      "keywords": ["seo tools", "keyword research"],
      "tag": "keyword-expansion-demo"
    }
  ]'

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

post_data = [
    {
        "location_name": "United States",
        "language_code": "en",
        "keywords": ["seo tools", "keyword research"],
        "tag": "keyword-expansion-demo",
    }
]

response = requests.post(url, headers=headers, json=post_data)
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 postArray = [
  {
    location_name: "United States",
    language_code: "en",
    keywords: ["seo tools", "keyword research"],
    tag: "keyword-expansion-demo",
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/keywords_data/google_ads/keywords_for_keywords/task_post",
    postArray,
    {
      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": 1.08,
  "tasks_count": 3,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01301831-1535-0107-0000-21cc045291e0",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0020 sec.",
      "cost": 0.36,
      "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": [
          "seo tools",
          "keyword research"
        ],
        "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag",
        "tag": "keyword-expansion-demo"
      },
      "result": null
    },
    {
      "id": "01301831-1535-0107-0000-77a3219d7e0b",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0022 sec.",
      "cost": 0.36,
      "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": [
          "seo tools",
          "keyword research"
        ],
        "postback_url": "https://your-server.com/postbackscript"
      },
      "result": null
    }
  ]
}

创建成功后，通常会返回任务状态码 20100（Task Created.）。此时 result 为 null，需要使用任务 ID 查询结果，或 postback_url / pingback_url 通知。

实用场景

扩展种子：根据核心批量获取搜索词，为 SEO规划和库建设提供数据基础。
分析商业价值：结合搜索量、竞争指数及页面顶部出价区间，筛选更转化潜力的。
构建地域化词库：按国家、城市或 GPS 坐标获取建议，支持本地 SEO 和区域投放策略。
规划多语言：指定目标语言获取对应，帮助企业制定多地区、多语言站点的布局。
监测历史趋势：设置时间范围获取历史数据，用于比较季节性需求并优化发布节奏。

拓展任务创建 ​

接口信息 ​

计费说明 ​

请求限制 ​

请求体格式 ​

请求参数 ​

日期参数说明 ​

回调 URL 示例 ​

响应字段 ​

顶层字段 ​

tasks 子项字段 ​

curl 示例 ​

Python 示例 ​

TypeScript 示例 ​

响应示例 ​

实用场景 ​