Google 实时查询

POST /v3/dataforseo_labs/google/related_keywords/live

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

/v3/dataforseo_labs/google/related_keywords/live

接口用于获取 Google 搜索结果页“搜索”区域中的。通过设置搜索深度，最多可获取约 4680 个建议。每个可产品或服务类别、最近一个月的搜索量、过去 12 个月的搜索趋势、每次点击费用（CPC）和竞争程度等数据。

数据源：平台 SERP 数据库
搜索算法：从指定种子对应 SERP 中的“搜索”词开始，采用深度优搜索
单次 Live 请求：支持 1 个任务平台限流以认证说明中的 30/60/120 次/分钟规则为准
并发限制：同时最多 30 个请求

计费说明

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

所有 POST 数据使用 UTF-8 编码的 JSON 格式，并且请求体是 JSON 数组，例如：

json

[
  {
    "keyword": "keyword research",
    "location_code": 2840,
    "language_code": "en",
    "depth": 1
  }
]

请求参数

基础参数

参数	类型	填	说明
`keyword`	string	是	种子，使用 UTF-8 编码。会被转换为小写格式。
`location_name`	string	条件填	地理位置完整名称。当未指定 `location_code` 时填。
`location_code`	integer	条件填	地理位置代码。当未指定 `location_name` 时填。
`language_name`	string	条件填	语言完整名称。当未指定 `language_code` 时填。
`language_code`	string	条件填	语言代码。当未指定 `language_name` 时填。
`depth`	integer	否	搜索深度，默认值为 `1`，可设置为 `0` 至 `4`。
`include_seed_keyword`	boolean	否	是否返回种子数据。设为 `true` 后，种子数据会出现在响应的 `seed_keyword_data` 数组中。默认值为 `false`。
`include_serp_info`	boolean	否	是否返回每个的 SERP 数据。设为 `true` 后，将返回搜索结果数量、 URL 和 SERP 特征等信息。默认值为 `false`。
`include_clickstream_data`	boolean	否	是否返回点击流数据。设为 `true` 后，响应中会 `clickstream_keyword_info`。
`ignore_synonyms`	boolean	否	是否忽略同义词。
`replace_with_core_keyword`	boolean	否	是否使用核心返回数据。默认值为 `false`。

地理位置与语言

指定以下任意一组参数：

location_name 或 location_code
language_name 或 language_code

可通过以下接口获取可用的地理位置和语言列表：

/v3/dataforseo_labs/locations_and_languages

示例：

json

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

`depth` 深度说明

深度	预计最大数量
`0`	返回 `keyword` 中的种子
`1`	约 8 个
`2`	约 72 个
`3`	约 584 个
`4`	约 4680 个

返回数量取决于数据库中与请求条件匹的结果数量。

`filters`

参数	类型	说明
`filters`	array	结果过滤条件，最多支持 8 个过滤器。

过滤条件需要通过逻辑运算符 and 或 or 连接。支持的操作符：

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

对于 like、not_like、ilike 和 not_ilike，可以使用 % 匹零个或多个字符。

示例：

json

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

`order_by`

参数	类型	说明
`order_by`	array	结果排序规则。可使用与 `filters` 相同的字段和表达式。

排序方向：

asc：升序
desc：降序

排序规则通常使用 "字段,方向" 的格式表示，单次请求最多设置 3 条排序规则。

示例：

json

"order_by": [
  "keyword_data.keyword_info.search_volume,desc",
  "keyword_data.keyword_info.competition,asc"
]

分页与任务标识

参数	类型	默认值	限制与说明
`limit`	integer	`100`	返回的最大数量，最大值为 `1000`。
`offset`	integer	`0`	结果偏移量。例如设置为 `10` 时，跳过前 10 条结果。
`tag`	string	-	用户自定义任务标识，最多 255 个字符。可用于匹请求和响应，指定值会出现在响应的 `data` 对象中。

响应结构

接口返回 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	任务结果数组。

任务字段

