站点实时查询

POST /v3/dataforseo_labs/google/keywords_for_site/live

接口说明

/v3/dataforseo_labs/google/keywords_for_site/live 用于根据目标域名，返回与该网站主题高度的列表。

每个通常会附带以下数据：

• 所属分类
• 最近一个月搜索量
• 平均点击成本（CPC）
• 竞争度
• 过去 12 个月搜索趋势
• 可选的 SERP 信息
• 可选的点击流标准化数据

该接口适合做站点语义扩展、竞品词挖掘、规划和投放分析。

数据来源：

• 平台数据库（按域名分段）
• Google Ads 数据
• 并由 SERP 数据库补增强

匹逻辑：

• 基于性，识别与目标域名所属主题/分类相近的

示例：

若目标域名为 letslevitate.com，可能返回类似：

• xvt blades
• scar blades falcon
• palatine blades
• blades macomb il

请求方式

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

计费说明

该接口按请求计费。

参考价约 ¥0.1648 / 次

如果开启 include_clickstream_data=true，请求费用约翻倍。

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

并发与频率限制

• 每分钟最多可发送 2000 次 API 调用
• 同时进行中的请求数上限为 30

请求体格式

所有 POST 数据需使用 JSON（UTF-8 编码），并以数组形式提交：

[
 {
 "target": "apple.com",
 "location_code": 2840,
 "language_code": "en",
 "limit": 3
 }
]

请求参数

字段名	类型	说明
target	string	填。目标域名，不 https://，例如 apple.com
location_name	string	地区名。未传 location_code 时填。location_name 与 location_code 二选一。可通过 /v3/dataforseo_labs/locations_and_languages 获取可用地区，例如 United Kingdom
location_code	integer	地区唯一标识。未传 location_name 时填。location_name 与 location_code 二选一。可通过 /v3/dataforseo_labs/locations_and_languages 获取，例如 2840
language_name	string	语言名，可选。传此字段时可不传 language_code。可通过 /v3/dataforseo_labs/locations_and_languages 获取，例如 English
language_code	string	语言代码，可选。传此字段时可不传 language_name。可通过 /v3/dataforseo_labs/locations_and_languages 获取，例如 en
include_serp_info	boolean	是否为每个返回 SERP 数据。为 true 时，响应中会 serp_info，默认 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	返回数量上限，默认 100，最大 1000
offset	integer	结果偏移量，默认 0。如传 10，则跳过前 10 个结果。建议在获取不 10,000 条结果时使用
offset_token	string	用于分页拉取后续结果的令牌。适合获取 10,000 条结果，时。若请求中传该字段，则除 limit 外余参数将被忽略
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 支持 % 通符。注意：不能按 relevance 过滤
order_by	array	排序规则，可选。支持与 filters 相同的字段路径。排序方式：asc 升序、desc 降序。单次请求最多设置 3 条排序规则。默认按性 relevance 排序。注意：relevance 用于排序，不能用于过滤，且不会出现在结果字段中
tag	string	用户自定义任务标识，可选，最大长度 255。响应中可在 data 对象里取回该值，便于请求与结果对账

语言默认规则

如果同时省略 language_name 和 language_code，系统会默认使用该地区下记录最多的语言。可通过 /v3/dataforseo_labs/locations_and_languages 返回结果中的 available_languages.keywords 判断默认语言。

filters 用法说明

filters 为数组格式，可按字段路径构造条件。

示例：筛选难度大于 0 的结果

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

多个条件组合时，应使用 and 或 or 连接。

更多字段路径可结合下文响应字段说明使用。

order_by 用法说明

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

也可以按字段排序，例如：

[
 "keyword_info.search_volume,desc"
]

或多字段排序：

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

响应结构

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

顶层字段

字段名	类型	说明
version	string	当前 API 版本
status_code	integer	通用状态码
status_message	string	通用状态信息
time	string	执行耗时，单位秒
cost	float	总扣费，单位 USD
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	返回错误的任务数量
tasks	array	任务列表

task 字段

字段名	类型	说明
id	string	任务唯一标识，UUID 格式
status_code	integer	任务状态码
status_message	string	任务状态信息
time	string	任务执行耗时
cost	float	当前任务扣费，单位 USD
result_count	integer	result 数组数量
path	array	URL 路径
data	object	与请求体中提交的参数基本一致
result	array	获取结果

result 字段

字段名	类型	说明
se_type	string	搜索引擎类型
target	string	请求中的目标域名
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 指标

字段名	类型	说明
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	历史平均点击成本，单位 USD
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	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 岁用户数

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	若为 true，表示语言与请求语言不一致
words_count	integer	词数

