建议

POST /v3/dataforseo_labs/google/keyword_suggestions/live

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

/v3/dataforseo_labs/google/keyword_suggestions/live

建议接口用于查询指定种子的搜索词。系统基于匹算法，在种子前、后或中间匹词语，因此返回的建议可能改变种子中词语的顺序。

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

google research keyword
how to do keyword research
keyword competitor research
how to do keyword research for content marketing

每个建议通常近月搜索量、过去 12 个月的搜索量趋势、每次点击费用（CPC）和竞争程度等数据。

数据源：数据库
搜索算法：搜索，匹种子及前后或中间附加词语的搜索词
单次调用任务数：每个 Live 请求支持 1 个任务平台限流以认证说明中的 30/60/120 次/分钟规则为准/分钟
并发限制：最多 30 个并发请求
请求格式：UTF-8 编码的 JSON 数组
结果控制：支持数量限制、分页、筛选和排序

计费说明

本接口按请求计费。启用 include_clickstream_data=true 时，请求费用按基础费用的 2 倍计算。

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

请求参数

请求体为 JSON 数组，数组中只能一个任务对象。

参数	类型	填	说明
`keyword`	string	是	种子。使用 UTF-8 编码，系统会将转换为小写。
`location_name`	string	否	地理位置的完整名称，例如 `United Kingdom`。指定后无需再传 `location_code`。不传时返回所有可用位置的结果。
`location_code`	integer	否	地理位置代码，例如 `2840`。指定后无需再传 `location_name`。不传时返回所有可用位置的结果。
`language_name`	string	否	语言完整名称，例如 `English`。指定后无需再传 `language_code`。
`language_code`	string	否	语言代码，例如 `en`。指定后无需再传 `language_name`。
`include_seed_keyword`	boolean	否	是否返回种子本身的数据。为 `true` 时，结果位于 `seed_keyword_data`。默认值为 `false`。
`include_serp_info`	boolean	否	是否返回每个的搜索结果页数据搜索结果数量、查询 URL 和 SERP 特征。默认值为 `false`。
`include_clickstream_data`	boolean	否	是否返回基于点击流数据计算的指标。为 `true` 时，响应中会 `clickstream_keyword_info`、`keyword_info_normalized_with_clickstream` 和 `keyword_info_normalized_with_bing`。默认值为 `false`，启用后费用加倍。
`exact_match`	boolean	否	是否按精确短语搜索。为 `true` 时，返回结果完整种子短语，但短语前后仍可出现词语。默认值为 `false`。
`ignore_synonyms`	boolean	否	是否排除高度相似的。为 `true` 时返回核心，排除高度相似词。默认值为 `false`。
`filters`	array	否	结果筛选条件，最多支持 8 个过滤器。多个条件之间使用 `and` 或 `or`。
`order_by`	array	否	结果排序规则。最多支持 3 条规则，可使用与 `filters` 相同的字段和值。
`limit`	integer	否	最多返回的数量。默认值为 `100`，最大值为 `1000`。
`offset`	integer	否	结果偏移量。默认值为 `0`。例如设置为 `10`，则跳过前 10 条结果。建议在获取不 10000 条结果时使用。
`offset_token`	string	否	后续分页令牌。用于获取 10000 条结果时的后续数据。指定该参数后，除 `limit` 外的参数将不会生效。
`tag`	string	否	自定义任务标识，最长 255 个字符。该值会原样返回在响应的 `data` 对象中。

地理位置与语言

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

/v3/dataforseo_labs/locations_and_languages

location_name 与 location_code 二选一。
language_name 与 language_code 二选一。
未指定语言时，系统默认使用指定位置中记录最多的语言。

筛选条件

支持的操作符：

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

like、not_like、ilike 和 not_ilike 支持使用 % 匹零个或多个字符。

示例：

json

"filters": [
  ["keyword", "like", "%phone%"],
  "and",
  ["keyword_info.search_volume", ">=", 1000]
]

排序规则

排序方向支持：

asc：升序
desc：降序

示例：

json

"order_by": [
  ["keyword_info.search_volume", "desc"],
  ["keyword", "asc"]
]

响应字段

响应为 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	请求 URL 路径。
`data`	object	请求中提交的任务参数。
`result`	array	任务结果数组。

