SeerMarTech API 文档

主题

Google Ads 拓展（实时） ​

POST /v3/keywords_data/google_ads/keywords_for_keywords/live

接口说明 ​

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

/v3/keywords_data/google_ads/keywords_for_keywords/live

根据指定的获取建议及核心指标。单次请求最多提交 20 个，最多可返回 20,000 条建议。

本接口基于最新版 Google Ads API。历史数据最长支持查询近 4 年。

> 调用限制 > > - 每个账户通过 Google Ads 实时接口每分钟最多发送 12 个请求。 > - 每次实时 API 请求只能 1 个任务。 > - 账户整体每分钟最多可发送 2,000 次 API 调用。 > - 无论返回多少条，每次请求均会计费。

计费说明 ​

参考价约 ¥0.54 / 次。

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

请求参数 ​

请求体使用 UTF-8 编码的 JSON 数组格式：

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

任务参数 ​

参数类型填说明
keywordsarray是用于获取的种子列表。最多 20 个；每个最长 80 个字符。平台会将转换为小写。部分组合可能没有返回数据。Google Ads 不使用部分特殊符号、Unicode 符号或表字符。
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否地理坐标，格式为 "纬度,经度"，例如 52.6178549,-155.352142。数据将该坐标所属国家提供。使用此参数时，无需同时传 location_name 或 location_code。
language_namestring否搜索语言的完整名称，例如 English。可通过 /v3/keywords_data/google_ads/languages 获取可用语言。
language_codestring否搜索语言编码，例如 en。可通过 /v3/keywords_data/google_ads/languages 获取可用语言编码。
search_partnersboolean否是否 Google 搜索合作伙伴网络的数据。true 表示 Google 自有、运营及合作伙伴搜索网络；false 返回 Google 搜索网站数据。默认值为 false。
date_fromstring否数据起始日期，格式为 yyyy-mm-dd。最早可设置为当前日期前 4 年。未指定时默认查询过去 12 个月。该日期不能晚于 date_to 或昨天。
date_tostring否数据结束日期，格式为 yyyy-mm-dd，例如 "2022-11-30"。不能晚于昨天。未指定时默认使用昨天。
sort_bystring否返回结果的排序字段，支持 relevance、search_volume、competition_index、low_top_of_page_bid、high_top_of_page_bid。结果按降序排列。默认值为 relevance。
include_adult_keywordsboolean否是否返回与成人的。默认值为 false。即使设为 true，Google Ads 仍可能因政策限制而不返回数据。
tagstring否用户自定义任务标识，最长 255 个字符。可用于请求与响应，指定的值会原样返回在响应的 data 对象中。

日期限制 ​

如果状态接口 /v3/keywords_data/google_ads/status 返回的 actual_data 为：

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

请求示例 ​

cURL ​

bash
curl --location --request POST \
  "https://api.seermartech.cn/v3/keywords_data/google_ads/keywords_for_keywords/live" \
  --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"
      ],
      "search_partners": false,
      "sort_by": "relevance"
    }
  ]'

Python ​

python
import requests

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

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

# 请求体是 JSON 数组
payload = [
    {
        "location_name": "United States",
        "language_code": "en",
        "keywords": [
            "seo tools",
            "keyword research"
        ],
        "search_partners": False,
        "sort_by": "relevance"
    }
]

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

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

TypeScript ​

typescript
import axios from "axios";

