获取 Google Ads 搜索量任务结果

本接口使用 GET 方法，通过任务 ID 获取 Google Ads 搜索量任务结果：

GET https://api.seermartech.cn/v3/keywords_data/google_ads/search_volume/task_get/$id

本接口可返回最多 1000 个的搜索量、月均搜索次数、竞争程度、竞价范围、每次点击费用及历史月度搜索数据。任务提交成功后，可在 30 天获取任务结果。

认证

请求头中使用 Bearer Token：

http

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

请求参数

路径参数

参数	类型	说明
`id`	string	任务唯一标识符，UUID 格式。任务提交后，可在 30 天使用该 ID 获取结果。

计费说明

本接口对任务提交操作计费，任务结果可在 30 天查询。

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

返回字段

接口返回 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` 数组中的结果数量。
`path`	array	请求路径信息。
`data`	array/object	创建任务时提交的参数。
`result`	array	搜索量结果数组。

`result` 数组中的字段

字段	类型	说明
`keyword`	string	。返回时会对编码进行解码，`+` 会被解码为空格。
`spell`	string/null	的正确拼写。如果提交的存在拼写错误，系统可能根据 Google Ads 的校验结果返回修正后的。
`location_code`	integer/null	请求中指定的地理位置代码。无数据时为 `null`。
`language_code`	string/null	请求中指定的语言代码。无数据时为 `null`。
`search_partners`	boolean	是否搜索合作伙伴网络的数据。
`competition`	string/null	付费搜索结果中的相对竞争程度，可选值为 `HIGH`、`MEDIUM`、`LOW`。无数据时为 `null`。
`competition_index`	integer/null	付费搜索结果中的竞争指数，取值范围为 0 至 100。无数据时为 `null`。
`search_volume`	integer/null	月均搜索量，表示目标地理位置下该的大致月均搜索次数。无数据时为 `null`。
`low_top_of_page_bid`	float	广告展示在搜索结果首页顶部所需的较低竞价估算值。
`high_top_of_page_bid`	float	广告展示在搜索结果首页顶部所需的较高竞价估算值。
`cpc`	float	每次点击费用估算值。
`monthly_searches`	array/null	过去 12 个月的月度搜索量数据。无数据时为 `null`。

`monthly_searches` 数组中的字段

字段	类型	说明
`year`	integer	年份。
`month`	integer	月份，取值为 1 至 12。
`search_volume`	integer	当月搜索量估算值。

请求示例

cURL

bash

task_id="02031608-0696-0110-0000-a81d0414edbe"

curl --location --request GET \
  "https://api.seermartech.cn/v3/keywords_data/google_ads/search_volume/task_get/${task_id}" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json"

TypeScript

typescript

import axios from "axios";

const taskId = "02231934-2604-0066-2000-570459f04879";

axios
  .get(
    `https://api.seermartech.cn/v3/keywords_data/google_ads/search_volume/task_get/${taskId}`,
    {
      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);
  });

Python

python

import requests

task_id = "02031608-0696-0110-0000-a81d0414edbe"

url = (
    "https://api.seermartech.cn/v3/keywords_data/"
    f"google_ads/search_volume/task_get/{task_id}"
)

response = requests.get(
    url,
    headers={
        "Authorization": "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
    },
)

if response.ok:
    result = response.json()
    print(result)
else:
    print(f"请求失败：HTTP {response.status_code}")
    print(response.text)

返回示例

json

{
  "version": "0.1.20231117",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "02031608-0696-0110-0000-a81d0414edbe",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.12 sec.",
      "cost": 0,
      "result_count": 2,
      "path": [
        "v3",
        "keywords_data",
        "google_ads",
        "search_volume",
        "task_get",
        "02031608-0696-0110-0000-a81d0414edbe"
      ],
      "data": {
        "api": "keywords_data",
        "function": "search_volume",
        "se": "google_ads",
        "language_code": "en",
        "location_code": 2840,
        "keywords": [
          "cheap laptops for sale",
          "purchase laptop"
        ],
        "date_from": "2021-08-01"
      },
      "result": [
        {
          "keyword": "cheap laptops for sale",
          "spell": null,
          "location_code": 2840,
          "language_code": "en",
          "search_partners": false,
          "competition": "HIGH",
          "competition_index": 100,
          "search_volume": 6600,
          "low_top_of_page_bid": 0.38,
          "high_top_of_page_bid": 2.78,
          "cpc": 1.25,
          "monthly_searches": [
            {
              "year": 2023,
              "month": 1,
              "search_volume": 6600
            }
          ]
        },
        {
          "keyword": "purchase laptop",
          "spell": null,
          "location_code": 2840,
          "language_code": "en",
          "search_partners": false,
          "competition": "HIGH",
          "competition_index": 99,
          "search_volume": 110,
          "low_top_of_page_bid": 2.07,
          "high_top_of_page_bid": 15.43,
          "cpc": 12.74,
          "monthly_searches": [
            {
              "year": 2023,
              "month": 1,
              "search_volume": 110
            }
          ]
        }
      ]
    }
  ]
}

状态码处理

建议同时检查顶层 status_code 和任务级 tasks[].status_code：

20000：请求或任务执行成功。
40000 及以上：通常表示任务执行失败或发生错误，应结合 status_message 定位原因。
当 result 为 null 或不存在时，不应继续按成功结果处理。
tasks_error 大于 0 时，应逐个检查对应任务的状态码和错误信息。

实用场景

批量获取搜索量：为库补月均搜索量，支持 SEO 筛选和优级排序。
评估商业竞争度：结合 competition 和 competition_index，识别更适合布局或付费投放的。
估算广告投放成本：使用 low_top_of_page_bid、high_top_of_page_bid 和 cpc，制定广告预算。
分析季节性趋势：读取 monthly_searches 历史数据，发现旺季、淡季及周期性搜索需求。
对比不同市场的搜索需求：按不同地理位置和语言提交任务，比较各市场的搜索量与竞争程度，为本地化 SEO 规划提供依据。

获取 Google Ads 搜索量任务结果 ​

认证 ​

请求参数 ​

路径参数 ​

计费说明 ​

返回字段 ​

顶层字段 ​

tasks 数组中的字段 ​

result 数组中的字段 ​

monthly_searches 数组中的字段 ​

请求示例 ​

cURL ​

TypeScript ​

Python ​

返回示例 ​

状态码处理 ​

实用场景 ​