字段	类型	说明
`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	查询结果数组。

结果字段

字段	类型	说明
`se_type`	string	搜索引擎类型，通常为 `google`。
`seed_keyword`	string	请求中的种子。
`seed_keyword_data`	array	种子数据。字段结构与 `keyword_data` 相同在 `include_seed_keyword` 为 `true` 时返回。
`location_code`	integer	请求中的地理位置代码。
`language_code`	string	请求中的语言代码。
`total_count`	integer	数据库中符合请求条件的结果总数。
`items_count`	integer	`items` 数组中的结果数量。
`items`	array	及详细数据。
`depth`	integer	当前的搜索深度。
`related_keywords`	array	当前对应的搜索词列表。

`items` 与数据

`items`

字段	类型	说明
`se_type`	string	搜索引擎类型。
`keyword_data`	object	当前的详细数据。

`keyword_data`

字段	类型	说明
`se_type`	string	搜索引擎类型。
`keyword`	string	。
`location_code`	integer	地理位置代码。
`language_code`	string	语言代码。
`keyword_info`	object	搜索量、竞争度和 CPC 等数据。
`clickstream_keyword_info`	object	点击流数据。在 `include_clickstream_data` 为 `true` 时返回。
`keyword_properties`	object	附加信息。
`serp_info`	object	SERP 数据。在 `include_serp_info` 为 `true` 且数据库中存在该的 SERP 数据时返回，否则为 `null`。
`avg_backlinks_info`	object	排名结果的平均外链数据。
`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	历史平均每次点击费用。
`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	搜索量趋势变化。

`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	点击流数据集更新时间，UTC 格式。
`gender_distribution`	object	按性别划分的点击流用户分布。
`age_distribution`	object	按年龄划分的点击流用户分布。
`monthly_searches`	array	按月份统计的点击流搜索量。

`gender_distribution`

字段	类型	说明
`female`	integer	点击流数据集中的女性用户数量。
`male`	integer	点击流数据集中的男性用户数量。

`age_distribution`

字段	类型	说明
`18-24`	integer	18 至 24 岁用户数量。
`25-34`	integer	25 至 34 岁用户数量。
`35-44`	integer	35 至 44 岁用户数量。
`45-54`	integer	45 至 54 岁用户数量。
`55-64`	integer	55 至 64 岁用户数量。

点击流 `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` 表示基于文本处理；无法识别时为 `null`。
`keyword_difficulty`	integer	排名难度，取值范围为 `0` 至 `100`，用于表示自然搜索结果前 10 名的难度。
`detected_language`	string	系统检测到的语言。
`is_another_language`	boolean	检测到的语言是否不同于请求中指定的语言。

`serp_info` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型。
`check_url`	string	可直接访问的搜索结果 URL，用于核验返回结果。
`serp_item_types`	array	SERP 中出现的结果类型。
`se_results_count`	integer	该的搜索结果数量。
`last_updated_time`	string	SERP 数据最近更新时间，UTC 格式。
`previous_updated_time`	string	SERP 数据上一次更新时间，UTC 格式。

可能出现的 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	外链数据更新时间，UTC 格式。

`search_intent_info` 字段

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

归一化数据

`keyword_info_normalized_with_bing`

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

`keyword_info_normalized_with_clickstream`

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

请求示例

curl

bash

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

Python

python

import requests

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

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

post_data = [
    {
        "keyword": "phone",
        "location_name": "United States",
        "language_name": "English",
        "filters": [
            [
                "keyword_data.keyword_info.search_volume",
                ">",
                10,
            ]
        ],
        "limit": 3,
    }
]

