设置 Google 搜索量任务

本接口使用 POST 方法，路径为：

/v3/keywords_data/google/search_volume/task_post

Google AdWords 数据接口属于旧版接口，当前已由 Google Ads API 替代。本文保留该容路径，便于已有系统继续调用。

本接口用于提交 Google 搜索量任务，并获取以下数据：

最近一个月的搜索量
最近一年的搜索量趋势，用于评估搜索需求变化
当前每次点击费用（CPC）
付费搜索竞争度

这是标准任务模式。调用接口后，系统会创建任务，任务处理完成后再获取结果。处理时间取决于系统负载。如果业务需要实时返回结果，可使用 Live 接口：

/v3/keywords_data/google/search_volume/live/

还可以通过以下接口查询 Google 返回的搜索量数据更新状态：

/v3/keywords_data/google/adwords_status/

请求地址

http

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

所有请求体使用 UTF-8 编码的 JSON 格式，并且顶层结构是 JSON 数组：

json

[
  {
    "keywords": ["example keyword"]
  }
]

请求限制：

平台限流以认证说明中的 30/60/120 次/分钟规则为准

每次请求最多 100 个任务
单个任务的 keywords 数组最多 700 个
如果单次请求 100 个任务，出部分的任务将返回 40006 错误
每个任务按请求计费，与 keywords 数组中 1 个还是 700 个无

任务创建后，可以通过返回的唯一任务 ID 获取结果。也可以在请求中指定 postback_url 或 pingback_url，由本平台在任务完成后主动通知。

如果接收服务器在 10 秒未响应，连接将因时中断，任务会转移至以下处理列表：

/v3/keywords_data/google/search_volume/tasks_ready/

回调的错误码和错误信息取决于接收服务器的。

计费说明

提交任务时计费，数量不会改变单个任务的价格。

根据原始示例中的任务价格，参考价约为：

参考价约 ¥0.36 / 个任务
3 个任务示例的参考总价约 ¥1.08

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

参数名	类型	填	说明
`keywords`	array	是	要查询的列表。最多 700 个；每个最多 80 个字符、最多 10 个单词。系统会将指定转换为小写，并在结果中分别返回对应数据。
`location_name`	string	否	搜索引擎地域的完整名称。使用该参数时，不要同时指定 `location_code` 或 `location_coordinate`。省略该参数时，返回结果。
`location_code`	integer	否	搜索引擎地域代码。使用该参数时，不要同时指定 `location_name` 或 `location_coordinate`。省略该参数时，返回结果。
`location_coordinate`	string	否	地理位置 GPS 坐标，格式为 `纬度,经度`。使用该参数时，不要同时指定 `location_name` 或 `location_code`。数据将按该坐标所属国家返回。省略该参数时，返回结果。
`language_name`	string	否	搜索引擎语言的完整名称。不建议在创建任务时使用此参数；指定后 Google 可能返回 `null` 搜索量。使用该参数时，不要同时指定 `language_code`。
`language_code`	string	否	搜索引擎语言代码。不建议在创建任务时使用此参数；指定后 Google 可能返回 `null` 搜索量。使用该参数时，不要同时指定 `language_name`。
`search_partners`	boolean	否	是否同时查询 Google 搜索及搜索合作伙伴。默认值为 `false`。设置为 `true` 时，结果覆盖 Google 和搜索合作伙伴。
`postback_url`	string	否	任务完成后的结果回调地址。本平台会向该地址发送任务结果的 POST 请求，采用 gzip 压缩格式。
`pingback_url`	string	否	任务完成后的通知地址。本平台会向该地址发送 GET 请求。
`tag`	string	否	用户自定义任务标识，最多 255 个字符。可用于任务与结果。指定的值会出现在响应的 `data` 对象中。

`keywords`

限制如下：

最多 700 个
每个最多 80 个字符
每个短语最多 10 个单词
系统会将转换为小写
每个的数据会在结果数组中单独返回

示例：

json

{
  "keywords": [
    "average page rpm adsense",
    "adsense blank ads how long"
  ]
}

地域参数

三种地域参数只能选择一种。

使用 `location_name`

json

{
  "location_name": "London,England,United Kingdom",
  "keywords": ["seo tools"]
}

可通过以下接口获取可用地域名称：

/v3/keywords_data/google/locations

使用 `location_code`

json

{
  "location_code": 2840,
  "keywords": ["seo tools"]
}

可通过以下接口获取可用地域代码：

/v3/keywords_data/google/locations

使用 `location_coordinate`

json

{
  "location_coordinate": "52.6178549,-155.352142",
  "keywords": ["seo tools"]
}

坐标格式为：

text

纬度,经度

返回数据将该坐标所属国家处理。

语言参数

不建议在创建任务时指定 language_name 或 language_code，因为 Google 可能在指定语言后返回 null 搜索量。

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

/v3/keywords_data/google/languages

使用语言名称：

json

{
  "language_name": "English",
  "keywords": ["seo tools"]
}

使用语言代码：

json

{
  "language_code": "en",
  "keywords": ["seo tools"]
}

`postback_url`

任务完成后，本平台会向指定地址发送 POST 请求，结果使用 gzip 格式压缩。

支持以下变量：

$id：任务 ID
$tag：经过 URL 编码的任务标签

示例：

text

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

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

`pingback_url`

任务完成后，本平台会向指定地址发送 GET 请求。

支持以下变量：

$id：任务 ID
$tag：经过 URL 编码的任务标签

示例：

text

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

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

响应字段

接口返回 JSON 数据，顶层 tasks 数组，每个对应一个已创建的任务。

顶层响应字段

