Google 站点拓展（实时）

POST /v3/dataforseo_labs/google/keywords_for_site/live

接口说明

POST /v3/dataforseo_labs/google/keywords_for_site/live

本接口根据目标域名所属的主题类别，返回及 SEO 数据分类、最近一个月搜索量、每次点击费用（CPC）、竞争度、过去 12 个月搜索量趋势等。

数据来源于本平台数据库，并结合 Google Ads 数据和 SERP 数据进行补。接口采用基于性的搜索算法，优返回与目标网站主题类别相近的。

例如，目标域名为 letslevitate.com 时，可能返回以下：

xvt blades
scar blades falcon
palatine blades
blades macomb il

数据每周更新。最新更新时间可通过 /v3/dataforseo_labs/status 查询。

请求限制与计费

所有 POST 请求体使用 UTF-8 编码的 JSON。
请求体是 JSON 数组，实时接口每次调用只能提交一个任务。平台限流以认证说明中的 30/60/120 次/分钟规则为准。
同时处理的请求数量最多为 30 个。
可通过 limit、offset、offset_token、filters 和 order_by 控制结果数量、分页、筛选和排序。
本接口按请求计费。原始文档未提供固定单价，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
启用 include_clickstream_data 后，该请求按基础价格的 2 倍计费。

请求参数

参数	类型	填	说明
`target`	string	是	目标网站域名，不应 `https://`。例如：`apple.com`
`location_name`	string	条件填	地理位置完整名称。未指定 `location_code` 时填，例如：`United States`
`location_code`	integer	条件填	地理位置唯一标识。未指定 `location_name` 时填，例如：`2840`
`language_name`	string	否	语言完整名称。使用此参数时无需指定 `language_code`，例如：`English`
`language_code`	string	否	语言代码。使用此参数时无需指定 `language_name`，例如：`en`
`include_serp_info`	boolean	否	是否返回每个的 SERP 数据结果数量、检查 URL 和 SERP 特征。默认值为 `false`
`include_subdomains`	boolean	否	是否将目标域名的子域名纳搜索。设置为 `false` 时忽略子域名。默认值为 `true`
`include_clickstream_data`	boolean	否	是否返回基于点击流的指标。设置为 `true` 时，将返回 `clickstream_keyword_info`、`keyword_info_normalized_with_clickstream` 和 `keyword_info_normalized_with_bing`。默认值为 `false`
`limit`	integer	否	`items` 数组最多返回的数量。默认值为 `100`，最大值为 `1000`
`offset`	integer	否	结果偏移量。例如设置为 `10` 时，跳过前 10 条结果。默认值为 `0`。建议在结果量不 10,000 条时使用
`offset_token`	string	否	用于获取后续结果的分页令牌。该值由上一次响应返回。指定后，除 `limit` 外的请求参数将不再生效
`filters`	array	否	结果筛选条件。最多支持 8 个筛选条件，条件之间使用 `and` 或 `or` 连接。不支持按 `relevance` 筛选
`order_by`	array	否	结果排序规则。最多支持 3 条规则，可使用 `asc` 或 `desc` 指定升序或降序
`tag`	string	否	自定义任务标识，最多 255 个字符。该值会原样返回在响应的 `data` 对象中

地理位置与语言

location_name 与 location_code须二选一；language_name 与 language_code 也二选一（两均省略时使用指定地区记录最多的语言）。

可通过以下接口获取可用的地区和语言：

GET /v3/dataforseo_labs/locations_and_languages

如果未指定语言，请参考该接口返回的 available_languages.keywords 字段，确认对应地区的默认语言。

筛选条件

支持以下操作符：

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

like、not_like、ilike 和 not_ilike 支持使用 % 匹任意数量的字符。

筛选条件示例：

json

[
  "keyword_properties.keyword_difficulty",
  ">",
  0
]

多个条件示例：

json

[
  [
    "keyword_info.search_volume",
    ">",
    100
  ],
  "and",
  [
    "keyword_properties.keyword_difficulty",
    "<=",
    50
  ]
]

排序规则

默认按 relevance 排序，以优返回与目标域名最的。

relevance 是本平台使用的性标识，不会出现在结果字段中，也不能用于筛选。

排序示例：

json