response = requests.post(url, headers=headers, json=post_data)
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 postData = [
  {
    keyword: "phone",
    location_name: "United States",
    language_name: "English",
    filters: [
      ["keyword_data.keyword_info.search_volume", ">", 10],
    ],
    limit: 3,
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/dataforseo_labs/google/related_keywords/live",
    postData,
    {
      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.0995 sec.",
  "cost": 0.0103,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0800 sec.",
      "cost": 0.0103,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "google",
        "related_keywords",
        "live"
      ],
      "data": {
        "api": "dataforseo_labs",
        "function": "related_keywords",
        "se_type": "google",
        "keyword": "phone",
        "language_name": "English",
        "location_code": 2840,
        "limit": 3
      },
      "result": [
        {
          "se_type": "google",
          "seed_keyword": "phone",
          "location_code": 2840,
          "language_code": "en",
          "total_count": 3,
          "items_count": 3,
          "items": [
            {
              "se_type": "google",
              "keyword_data": {
                "se_type": "google",
                "keyword": "phone call",
                "location_code": 2840,
                "language_code": "en",
                "keyword_info": {
                  "se_type": "google",
                  "competition": 0.07,
                  "competition_level": "LOW",
                  "cpc": 4.23,
                  "search_volume": 27100,
                  "low_top_of_page_bid": 0.92,
                  "high_top_of_page_bid": 7.55,
                  "categories": [],
                  "monthly_searches": [
                    {
                      "year": 2024,
                      "month": 7,
                      "search_volume": 27100
                    }
                  ],
                  "search_volume_trend": {
                    "monthly": 22,
                    "quarterly": 22,
                    "yearly": 0
                  }
                },
                "clickstream_keyword_info": null,
                "keyword_properties": {
                  "se_type": "google",
                  "core_keyword": "phone calling",
                  "synonym_clustering_algorithm": "text_processing",
                  "keyword_difficulty": 57,
                  "detected_language": "en",
                  "is_another_language": false
                },
                "serp_info": null,
                "avg_backlinks_info": null,
                "search_intent_info": {
                  "se_type": "google",
                  "main_intent": "commercial",
                  "foreign_intent": null,
                  "last_updated_time": "2023-03-02 03:54:30 +00:00"
                }
              },
              "depth": 1,
              "related_keywords": []
            }
          ]
        }
      ]
    }
  ]
}

错误处理

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

20000：请求或任务执行成功
非 20000：请求或任务执行失败，应结合对应的 status_message 进行排查

建议客户端同时处理 HTTP 错误、网络时、空结果、字段为 null 以及任务级错误等。

实用场景

扩展种子：从核心词递归获取搜索词，构建规划和覆盖单。
筛选高潜：结合搜索量、竞争度和 CPC 过滤结果，优安排更商业价值的。
分析趋势：使用 monthly_searches 和 search_volume_trend 识别季节性需求，为发布时间和投放预算提供依据。
规划集群：利用 depth 和 related_keywords 建立主题词之间的，设计支柱页与集群页结构。
评估搜索意图与竞争环境：结合 search_intent_info、keyword_difficulty 和 avg_backlinks_info 判断的排名难度及适合的页面类型。

Google 实时查询 ​

计费说明 ​

请求参数 ​

基础参数 ​

地理位置与语言 ​

depth 深度说明 ​

filters ​

order_by ​

分页与任务标识 ​

响应结构 ​

顶层字段 ​

任务字段 ​

结果字段 ​

items 与数据 ​

items ​

keyword_data ​

keyword_info 字段 ​

monthly_searches ​

search_volume_trend ​

clickstream_keyword_info 字段 ​

gender_distribution ​

age_distribution ​

点击流 monthly_searches ​

keyword_properties 字段 ​

serp_info 字段 ​

avg_backlinks_info 字段 ​

search_intent_info 字段 ​

归一化数据 ​

keyword_info_normalized_with_bing ​

keyword_info_normalized_with_clickstream ​

请求示例 ​

Google 实时查询

计费说明

请求参数

基础参数

地理位置与语言

`depth` 深度说明

`filters`

`order_by`

分页与任务标识

响应结构

顶层字段

任务字段

结果字段

`items` 与数据

`items`

`keyword_data`

`keyword_info` 字段

`monthly_searches`

`search_volume_trend`

`clickstream_keyword_info` 字段

`gender_distribution`

`age_distribution`

点击流 `monthly_searches`

`keyword_properties` 字段

`serp_info` 字段

`avg_backlinks_info` 字段

`search_intent_info` 字段

归一化数据

`keyword_info_normalized_with_bing`

`keyword_info_normalized_with_clickstream`

请求示例