SeerMarTech API 文档

主题

设置实时「网站」任务 ​

POST /v3/keywords_data/google_ads/keywords_for_site/live

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

/v3/keywords_data/google_ads/keywords_for_site/live

本接口基于最新版 Google Ads API，可根据指定的网站域名或网页 URL 获取，并返回出价、近月搜索量、近一年搜索趋势及竞争程度等数据。

> 频率限制：Google Ads Live 接口单个账户每分钟最多可发送 12 个请求。
> 数据范围：最长可查询近 4 年的历史数据。
> 返回数量：单次请求最多返回 2,000 个。无论返回多少，均按请求次数计费。

计费说明 ​

每次请求都会产生费用。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

所有 POST 请求使用 UTF-8 编码的 JSON 格式。Live 接口每次请求只能提交一个任务，任务参数放在 JSON 数组中。

请求参数 ​

参数类型填说明
targetstring是目标网站域名或目标网页 URL。结合 target_type 确定获取整个网站或指定页面的。
target_typestring否搜索范围。可选值：site、page。默认值为 page。site 表示获取整个网站的；page 表示获取指定页面的。
location_namestring否搜索引擎地域的完整名称，例如 London,England,United Kingdom。未指定时返回范围结果。使用此参数时，不要同时提交 location_code 或 location_coordinate。可通过 /v3/keywords_data/google_ads/locations 获取可用地域。
location_codeinteger否搜索引擎地域代码，例如 2840。未指定时返回范围结果。使用此参数时，不要同时提交 location_name 或 location_coordinate。
location_coordinatestring否地域 GPS 坐标，格式为 "纬度,经度"，例如 52.6178549,-155.352142。数据将该坐标所属国家返回。使用此参数时，不要同时提交 location_name 或 location_code。
language_namestring否搜索引擎语言的完整名称，例如 English。可通过 /v3/keywords_data/google_ads/languages 获取可用语言。
language_codestring否搜索引擎语言代码，例如 en。
search_partnersboolean否是否 Google 搜索合作伙伴网络。true：返回 Google 及合作伙伴网站的数据；false：返回 Google 搜索网站数据。默认值为 false。
date_fromstring否查询起始日期，格式为 yyyy-mm-dd。默认查询过去 12 个月。最早可设置为当前日期前 4 年。该日期不能晚于 date_to 或昨天。可用的最早月份取决于状态接口 /v3/keywords_data/google_ads/status 返回的 actual_data 值。
date_tostring否查询结束日期，格式为 yyyy-mm-dd。不能晚于昨天。未指定时默认使用昨天，例如 "2022-11-30"。
include_adult_keywordsboolean否是否与成人的。默认值为 false。即使设置为 true，受 Google Ads 政策限制，也可能没有数据。
sort_bystring否结果排序字段。可选值：relevance、search_volume、competition_index、low_top_of_page_bid、high_top_of_page_bid。结果按所选字段降序排列。默认值为 relevance。
tagstring否自定义任务标识，用于请求与响应，最长 255 个字符。提交后可在响应的 data 对象中获取。

日期参数说明 ​

  • date_from 和 date_to 均使用 yyyy-mm-dd 格式。
  • date_to 不能昨天。
  • 如果状态接口的 actual_data 为 false，date_from 可以设置为上上个月及更早日期。
  • 如果 actual_data 为 true，date_from 可以设置为上个月及更早日期。

请求示例 ​

curl ​

bash
curl --location --request POST \
  "https://api.seermartech.cn/v3/keywords_data/google_ads/keywords_for_site/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "location_name": "United States",
      "target": "example.com",
      "target_type": "site",
      "language_code": "en",
      "search_partners": false
    }
  ]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/keywords_data/google_ads/keywords_for_site/live"

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

payload = [
    {
        "location_name": "United States",
        "target": "example.com",
        "target_type": "site",
        "language_code": "en",
        "search_partners": False,
    }
]

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

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        f"请求失败，错误码：{result.get('status_code')}，"
        f"错误信息：{result.get('status_message')}"
    )

TypeScript ​

typescript
import axios from "axios";