[
  "keyword_info.search_volume,desc",
  "keyword_properties.keyword_difficulty,asc"
]

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/dataforseo_labs/google/keywords_for_site/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "target": "apple.com",
      "location_code": 2840,
      "language_code": "en",
      "include_serp_info": true,
      "include_subdomains": true,
      "limit": 3
    }
  ]'

Python

python

import requests

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

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

payload = [
    {
        "target": "apple.com",
        "location_name": "United States",
        "language_name": "English",
        "include_serp_info": True,
        "include_subdomains": True,
        "filters": [
            "keyword_properties.keyword_difficulty",
            ">",
            0
        ],
        "limit": 3
    }
]

response = requests.post(url, headers=headers, json=payload, timeout=60)
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 = [
  {
    target: "apple.com",
    location_code: 2840,
    language_code: "en",
    include_serp_info: true,
    include_subdomains: true,
    limit: 3
  }
];

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

顶层字段

字段	类型	说明
`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`	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	本次 POST 请求中提交的任务参数
`result`	array	任务结果数组

`result` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型，通常为 `google`
`target`	string	请求中的目标域名
`location_code`	integer	请求中的地区代码
`language_code`	string	请求中的语言代码
`total_count`	integer	数据库中与请求的结果总数
`items_count`	integer	本次 `items` 数组返回的结果数量
`offset`	integer	当前结果偏移量
`offset_token`	string	后续分页令牌
`items`	array	及数据

如果需要获取 10,000 条结果，应使用响应中的 offset_token 发起后续请求。每个后续任务返回的令牌都是唯一的。

`items` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型
`keyword`	string	返回的
`location_code`	integer	地区代码
`language_code`	string	语言代码
`keyword_info`	object	搜索和竞价数据
`keyword_properties`	object	附加信息
`serp_info`	object/null	SERP 数据。未启用 `include_serp_info` 或无对应数据时为 `null`
`avg_backlinks_info`	object/null	排名前 10 的自然搜索页面的平均外链数据
`search_intent_info`	object/null	搜索意图数据
`clickstream_keyword_info`	object/null	点击流数据在启用 `include_clickstream_data` 时返回
`keyword_info_normalized_with_bing`	object/null	使用 Bing 搜索量归一化后的数据
`keyword_info_normalized_with_clickstream`	object/null	使用点击流数据归一化后的数据

`keyword_info` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型
`last_updated_time`	string	数据更新时间，UTC 格式：`yyyy-mm-dd hh:mm:ss +00:00`
`competition`	float/null	竞争度，取值范围为 `0-1`，数值越高表示竞争越激烈
`competition_level`	string/null	付费 SERP 竞争等级，可选值：`LOW`、`MEDIUM`、`HIGH`
`cpc`	float/null	历史平均每次点击费用
`search_volume`	integer	Google 月均搜索量估值
`low_top_of_page_bid`	float/null	广告展示在首页顶部所需的较低竞价估值
`high_top_of_page_bid`	float/null	广告展示在首页顶部所需的较高竞价估值
`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/null	难度，取值范围为 `0-100`，用于衡量自然搜索前 10 名的难度
`detected_language`	string	系统识别出的语言
`is_another_language`	boolean	识别语言是否与请求语言不同
`words_count`	integer	的单词数量

`serp_info` 字段

当 include_serp_info 为 true 且数据库中存在对应 SERP 数据时返回。

字段	类型	说明
`se_type`	string	搜索引擎类型
`check_url`	string	可直接访问的搜索结果页 URL，可用于核验结果
`serp_item_types`	array	SERP 中出现的结果类型
`se_results_count`	string/integer	该对应的搜索结果数量
`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	主要搜索意图
`foreign_intent`	array/null	搜索意图
`last_updated_time`	string	搜索意图数据更新时间

搜索意图可能为：

informational：信息型
navigational：导航型
commercial：商业调研型
transactional：交易型

点击流字段

只有在请求中将 include_clickstream_data 设置为 true 时，以下字段才会返回。

`clickstream_keyword_info`