字段名	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	通用状态码。
`status_message`	string	通用状态说明。
`time`	string	请求执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务数量。
`tasks_error`	integer	`tasks` 数组中返回错误的任务数量。
`tasks`	array	已创建任务的数组。

`tasks`素字段

字段名	类型	说明
`id`	string	任务唯一标识，UUID 格式。
`status_code`	integer	任务状态码，通常在 `10000` 至 `60000` 范围。
`status_message`	string	任务状态说明。
`time`	string	任务执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量。任务创建接口通常为 `0`。
`path`	array	请求 URL 路径信息。
`data`	object	创建任务时提交的参数及系统补的接口信息。
`result`	array \| null	任务结果数组。任务创建成功后通常为 `null`，需要在任务完成后单独获取结果。

完整错误码请参考错误码文档。建议客户端针对 HTTP 错误、通用状态码和单任务状态码分别实现异常处理。

请求示例

curl

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/keywords_data/google/search_volume/task_post" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "location_name": "United States",
      "keywords": [
        "average page rpm adsense"
      ]
    },
    {
      "language_code": "en",
      "location_code": 2840,
      "keywords": [
        "adsense blank ads how long"
      ],
      "tag": "some_string_123",
      "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
    },
    {
      "location_name": "United States",
      "keywords": [
        "leads and prospects"
      ],
      "postback_url": "https://your-server.com/postbackscript"
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/keywords_data/google/search_volume/task_post"

headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
}

payload = [
    {
        "location_name": "United States",
        "keywords": [
            "average page rpm adsense"
        ],
    },
    {
        "language_code": "en",
        "location_code": 2840,
        "keywords": [
            "adsense blank ads how long"
        ],
        "tag": "some_string_123",
        "pingback_url": (
            "https://your-server.com/pingscript"
            "?id=$id&tag=$tag"
        ),
    },
    {
        "location_name": "United States",
        "keywords": [
            "leads and prospects"
        ],
        "postback_url": "https://your-server.com/postbackscript",
    },
]

response = requests.post(url, headers=headers, json=payload)
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 payload = [
  {
    location_name: "United States",
    keywords: ["average page rpm adsense"],
  },
  {
    language_code: "en",
    location_code: 2840,
    keywords: ["adsense blank ads how long"],
    tag: "some_string_123",
    pingback_url:
      "https://your-server.com/pingscript?id=$id&tag=$tag",
  },
  {
    location_name: "United States",
    keywords: ["leads and prospects"],
    postback_url: "https://your-server.com/postbackscript",
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/keywords_data/google/search_volume/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.0882 sec.",
  "cost": 0.15,
  "tasks_count": 3,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01302137-1535-0110-0000-af164848a289",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0020 sec.",
      "cost": 0.05,
      "result_count": 0,
      "path": [
        "v3",
        "keywords_data",
        "google",
        "search_volume",
        "task_post"
      ],
      "data": {
        "api": "keywords_data",
        "function": "search_volume",
        "se": "google",
        "location_name": "London,England,United Kingdom",
        "keywords": [
          "seo tools"
        ]
      },
      "result": null
    },
    {
      "id": "01302137-1535-0110-0000-af164848a289",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0020 sec.",
      "cost": 0.05,
      "result_count": 0,
      "path": [
        "v3",
        "keywords_data",
        "google",
        "search_volume",
        "task_post"
      ],
      "data": {
        "api": "keywords_data",
        "function": "search_volume",
        "se": "google",
        "language_code": "en",
        "location_code": 2840,
        "keywords": [
          "adsense blank ads how long"
        ],
        "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag",
        "tag": "some_string_123"
      },
      "result": null
    },
    {
      "id": "01302137-1535-0110-0000-6aa9f0d703d5",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0021 sec.",
      "cost": 0.05,
      "result_count": 0,
      "path": [
        "v3",
        "keywords_data",
        "google",
        "search_volume",
        "task_post"
      ],
      "data": {
        "api": "keywords_data",
        "function": "search_volume",
        "se": "google",
        "location_name": "United States",
        "keywords": [
          "leads and prospects"
        ],
        "postback_url": "https://your-server.com/postbackscript"
      },
      "result": null
    }
  ]
}

任务创建成功通常返回：

顶层 status_code：20000
单任务 status_code：20100
单任务 result：null

后续需要根据任务 ID 获取已完成任务的结果， postback_url、pingback_url 回调。

实用场景

批量评估搜索量：一次提交最多 700 个，为 SEO 选词和优级排序提供数据依据。
对比不同国家或城市的搜索需求：通过 location_name、location_code 或坐标查询地域搜索量，支持本地 SEO 和化市场决策。
分析年度趋势：获取最近一年的搜索量变化，识别季节性需求并规划发布时间。
评估付费搜索竞争度与 CPC：结合竞争度和点击费用筛选商业价值更高的， SEO 与 SEM 联合投放。
通过回调自动更新数据仓库： postback_url 或 pingback_url，在任务完成后自动触发数据库、报表刷新或监控流程。

设置 Google 搜索量任务 ​

请求地址 ​

计费说明 ​

请求参数 ​

keywords ​

地域参数 ​

使用 location_name ​

使用 location_code ​

使用 location_coordinate ​

语言参数 ​

postback_url ​

pingback_url ​

响应字段 ​

顶层响应字段 ​

tasks素字段 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应示例 ​

实用场景 ​

设置 Google 搜索量任务

请求地址

计费说明

请求参数

`keywords`

地域参数

使用 `location_name`

使用 `location_code`

使用 `location_coordinate`

语言参数

`postback_url`

`pingback_url`

响应字段

顶层响应字段

`tasks`素字段

请求示例

curl

Python

TypeScript

响应示例

实用场景