const payload = [
  {
    location_name: "United States",
    target: "example.com",
    target_type: "site",
    language_code: "en",
    search_partners: false,
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/keywords_data/google_ads/keywords_for_site/live",
    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 数据，顶层 tasks 数组。

顶层响应字段 ​

字段类型说明
versionstring当前 API 版本。
status_codeinteger通用响应状态码。成功通常为 20000。完整错误码请参考 /v3/appendix/errors。
status_messagestring通用状态说明。
timestring请求执行耗时，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_countintegertasks 数组中的任务数量。
tasks_errorintegertasks 数组中返回错误的任务数量。
tasksarray任务结果数组。

任务字段 ​

字段类型说明
idstring任务唯一标识，UUID 格式。
status_codeinteger任务状态码，通常在 10000 至 60000 范围。
status_messagestring任务状态说明。
timestring任务执行耗时，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_countintegerresult 数组中的结果数量。
patharray请求路径信息。
dataobject创建任务时提交的参数及任务数据。
resultarray结果数组。

结果字段 ​

字段类型说明
keywordstring返回的。
location_codeinteger / null地域代码。无数据时为 null。
language_codestring / null语言代码。无数据时为 null。
search_partnersboolean是否 Google 搜索合作伙伴网络。
competitionstring / null付费搜索结果中的相对竞争程度。可选值：LOW、MEDIUM、HIGH。未知时为 null。
competition_indexinteger / null竞争指数，范围为 0 至 100。该值根据已填广告位数量与可用广告位总数计算。数据不足时为 null。
search_volumeinteger / null月均搜索量，为目标地域下的估算值。无数据时为 null。
low_top_of_page_bidfloat / null广告出现在搜索结果首页顶部所需的较低参考出价，约高于历史最低展示出价的 20%。该值会因地域不同而变化。
high_top_of_page_bidfloat / null广告出现在搜索结果首页顶部所需的较高参考出价，约高于历史最低展示出价的 80%。该值会因地域不同而变化。
cpcfloat / null每次点击费用参考值。金额字段的币种及数值以接口返回口径为准。
monthly_searchesarray / null过去 12 个月的月度搜索量数据。无数据时为 null。
keyword_annotationsobject注释信息。
conceptsarray对应的概念列表。

monthly_searches 字段 ​

字段类型说明
yearinteger年份。
monthinteger月份。
search_volumeinteger当月估算搜索量。

keyword_annotations.concepts 字段 ​

字段类型说明
namestring概念名称。
concept_groupobject概念所属分组。
concept_group.namestring概念分组名称。
concept_group.typestring概念分组类型。

响应示例 ​

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": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "3.5000 sec.",
      "cost": 0.075,
      "result_count": 4,
      "path": [
        "v3",
        "keywords_data",
        "google_ads",
        "keywords_for_site",
        "live"
      ],
      "data": {
        "api": "keywords_data",
        "function": "keywords_for_site",
        "se": "google_ads",
        "target": "example.com",
        "target_type": "site",
        "location_code": 2840,
        "language_code": "en",
        "search_partners": false
      },
      "result": [
        {
          "keyword": "example seo tools",
          "location_code": 2840,
          "language_code": "en",
          "search_partners": false,
          "competition": "LOW",
          "competition_index": 12,
          "search_volume": 110,
          "low_top_of_page_bid": 104.34,
          "high_top_of_page_bid": 264.96,
          "cpc": 3.94,
          "monthly_searches": [
            {
              "year": 2024,
              "month": 11,
              "search_volume": 110
            }
          ],
          "keyword_annotations": {
            "concepts": [
              {
                "name": "SEO tools",
                "concept_group": {
                  "name": "Marketing",
                  "type": "CATEGORY"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

状态码与错误处理 ​

建议客户端同时检查以下字段：

  • 顶层 status_code
  • 任务级 tasks[].status_code
  • 对应的 status_message

当 tasks_error 大于 0 时，说明至少有一个任务处理失败。完整状态码和错误信息请参考：

/v3/appendix/errors

实用场景 ​

  • 挖掘网站，批量发现目标域名覆盖不足的搜索需求，扩 SEO 库。
  • 筛选高搜索量、低竞争，识别更自然排名潜力的主题，提升产出比。
  • 分析 CPC 与顶部出价，评估商业价值和广告竞争强度，为 SEO 与 SEM 联合决策提供依据。
  • 对比不同地域和语言的需求，制定本地化及市场扩张策略。
  • 追踪近一年月度搜索趋势，识别季节性需求变化，优化发布时间和营销资源。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API