Google Keyword Ideas 实时接口

POST /v3/dataforseo_labs/google/keyword_ideas/live

本接口使用 POST /v3/dataforseo_labs/google/keyword_ideas/live，根据最多 200 个种子所属的产品或服务类别，返回的建议及搜索数据。

每个建议可：

最近一个月的搜索量；
过去 12 个月的搜索量趋势；
点击费用（CPC）与竞争度；
首页顶部广告位的最低、最高出价；
难度、搜索意图、SERP 特征；
前 10 个自然排名页面的平均外链指标；
可选的点击流数据及性别、年龄分布。

**数据源：**按产品类别划分的数据库。
**搜索算法：**基于性的类别匹算法，查找与种子属于相同类别的搜索词。

例如，种子为 keyword research 和 content marketing 时，可能返回：

free adword tools
find longtail keywords
how to do keywords research
seo keyword research template

默认不启用额外排序，closely_variants 默认为 false。

请求地址

http

POST https://api.seermartech.cn/v3/dataforseo_labs/google/keyword_ideas/live

每次请求只能一个任务，但请求体是 JSON 数组。接口限制如下：

每个任务最多指定 200 个种子；平台限流以认证说明中的 30/60/120 次/分钟规则为准；
同时处理的请求数最多为 30；
所有请求数据使用 UTF-8 编码的 JSON 格式。

计费说明

接口按请求计费。启用 include_clickstream_data 后，单次请求费用按基础价格的 2 倍计算。

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

请求参数

参数	类型	填	说明
`keywords`	array	是	种子数组，最多 200 个。会被转换为小写格式。
`location_name`	string	条件填	地理位置名。未指定 `location_code` 时填。
`location_code`	integer	条件填	地理位置唯一标识。未指定 `location_name` 时填。指定 `location_name` 或 `location_code` 一个。
`language_name`	string	否	语言名。指定后无需指定 `language_code`。
`language_code`	string	否	语言代码。指定后无需指定 `language_name`。
`closely_variants`	boolean	否	搜索模式。`true` 使用词组匹，`false` 使用广泛匹。默认值为 `false`。
`ignore_synonyms`	boolean	否	是否排除高度相似的。`true` 返回核心，默认值为 `false`。
`include_serp_info`	boolean	否	是否返回每个的 SERP 数据结果数量、 URL 和 SERP 特征。默认值为 `false`。
`include_clickstream_data`	boolean	否	是否返回点击流指标。设为 `true` 时，将返回 `clickstream_keyword_info`、`keyword_info_normalized_with_clickstream` 和 `keyword_info_normalized_with_bing`。默认值为 `false`。
`limit`	integer	否	`items` 数组最多返回的数量。默认值为 `700`，最大值为 `1000`。
`offset`	integer	否	结果偏移量。默认值为 `0`。例如设置为 `10`，将跳过前 10 条结果。建议在获取不 10,000 条结果时使用。
`offset_token`	string	否	后续分页令牌。适用于获取 10,000 条结果的场景。指定该参数后，除 `limit` 外的参数不会参与任务处理。
`filters`	array	否	结果过滤条件，最多 8 个。不能按 `relevance` 过滤。
`order_by`	array	否	结果排序规则，最多设置 3 条。支持升序 `asc` 和降序 `desc`。
`tag`	string	否	自定义任务标识，最多 255 个字符。该值会原样返回在响应的 `data` 对象中。

地理位置与语言

可通过以下接口查询可用的位置和语言：

http

GET https://api.seermartech.cn/v3/dataforseo_labs/locations_and_languages

示例：

json

{
  "location_name": "United Kingdom",
  "location_code": 2840,
  "language_name": "English",
  "language_code": "en"
}

如果不指定语言，接口默认使用指定位置中记录最多的语言。

过滤器

过滤器格式为：

json

[
  ["keyword_info.search_volume", ">", 100],
  "and",
  ["keyword_info.competition_level", "=", "LOW"]
]

支持的运算符：

text

regex、not_regex、<、<=、>、>=、=、<>、
in、not_in、match、not_match、
ilike、not_ilike、like、not_like

like、not_like、ilike 和 not_ilike 支持使用 % 匹任意长度的字符串。

排序

默认性分数 relevance 降序排列，以优返回最的建议。relevance 用于排序，不能作为过滤条件，也不会出现在结果字段中。

排序示例：

json

[
  ["keyword_info.search_volume", "desc"],
  ["keyword_info.cpc", "desc"]
]

请求示例