`result` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型，通常为 `google`。
`seed_keyword`	string	请求中提交的种子。
`seed_keyword_data`	object	种子数据。在 `include_seed_keyword=true` 时返回，字段结构与 `items` 中的数据一致。
`location_code`	integer	请求中的位置代码。无数据时为 `null`。
`language_code`	string	请求中的语言代码。无数据时为 `null`。
`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	基于点击流数据的指标。需启用 `include_clickstream_data`。
`keyword_properties`	object	附加属性。
`serp_info`	object	SERP 数据。需启用 `include_serp_info`，否则可能为 `null`。
`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	付费搜索结果中的竞争等级，可选值为 `LOW`、`MEDIUM`、`HIGH`；未知时为 `null`。
`cpc`	float	历史平均每次点击费用。
`search_volume`	integer	平均月搜索量，表示该在搜索引擎中的近似月搜索次数。
`low_top_of_page_bid`	float	广告出现在首页顶部所需的较低参考出价。
`high_top_of_page_bid`	float	广告出现在首页顶部所需的较高参考出价。
`categories`	array	产品和服务分类。
`monthly_searches`	array	过去 12 个月的月度搜索量。
`search_volume_trend`	object	搜索量变化趋势。

monthly_searches 中的字段：

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

search_volume_trend 中的字段：

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

`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 字段：

female：点击流数据集中的女性用户数量
male：点击流数据集中的男性用户数量

age_distribution 字段：

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

以上字段表示对应年龄段的用户数量。

`keyword_properties` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型。
`core_keyword`	string	同义词分组中的核心。无法识别同义词时为 `null`。
`synonym_clustering_algorithm`	string	同义词聚类算法。可选值为 `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 数据时，该字段为 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 可能：

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、people_also_search、shopping、top_stories、twitter、video、events、mention_carousel、recipes、top_sights、scholarly_articles、popular_products、podcasts、questions_and_answers、find_results_on、stocks_box、visual_stories、commercial_units、local_services、google_hotels、math_solver、currency_box、product_considerations、found_on_web、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	补搜索意图。
`last_updated_time`	string	搜索意图数据更新时间。

归一化指标

`keyword_info_normalized_with_bing`

字段	类型	说明
`last_updated_time`	string	数据集更新时间。
`search_volume`	integer	当前归一化搜索量。
`is_normalized`	boolean	是否已使用 Bing 数据归一化。
`monthly_searches`	array	月度归一化搜索量， `year`、`month` 和 `search_volume`。

`keyword_info_normalized_with_clickstream`

字段	类型	说明
`last_updated_time`	string	数据集更新时间。
`search_volume`	integer	当前归一化搜索量。
`is_normalized`	boolean	是否已使用点击流数据归一化。
`monthly_searches`	array	月度归一化搜索量， `year`、`month` 和 `search_volume`。

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/dataforseo_labs/google/keyword_suggestions/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "keyword": "phone",
      "location_code": 2840,
      "language_name": "English",
      "include_serp_info": true,
      "include_seed_keyword": true,
      "limit": 1
    }
  ]'

Python

python

import requests

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

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

payload = [
    {
        "keyword": "phone",
        "location_name": "United States",
        "language_name": "English",
        "include_serp_info": True,
        "include_seed_keyword": True,
        "limit": 1,
    }
]

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

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败，状态码：%s，消息：%s"
        % (result.get("status_code"), result.get("status_message"))
    )

TypeScript

typescript

import axios from "axios";

