按任务 ID 获取网站结果

本接口使用 GET 方法，通过任务 ID 获取网站建议结果：

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

本接口返回与指定网站域名的，并提供出价、近一个月搜索量、近一年搜索量趋势及竞争程度等数据。单次请求最多返回 2,000 个建议。无论返回多少，均按请求次数计费。

任务提交成功后，可在 30 天获取任务结果。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

请求路径中的 $id 为任务唯一标识。

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

返回结构

接口返回 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`	object	创建任务时提交的参数。
`result`	array	结果数组。

`result` 字段说明

字段	类型	说明
`keyword`	string	。
`location_code`	integer	地理位置代码，与创建任务时的参数一致。无数据时为 `null`。
`language_code`	string	语言代码，与创建任务时的参数一致。无数据时为 `null`。
`search_partners`	boolean	是否 Google 搜索合作伙伴网络。`true` 表示 Google 及合作伙伴网站；`false` 表示返回 Google 搜索网站数据。
`competition`	string	付费搜索结果中的相对竞争程度。可选值：`LOW`、`MEDIUM`、`HIGH`。未知时为 `null`。
`competition_index`	integer	广告展示竞争指数，范围为 `0` 至 `100`。该值根据已填广告位数量与可用广告位总数计算。数据不足时为 `null`。
`search_volume`	integer	月均搜索量，表示目标地理位置下该的大致搜索次数。无数据时为 `null`。
`low_top_of_page_bid`	float	首页顶部广告展示的低位出价估算值，约高于广告展示最低出价的 20%。该值可能因目标地区不同而变化。
`high_top_of_page_bid`	float	首页顶部广告展示的高位出价估算值，约高于广告展示最低出价的 80%。该值可能因目标地区不同而变化。
`cpc`	float	单次点击费用估算值。
`monthly_searches`	array	过去 12 个月的月度搜索量数据。无数据时为 `null`。
`keyword_annotations`	object	语义标注信息。

`monthly_searches` 字段

字段	类型	说明
`year`	integer	年份。
`month`	integer	月份。
`search_volume`	integer	当月平均搜索量。

`keyword_annotations` 字段

字段	类型	说明
`concepts`	array	的概念列表。
`concepts[].name`	string	概念名称。
`concepts[].concept_group`	object	概念所属的概念组。
`concepts[].concept_group.name`	string	概念组名称。
`concepts[].concept_group.type`	string	概念组类型。

请求示例

cURL

bash

id="02031614-0696-0108-0000-b26a2a6c7e17"

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

Python

python

import requests

task_id = "02031614-0696-0108-0000-b26a2a6c7e17"

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

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

response = requests.get(url, headers=headers)
response.raise_for_status()

data = response.json()

if data.get("status_code") == 20000:
    print(data)
else:
    print(
        f"请求失败，状态码：{data.get('status_code')}，"
        f"消息：{data.get('status_message')}"
    )

TypeScript

typescript

import axios from "axios";

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

axios
  .get(
    `https://api.seermartech.cn/v3/keywords_data/google_ads/keywords_for_site/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);
  });

返回示例

json

{
  "version": "0.1.20210917",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "3.6321 sec.",
  "cost": 0.075,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "02031614-0696-0108-0000-b26a2a6c7e17",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "3.4210 sec.",
      "cost": 0.075,
      "result_count": 2,
      "path": [
        "v3",
        "keywords_data",
        "google_ads",
        "keywords_for_site",
        "task_get"
      ],
      "data": {
        "api": "keywords_data",
        "function": "keywords_for_site",
        "se": "google_ads",
        "target": "example.com",
        "location_code": 2840,
        "search_partners": true
      },
      "result": [
        {
          "keyword": "seo tools",
          "location_code": 2840,
          "language_code": null,
          "search_partners": true,
          "competition": "LOW",
          "competition_index": 24,
          "search_volume": 1300,
          "low_top_of_page_bid": 113.83,
          "high_top_of_page_bid": 481.14,
          "cpc": 3.94,
          "monthly_searches": [
            {
              "year": 2024,
              "month": 1,
              "search_volume": 1200
            },
            {
              "year": 2024,
              "month": 2,
              "search_volume": 1300
            }
          ],
          "keyword_annotations": {
            "concepts": [
              {
                "name": "搜索引擎优化",
                "concept_group": {
                  "name": "SEO",
                  "type": "CATEGORY"
                }
              }
            ]
          }
        },
        {
          "keyword": "keyword research tools",
          "location_code": 2840,
          "language_code": null,
          "search_partners": true,
          "competition": "MEDIUM",
          "competition_index": 41,
          "search_volume": 2900,
          "low_top_of_page_bid": 130.17,
          "high_top_of_page_bid": 780.74,
          "cpc": 3.94,
          "monthly_searches": [],
          "keyword_annotations": {
            "concepts": []
          }
        }
      ]
    }
  ]
}

状态码与异常处理

建议根据顶层 status_code 和任务级 tasks[].status_code 分别处理请求异常：

20000：请求或任务处理成功。
40000 及以上：通常表示任务处理失败或请求存在错误。
当 result 为 null 或 result_count 为 0 时，应按无结果场景处理。
competition、competition_index、search_volume 等字段可能因数据不足返回 null，不应直接视为接口错误。
建议记录 status_code、status_message 和任务 ID，便于重试与问题排查。

实用场景

挖掘网站：根据目标域名获取高，为 SEO规划和库建设提供数据依据。
评估商业价值：结合搜索量、竞争指数、首页顶部出价和 CPC，筛选更转化潜力的。
分析季节趋势：读取过去 12 个月的月度搜索量，识别季节性需求并安排发布节奏。
构建竞品报告：批量获取多个网站的建议，比较不同站点的主题覆盖范围和搜索需求。
优化付费搜索投放：利用竞争程度和出价区间估算投放成本，制定分组与广告预算策略。

按任务 ID 获取网站结果 ​

请求参数 ​

返回结构 ​

顶层字段 ​

tasks 中的任务字段 ​

result 字段说明 ​

monthly_searches 字段 ​

keyword_annotations 字段 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

返回示例 ​

状态码与异常处理 ​

实用场景 ​