curl

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/dataforseo_labs/google/keyword_ideas/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "keywords": ["phone", "watch"],
      "location_code": 2840,
      "language_code": "en",
      "include_serp_info": true,
      "filters": [
        ["keyword_info.search_volume", ">", 10]
      ],
      "limit": 3
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/google/keyword_ideas/live"

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

payload = [
    {
        "keywords": ["phone", "watch"],
        "location_name": "United States",
        "language_name": "English",
        "filters": [
            ["keyword_info.search_volume", ">", 10]
        ],
        "limit": 3,
    }
]

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 = [
  {
    keywords: ["phone", "watch"],
    location_code: 2840,
    language_name: "English",
    filters: [
      ["keyword_info.search_volume", ">", 10],
    ],
    limit: 3,
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/dataforseo_labs/google/keyword_ideas/live",
    payload,
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    const result = response.data;

    if (result.status_code === 20000) {
      console.log(result);
    } else {
      console.error(
        `请求失败，错误码：${result.status_code}，错误信息：${result.status_message}`
      );
    }
  })
  .catch((error) => {
    console.error("网络请求失败：", error.message);
  });

响应结构

接口返回 JSON 数据，顶层 tasks 数组。

顶层字段

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

任务字段

字段	类型	说明
`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	请求 URL 路径。
`data`	object	创建任务时提交的参数。
`result`	array	建议结果。

结果字段

`result`

字段	类型	说明
`se_type`	string	搜索引擎类型，例如 `google`。
`seed_keywords`	array	请求中提交的种子。经过 URL 编码的会被解码，`+` 会转换为空格。
`location_code`	integer	请求中的地理位置代码。
`language_code`	string	请求中的语言代码。
`total_count`	integer	数据库中与请求的结果总数。
`items_count`	integer	本次返回的 `items` 数量。
`offset`	integer	当前结果偏移量。
`offset_token`	string	后续分页令牌。可用于获取当前任务的下一批结果。每次后续任务使用的令牌均不相同。
`items`	array	建议及数据。

`items`

字段	类型	说明
`se_type`	string	搜索引擎类型。
`keyword`	string	返回的建议。
`location_code`	integer	地理位置代码。
`language_code`	string	语言代码。
`keyword_info`	object	基础指标。
`clickstream_keyword_info`	object/null	点击流指标。在 `include_clickstream_data=true` 时返回。
`keyword_properties`	object	附加信息。
`serp_info`	object/null	SERP 数据。在 `include_serp_info=true` 且数据库存在数据时返回。
`avg_backlinks_info`	object	排名前 10 的自然结果页面的平均外链指标。
`search_intent_info`	object	搜索意图信息。
`keyword_info_normalized_with_bing`	object	使用 Bing 搜索量进行归一化后的指标。
`keyword_info_normalized_with_clickstream`	object	使用点击流数据归一化后的指标。

`keyword_info` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型。
`last_updated_time`	string	数据更新时间，UTC 格式：`yyyy-MM-dd HH:mm:ss +00:00`。
`competition`	float	竞争度，取值范围为 `0-1`，基于广告数据计算。
`competition_level`	string/null	付费 SERP 竞争级别，可选值为 `LOW`、`MEDIUM`、`HIGH`。未知时为 `null`。
`cpc`	float	每次点击费用，原始数据通常以计价。人民币扣费以响应头 `X-SeerMarTech-Charge-CNY` 为准。
`search_volume`	integer	平均月搜索量，表示指定区域在 Google 上的估算搜索次数。
`low_top_of_page_bid`	float	广告展示在首页顶部位置所需的较低出价估计值。
`high_top_of_page_bid`	float	广告展示在首页顶部位置所需的较高出价估计值。
`categories`	array	产品和服务类别。
`monthly_searches`	array	过去 12 个月的月度搜索量。
`search_volume_trend`	object	搜索量趋势变化。

search_volume_trend 字段：

字段	类型	说明
`monthly`	integer	相比上个月的搜索量变化百分比。
`quarterly`	integer	相比上一季度的搜索量变化百分比。
`yearly`	integer	相比上一年的搜索量变化百分比。

monthly_searches 数组中的对象：

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

`keyword_properties` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型。
`core_keyword`	string/null	同义词分组中的核心。无法识别同义词时为 `null`。
`synonym_clustering_algorithm`	string/null	同义词聚类算法。`keyword_metrics` 表示基于指标，`text_processing` 表示基于文本处理。
`keyword_difficulty`	integer	难度，范围为 `0-100`，用于表示自然搜索结果前 10 名的难度。
`detected_language`	string	系统识别出的语言。
`is_another_language`	boolean	识别出的语言是否与请求指定语言不同。
`words_count`	integer	的单词数量。

`serp_info` 字段

未启用 include_serp_info，或数据库中没有该的 SERP 数据时，serp_info 为 null。

字段	类型	说明
`se_type`	string	搜索引擎类型。
`check_url`	string	对应的搜索结果页 URL，可用于校验结果。
`serp_item_types`	array	SERP 中出现的结果类型。
`se_results_count`	string	搜索结果数量。
`last_updated_time`	string	SERP 数据更新时间。
`previous_updated_time`	string	上一次 SERP 数据更新时间。

常见 serp_item_types括：

text

answer_box、app、carousel、multi_carousel、featured_snippet、
google_flights、google_reviews、third_party_reviews、google_posts、
images、jobs、knowledge_graph、local_pack、hotels_pack、map、
organic、paid、people_also_ask、related_searches、shopping、
top_stories、video、events、recipes、scholarly_articles、
popular_products、podcasts、questions_and_answers、local_services、
google_hotels、math_solver、currency_box、product_considerations、
short_videos、refine_products、explore_brands、perspectives、
discussions_and_forums、compare_sites、courses、ai_overview

结果明细会针对 organic、paid、featured_snippet 和 local_pack素返回。

`avg_backlinks_info` 字段

该对象表示自然搜索结果前 10 个页面的平均外链和排名指标。

字段	类型	说明
`se_type`	string	搜索引擎类型。
`backlinks`	float	平均反向链接数量。
`dofollow`	float	平均 dofollow 链接数量。
`referring_pages`	float	平均引用页面数量。
`referring_domains`	float	平均引用域名数量。
`referring_main_domains`	float	平均引用主域名数量。
`rank`	float	平均页面排名。
`main_domain_rank`	float	平均主域名排名。
`last_updated_time`	string	外链数据更新时间。

`search_intent_info` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型，目前为 `google`。
`main_intent`	string	主要搜索意图。可选值：`informational`、`navigational`、`commercial`、`transactional`。
`foreign_intent`	array/null	补搜索意图，取值同 `main_intent`。
`last_updated_time`	string	搜索意图数据更新时间。

`clickstream_keyword_info` 字段

在请求中设置 include_clickstream_data=true 时返回。

字段	类型	说明
`search_volume`	integer	基于点击流数据的月平均搜索量。
`last_updated_time`	string	点击流数据集更新时间。
`gender_distribution`	object	按性别划分的估算点击流指标分布。
`age_distribution`	object	按年龄划分的估算点击流指标分布。
`monthly_searches`	array	按月份统计的点击流搜索量。

gender_distribution：

json

{
  "female": 0,
  "male": 0
}

age_distribution 支持以下字段：

text

18-24、25-34、35-44、45-54、55-64

归一化指标

`keyword_info_normalized_with_bing`

字段	类型	说明
`last_updated_time`	string	数据集更新时间。
`search_volume`	integer	当前搜索量。
`is_normalized`	boolean	是否已使用 Bing 数据完成归一化。
`monthly_searches`	array	按年月统计的归一化搜索量。

`keyword_info_normalized_with_clickstream`

字段	类型	说明
`last_updated_time`	string	数据集更新时间。
`search_volume`	integer	当前搜索量。
`is_normalized`	boolean	是否已使用点击流数据完成归一化。
`monthly_searches`	array	按年月统计的归一化搜索量。

两个 monthly_searches 数组中的对象均：

字段	类型	说明
`year`	integer	年份。
`month`	integer	月份。
`search_volume`	integer	对应月份的搜索量。

响应示例

json

{
  "version": "0.1.20240801",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.7097 sec.",
  "cost": 0.0103,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "b5a2dce9-4397-4758-aa28-65ab367d3948",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.7097 sec.",
      "cost": 0.0103,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "google",
        "keyword_ideas",
        "live"
      ],
      "data": {
        "api": "dataforseo_labs",
        "function": "keyword_ideas",
        "se_type": "google",
        "keywords": ["phone", "watch"],
        "location_code": 2840,
        "language_code": "en",
        "include_serp_info": true,
        "limit": 3
      },
      "result": [
        {
          "se_type": "google",
          "seed_keywords": ["phone", "watch"],
          "location_code": 2840,
          "language_code": "en",
          "total_count": 533763,
          "items_count": 3,
          "offset": 0,
          "offset_token": "NEXT_PAGE_TOKEN",
          "items": [
            {
              "se_type": "google",
              "keyword": "cell phone signal booster",
              "location_code": 2840,
              "language_code": "en",
              "keyword_info": {
                "se_type": "google",
                "last_updated_time": "2024-08-11 18:11:54 +00:00",
                "competition": 1,
                "competition_level": "HIGH",
                "cpc": 1.05,
                "search_volume": 22200,
                "low_top_of_page_bid": 0.31,
                "high_top_of_page_bid": 1.15,
                "categories": [10002, 10013],
                "monthly_searches": [
                  {
                    "year": 2024,
                    "month": 7,
                    "search_volume": 22200
                  }
                ],
                "search_volume_trend": {
                  "monthly": 22,
                  "quarterly": 22,
                  "yearly": 0
                }
              },
              "clickstream_keyword_info": null,
              "keyword_properties": {
                "se_type": "google",
                "core_keyword": "cell phone signal booster for phone",
                "synonym_clustering_algorithm": "text_processing",
                "keyword_difficulty": 23,
                "detected_language": "en",
                "is_another_language": false,
                "words_count": 4
              },
              "serp_info": {
                "se_type": "google",
                "check_url": "https://www.google.com/search?q=cell%20phone%20signal%20booster",
                "serp_item_types": ["organic", "paid", "people_also_ask"],
                "se_results_count": "13500000",
                "last_updated_time": "2024-08-04 11:06:04 +00:00",
                "previous_updated_time": "2024-06-22 20:35:21 +00:00"
              },
              "avg_backlinks_info": {
                "se_type": "google",
                "backlinks": 111.6,
                "dofollow": 34.7,
                "referring_pages": 104.5,
                "referring_domains": 29,
                "referring_main_domains": 26.3,
                "rank": 103.5,
                "main_domain_rank": 530.7,
                "last_updated_time": "2024-08-04 11:06:06 +00:00"
              },
              "search_intent_info": {
                "se_type": "google",
                "main_intent": "transactional",
                "foreign_intent": null,
                "last_updated_time": "2023-03-03 12:40:39 +00:00"
              },
              "keyword_info_normalized_with_bing": {
                "last_updated_time": "2024-08-16 10:43:48 +00:00",
                "search_volume": 12895,
                "is_normalized": true,
                "monthly_searches": []
              },
              "keyword_info_normalized_with_clickstream": {
                "last_updated_time": "2024-08-16 10:43:48 +00:00",
                "search_volume": 15498,
                "is_normalized": true,
                "monthly_searches": []
              }
            }
          ]
        }
      ]
    }
  ]
}

错误处理

请根据顶层 status_code、任务级 status_code 和 status_message 判断请求是否成功。建议对以下进行处理：

HTTP 请求失败；
顶层状态码非 20000；
tasks_error 大于 0；
单个任务的状态码非 20000；
分页令牌失效或结果为空；
请求参数冲突，例如同时传不匹的语言名称和语言代码。

实用场景

扩展种子词库：根据核心产品词批量发现同类别，扩大 SEO覆盖范围并减少人工调研成本。
筛选选题：结合搜索量、趋势和难度筛选潜力词，为博客、落地页和专题页制定优级。
识别商业机会：使用竞争度、CPC 和搜索意图定位高商业价值词，支持广告投放与转化页建设。
分析 SERP 竞争：获取 SERP 特征和前 10 名页面的平均外链指标，评估目标的排名门槛。
刻画搜索人群：启用点击流数据后分析性别、年龄及归一化搜索量，为定位和市场细分提供依据。

Google Keyword Ideas 实时接口 ​

请求地址 ​

计费说明 ​

请求参数 ​

地理位置与语言 ​

过滤器 ​

排序 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

任务字段 ​

结果字段 ​

result ​

items ​

keyword_info 字段 ​

keyword_properties 字段 ​

serp_info 字段 ​

avg_backlinks_info 字段 ​

search_intent_info 字段 ​

clickstream_keyword_info 字段 ​

归一化指标 ​

keyword_info_normalized_with_bing ​

keyword_info_normalized_with_clickstream ​

响应示例 ​

错误处理 ​

实用场景 ​

Google Keyword Ideas 实时接口

请求地址

计费说明

请求参数

地理位置与语言

过滤器

排序

请求示例

curl

Python

TypeScript

响应结构

顶层字段

任务字段

结果字段

`result`

`items`

`keyword_info` 字段

`keyword_properties` 字段

`serp_info` 字段

`avg_backlinks_info` 字段

`search_intent_info` 字段

`clickstream_keyword_info` 字段

归一化指标

`keyword_info_normalized_with_bing`

`keyword_info_normalized_with_clickstream`

响应示例

错误处理

实用场景