字段	类型	说明
`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

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

点击流 `monthly_searches`素

字段	类型	说明
`year`	integer	年份
`month`	integer	月份
`search_volume`	integer	指定月份的点击流搜索量

归一化数据

`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.20241227",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "4.5705 sec.",
  "cost": 0.0103,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "4.1200 sec.",
      "cost": 0.0103,
      "result_count": 1,
      "data": {
        "api": "dataforseo_labs",
        "function": "keywords_for_site",
        "se_type": "google",
        "target": "apple.com",
        "language_code": "en",
        "location_code": 2840,
        "include_serp_info": true,
        "include_subdomains": true,
        "limit": 3
      },
      "result": [
        {
          "se_type": "google",
          "target": "apple.com",
          "location_code": 2840,
          "language_code": "en",
          "total_count": 125000,
          "items_count": 1,
          "offset": 0,
          "offset_token": "eyJvZmZzZXQiOjF9",
          "items": [
            {
              "se_type": "google",
              "keyword": "apple ipad pro drawing app",
              "location_code": 2840,
              "language_code": "en",
              "keyword_info": {
                "se_type": "google",
                "last_updated_time": "2025-02-10 23:44:28 +00:00",
                "competition": null,
                "competition_level": "LOW",
                "cpc": null,
                "search_volume": 10,
                "low_top_of_page_bid": null,
                "high_top_of_page_bid": null,
                "categories": [],
                "monthly_searches": [
                  {
                    "year": 2025,
                    "month": 1,
                    "search_volume": 10
                  }
                ],
                "search_volume_trend": {
                  "monthly": 0,
                  "quarterly": 0,
                  "yearly": 0
                }
              },
              "keyword_info_normalized_with_bing": null,
              "keyword_info_normalized_with_clickstream": null,
              "clickstream_keyword_info": null,
              "keyword_properties": {
                "se_type": "google",
                "core_keyword": null,
                "synonym_clustering_algorithm": "text_processing",
                "keyword_difficulty": null,
                "detected_language": "en",
                "is_another_language": false,
                "words_count": 5
              },
              "serp_info": null,
              "avg_backlinks_info": null,
              "search_intent_info": {
                "se_type": "google",
                "main_intent": "transactional",
                "foreign_intent": null,
                "last_updated_time": "2023-03-02 18:51:08 +00:00"
              }
            }
          ]
        }
      ]
    }
  ]
}

状态码与错误处理

请根据响应中的 status_code 和 status_message 判断请求及任务是否成功：

顶层 status_code = 20000：请求成功。
tasks_error > 0：至少有一个任务返回错误。
任务级别的 status_code 需要单独检查。
建议在客户端实现时、网络异常、参数错误、任务错误和空结果处理机制。

完整错误码请参考本平台的错误码文档。

实用场景

拓展目标域名的，发现网站当前覆盖范围之外的搜索需求，为规划和库建设提供依据。
筛选高搜索量、低难度的词组，优制定更容易获得自然流量的 SEO策略。
分析的搜索意图与 SERP 特征，匹产品页、教程页、对比页或问答页等适合的页面类型。
结合月度搜索量趋势制定日历，识别季节性需求和搜索量增长机会，优化发布时机。
对比竞争度、CPC 与排名页面外链数据，评估自然搜索和付费搜索的价值， SEO 项目优级排序。

Google 站点拓展（实时） ​

接口说明 ​

请求限制与计费 ​

请求参数 ​

地理位置与语言 ​

筛选条件 ​

排序规则 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

任务字段 ​

result 字段 ​

items 字段 ​

keyword_info 字段 ​

search_volume_trend ​

monthly_searches 数组 ​

keyword_properties 字段 ​

serp_info 字段 ​

avg_backlinks_info 字段 ​

search_intent_info 字段 ​

点击流字段 ​

clickstream_keyword_info ​

点击流 monthly_searches素 ​

归一化数据 ​

keyword_info_normalized_with_bing ​

keyword_info_normalized_with_clickstream ​

响应示例 ​

状态码与错误处理 ​

Google 站点拓展（实时）

接口说明

请求限制与计费

请求参数

地理位置与语言

筛选条件

排序规则

请求示例

cURL

Python

TypeScript

响应结构

顶层字段

任务字段

`result` 字段

`items` 字段

`keyword_info` 字段

`search_volume_trend`

`monthly_searches` 数组

`keyword_properties` 字段

`serp_info` 字段

`avg_backlinks_info` 字段

`search_intent_info` 字段

点击流字段

`clickstream_keyword_info`

点击流 `monthly_searches`素

归一化数据

`keyword_info_normalized_with_bing`

`keyword_info_normalized_with_clickstream`

响应示例

状态码与错误处理