const payload = [
  {
    location_name: "United States",
    language_code: "en",
    keywords: ["seo tools", "keyword research"],
    search_partners: false,
    sort_by: "relevance",
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/keywords_data/google_ads/keywords_for_keywords/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。
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当前请求的 URL 路径信息。
dataobject请求时提交的参数。
resultarray建议结果数组。

result 字段 ​

字段类型说明
keywordstring返回的。
location_codeinteger地域编码。无数据时为 null。
language_codestring语言编码。无数据时为 null。
search_partnersboolean是否 Google 搜索合作伙伴网络。
competitionstring付费搜索结果中的竞争程度。可选值：LOW、MEDIUM、HIGH；未知时为 null。
competition_indexinteger竞争指数，取值范围为 0 至 100。根据已填广告位数量与可用广告位总数计算。数据不足时为 null。
search_volumeinteger月均搜索量，为近似值。无数据时为 null。
low_top_of_page_bidfloat广告展示在搜索结果首页顶部所需的较低出价估算值。该值约高于广告展示所需最低出价的 20%。
high_top_of_page_bidfloat广告展示在搜索结果首页顶部所需的较高出价估算值。该值约高于广告展示所需最低出价的 80%。
cpcfloat每次点击费用估算值。
monthly_searchesarray过去 12 个月的月度搜索量数据。无数据时为 null。
keyword_annotationsobject注释信息。
keyword_annotations.conceptsarray对应的概念列表；无数据时为 null。

low_top_of_page_bid、high_top_of_page_bid 和 cpc 可能因请求中指定的地域不同而变化。

monthly_searches 字段 ​

字段类型说明
yearinteger年份。
monthinteger月份。
search_volumeinteger该月的搜索量。

keyword_annotations.concepts 字段 ​

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

响应示例 ​

json
{
  "version": "0.1.20231117",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "1.8776 sec.",
  "cost": 0.075,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "1.8000 sec.",
      "cost": 0.075,
      "result_count": 2,
      "path": [
        "v3",
        "keywords_data",
        "google_ads",
        "keywords_for_keywords",
        "live"
      ],
      "data": {
        "api": "keywords_data",
        "function": "keywords_for_keywords",
        "se": "google_ads",
        "location_code": 2840,
        "keywords": [
          "seo tools"
        ]
      },
      "result": [
        {
          "keyword": "seo tools",
          "location_code": 2840,
          "language_code": "en",
          "search_partners": false,
          "competition": "MEDIUM",
          "competition_index": 55,
          "search_volume": 1000,
          "low_top_of_page_bid": 1.25,
          "high_top_of_page_bid": 4.80,
          "cpc": 2.10,
          "monthly_searches": [
            {
              "year": 2023,
              "month": 11,
              "search_volume": 1000
            }
          ],
          "keyword_annotations": {
            "concepts": null
          }
        },
        {
          "keyword": "adsense rpm average",
          "location_code": 2840,
          "language_code": null,
          "search_partners": false,
          "competition": "LOW",
          "competition_index": 0,
          "search_volume": 20,
          "low_top_of_page_bid": null,
          "high_top_of_page_bid": null,
          "cpc": null,
          "monthly_searches": [],
          "keyword_annotations": {
            "concepts": null
          }
        }
      ]
    }
  ]
}

状态码与错误处理 ​

请根据顶层 status_code 和任务级 tasks[].status_code 判断请求是否成功：

  • 20000：请求或任务执行成功；
  • 状态码：请求或任务执行失败，应结合对应的 status_message 排查原因。

建议在业务系统中同时处理以下：

  • 请求频率 Google Ads 实时接口限制；
  • 不支持的特殊字符；
  • 指定的地域或语言不存在；
  • 日期范围出可用历史数据范围；
  • Google Ads 对成人或特定组合不返回数据；
  • 返回结果为空或部分字段为 null。

实用场景 ​

  • 拓展种子：根据核心词批量获取搜索词，扩大 SEO和落地页的覆盖范围。
  • 筛选高价值：结合搜索量、竞争指数和首页顶部出价，优确定流量潜力高且商业价值明确的词。
  • 规划主题：利用概念注释和词建议，聚合同一搜索意图下的主题，构建集群。
  • 评估地域需求：按国家、城市或坐标查询数据，为本地 SEO 和区域投放制定策略。
  • 分析季节性趋势：读取近 12 个月的月度搜索量，识别季节性需求并安排发布或营销活动。

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

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