serp_info SERP 数据

当 include_serp_info=true 且数据库中存在 SERP 数据时返回，否则为 null。

字段名	类型	说明
se_type	string	搜索引擎类型
check_url	string	搜索结果检查链接
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	平均 Rank 值
main_domain_rank	float	平均主域 Rank 值
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

返回经 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	月度搜索量

认证方式

请在请求头中使用 Bearer Token：

Authorization: Bearer smt_live_YOUR_KEY

请求示例

cURL

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

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/google/keywords_for_site/live"
payload = [
 {
 "target": "apple.com",
 "location_name": "United States",
 "language_name": "English",
 "include_serp_info": True,
 "include_subdomains": True,
 "limit": 3
 }
]
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

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

TypeScript

import axios from "axios";

const postArray = [
 {
 target: "apple.com",
 location_code: 2840,
 language_code: "en",
 include_serp_info: true,
 include_subdomains: true,
 limit: 3
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/dataforseo_labs/google/keywords_for_site/live",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: postArray
})
 .then((response) => {
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应示例

{
 "version": "0.1.20241227",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "4.5705 sec.",
 "cost": 0.0103,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "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": [
 {
 "items": [
 {
 "se_type": "google",
 "keyword": "video editing app for ipad pro",
 "location_code": 2840,
 "language_code": "en",
 "keyword_info": {
 "se_type": "google",
 "last_updated_time": "2025-02-07 03:53:40 +00:00",
 "competition": 0.12,
 "competition_level": "LOW",
 "cpc": 0.45,
 "search_volume": 320,
 "monthly_searches": [],
 "search_volume_trend": {
 "monthly": 0,
 "quarterly": 50,
 "yearly": -57
 }
 },
 "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": 60,
 "detected_language": "en",
 "is_another_language": false,
 "words_count": 6
 },
 "serp_info": {
 "se_type": "google",
 "check_url": "https://www.google.com/search?q=video%20editing%20app%20for%20ipad%20pro&num=100&hl=en&gl=US&gws_rd=cr&ie=UTF-8&oe=UTF-8&glp=1&uule=w+CAIQIFISCQs2MuSEtepUEUK33kOSuTsc",
 "serp_item_types": ["organic", "paid", "featured_snippet"],
 "se_results_count": 165000000,
 "last_updated_time": "2025-01-15 02:36:57 +00:00",
 "previous_updated_time": "2024-11-15 17:47:55 +00:00"
 },
 "avg_backlinks_info": {
 "se_type": "google",
 "backlinks": 4616.3,
 "dofollow": 2067.3,
 "referring_pages": 2712.8,
 "referring_domains": 669.1,
 "referring_main_domains": 591.7,
 "rank": 250.1,
 "main_domain_rank": 812.6,
 "last_updated_time": "2025-01-15 02:36:57 +00:00"
 },
 "search_intent_info": {
 "se_type": "google",
 "main_intent": "transactional",
 "foreign_intent": null,
 "last_updated_time": "2023-03-02 13:20:01 +00:00"
 }
 }
 ]
 }
 ]
 }
 ]
}

错误处理

请基于 status_code 和 status_message 实现错误处理机制顶层响应和任务级别响应。

常见判断方式：

• 顶层 status_code != 20000：请求整体失败
• tasks_error > 0：部分任务失败
• 单个 tasks[i].status_code != 20000：该任务执行失败

完整错误码请参考 /v3/appendix/errors。

使用建议

1. 优使用默认性排序 若目标是挖掘与站点最的词，建议不要覆盖默认 relevance 排序。

2. 大批量翻页优使用 offset_token 当需要拉取 10,000 条结果时，建议不要继续使用 offset，而应改用 offset_token。

3. 按需开启 SERP 与点击流数据include_serp_info 会增加响应体大小；include_clickstream_data 会增加费用。建议在确有需求时开启。

4. 跨地区/语言批量测试 同一站点在不同国家和语言环境下可能返回不同的集合，适合做 SEO 分析。

实用场景

• 挖掘站点主题：围绕目标域名自动扩展高度的搜索词，快速建立站点语义词库。
• 分析竞品覆盖方向：竞品域名，识别可能覆盖的核心主题，差距分析。
• 筛选低难度机会词：结合 keyword_difficulty、search_volume 和 competition_level 找出更容易获取自然流量的词。
• 规划本地化 SEO 布局：按不同 location_code 与语言维度查询站点词，支持区域站点和多语言站点策略制定。
• 评估 SERP 成本：结合 serp_info、avg_backlinks_info、search_intent_info 判断竞争环境，优级和投放决策。