const payload = [
  {
    keyword: "phone",
    location_code: 2840,
    language_name: "English",
    include_serp_info: true,
    include_seed_keyword: true,
    limit: 1,
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/dataforseo_labs/google/keyword_suggestions/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

{
  "version": "0.1.20240801",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.2704 sec.",
  "cost": 0.0101,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "742708d0-fc28-430f-8707-4afecbbd480dc",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1234 sec.",
      "cost": 0.0101,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "google",
        "keyword_suggestions",
        "live"
      ],
      "data": {
        "api": "dataforseo_labs",
        "function": "keyword_suggestions",
        "se_type": "google",
        "keyword": "phone",
        "location_code": 2840,
        "language_code": "en",
        "include_serp_info": true,
        "include_seed_keyword": true,
        "limit": 1
      },
      "result": [
        {
          "se_type": "google",
          "seed_keyword": "phone",
          "location_code": 2840,
          "language_code": "en",
          "total_count": 3488300,
          "items_count": 1,
          "offset": 0,
          "offset_token": "eyJjdXJyZW50X29mZnNldCI6MX0=",
          "items": [
            {
              "se_type": "google",
              "keyword": "boost cell phone",
              "location_code": 2840,
              "language_code": "en",
              "keyword_info": {
                "se_type": "google",
                "last_updated_time": "2024-07-15 00:43:34 +00:00",
                "competition": 0.92,
                "competition_level": "HIGH",
                "cpc": 1.25,
                "search_volume": 2900,
                "low_top_of_page_bid": 0.85,
                "high_top_of_page_bid": 2.10,
                "categories": [],
                "monthly_searches": [],
                "search_volume_trend": {
                  "monthly": 22,
                  "quarterly": 22,
                  "yearly": 0
                }
              },
              "clickstream_keyword_info": null,
              "keyword_properties": {
                "se_type": "google",
                "core_keyword": null,
                "synonym_clustering_algorithm": "text_processing",
                "keyword_difficulty": 0,
                "detected_language": "en",
                "is_another_language": false,
                "words_count": 3
              },
              "serp_info": {
                "se_type": "google",
                "check_url": "https://www.google.com/search?q=boost%20cell%20phone",
                "serp_item_types": [
                  "organic",
                  "paid"
                ],
                "se_results_count": "115000000",
                "last_updated_time": "2024-08-04 08:25:36 +00:00",
                "previous_updated_time": "2024-06-22 17:54:36 +00:00"
              },
              "avg_backlinks_info": {
                "se_type": "google",
                "backlinks": 4739.3,
                "dofollow": 2334.9,
                "referring_pages": 4121.3,
                "referring_domains": 210.3,
                "referring_main_domains": 184.2,
                "rank": 113.1,
                "main_domain_rank": 512.4,
                "last_updated_time": "2024-08-04 08:25:38 +00:00"
              },
              "search_intent_info": {
                "se_type": "google",
                "main_intent": "transactional",
                "foreign_intent": null,
                "last_updated_time": "2023-12-14 04:27:21 +00:00"
              },
              "keyword_info_normalized_with_bing": {
                "last_updated_time": "2024-08-17 06:05:32 +00:00",
                "search_volume": 2893,
                "is_normalized": true,
                "monthly_searches": []
              },
              "keyword_info_normalized_with_clickstream": {
                "last_updated_time": "2024-08-17 06:05:32 +00:00",
                "search_volume": 197,
                "is_normalized": true,
                "monthly_searches": []
              }
            }
          ]
        }
      ]
    }
  ]
}

status_code=20000 表示请求成功。完整状态码和错误信息请参考错误码文档。

实用场景

扩展种子：围绕核心词批量发现长尾搜索词，为库建设和选题提供依据。
筛选高潜力：结合搜索量、竞争度、CPC 和难度，优选择流量潜力高且竞争可控的词。
分析季节性：利用过去 12 个月的月度搜索量和趋势数据，安排季节性与投放计划。
识别搜索意图：根据 search_intent_info 区分信息型、导航型、商业型和交易型，优化页面类型与转化路径。
评估 SERP 竞争环境：结合 SERP 特征、前 10 名页面的平均外链和排名指标，判断的自然排名难度。

建议 ​

计费说明 ​

请求参数 ​

地理位置与语言 ​

筛选条件 ​

排序规则 ​

响应字段 ​

顶层响应字段 ​

tasks 字段 ​

result 字段 ​

items 字段 ​

keyword_info 字段 ​

clickstream_keyword_info 字段 ​

keyword_properties 字段 ​

serp_info 字段 ​

avg_backlinks_info 字段 ​

search_intent_info 字段 ​

归一化指标 ​

keyword_info_normalized_with_bing ​

keyword_info_normalized_with_clickstream ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

实用场景 ​

建议

计费说明

请求参数

地理位置与语言

筛选条件

排序规则

响应字段

顶层响应字段

`tasks` 字段

`result` 字段

`items` 字段

`keyword_info` 字段

`clickstream_keyword_info` 字段

`keyword_properties` 字段

`serp_info` 字段

`avg_backlinks_info` 字段

`search_intent_info` 字段

归一化指标

`keyword_info_normalized_with_bing`

`keyword_info_normalized_with_clickstream`

请求示例

cURL

Python

TypeScript

响应示例

实用场景