概览（Google）实时接口

接口说明

该接口用于获取指定在 Google 维度下的数据。针对每个，您可以获得：

当前平均点击费用（CPC）
付费搜索竞争度及竞争等级
搜索量
搜索意图
近 12 个月月度搜索量
SERP 信息
反向链接统计信息

如需返回基于点击流的指标，可将 include_clickstream_data 设为 true，届时响应中会额外点击流搜索量及归一化搜索量数据。

返回结果会受到以下维度影响：

keywords 指定的
地区
语言

支持的地区与语言组合可通过 /v3/dataforseo_labs/locations_and_languages 查询。

数据源： 本平台数据库 数据基础： 基于 Google Ads 数据 更新频率： 指标通常每月更新一次；若平台数据源对某月搜索量进行回写或修正，本接口也会同步更新。

请求信息

HTTP 方法： POST接口地址：

https://api.seermartech.cn/v3/dataforseo_labs/google/keyword_overview/live

计费说明

本接口按请求计费。

实扣费以响应头 X-SeerMarTech-Charge-CNY 为准
开启 include_clickstream_data=true 后，请求价格会变为双倍

原文未提供固定单价，因此无法给出精确人民币参考价；请以响应中的 cost 为准。

调用限制

每分钟最多可发送 2000 次 API 调用
最多 30 个并发请求
POST 数据使用 JSON（UTF-8 编码）
请求体格式为 JSON 数组：[{ ... }]

请求参数

以下为任务对象字段说明。

字段名	类型	说明
`keywords`	array	填。数组。最多可传 `700` 个；每个最多 `80` 个字符；每个短语最多 `10` 个单词。系统会自动将转为小写。返回结果按独立数组项输出。若部分未出现在结果中，表示数据库中暂无该数据，此类不会计费。
`location_name`	string	地区名。若未传 `location_code`，则该字段填。`location_name` 与 `location_code` 二选一填。示例：`United Kingdom`
`location_code`	integer	地区编码。若未传 `location_name`，则该字段填。`location_name` 与 `location_code` 二选一填。示例：`2840`
`language_name`	string	语言名。若未传 `language_code`，则该字段填。`language_name` 与 `language_code` 二选一填。示例：`English`
`language_code`	string	语言编码。若未传 `language_name`，则该字段填。`language_name` 与 `language_code` 二选一填。示例：`en`
`include_serp_info`	boolean	是否返回每个的 SERP 数据。可选。设为 `true` 后，响应中会返回 `serp_info`，搜索结果数量、 URL、SERP 特征等。默认：`false`
`include_clickstream_data`	boolean	是否返回基于点击流的指标。可选。设为 `true` 后，响应中会返回 `clickstream_keyword_info`、`keyword_info_normalized_with_clickstream`、`keyword_info_normalized_with_bing`。默认：`false`
`tag`	string	用户自定义任务标识。可选，最大长度 `255`。便于将请求与结果进行匹；该值会原样出现在响应的 `data` 对象中。

地区与语言查询

可通过以下容路径获取支持的地区和语言列表：

/v3/dataforseo_labs/locations_and_languages

返回结构

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

顶层字段

字段名	类型	说明
`version`	string	API 当前版本
`status_code`	integer	通用状态码。完整列表参考：`/v3/appendix/errors`
`status_message`	string	通用状态信息
`time`	string	执行耗时，单位秒
`cost`	float	本次任务总费用，单位 USD
`tasks_count`	integer	`tasks` 数组中的任务数
`tasks_error`	integer	返回错误的任务数
`tasks`	array	任务数组

tasks 数组字段

字段名	类型	说明
`id`	string	任务唯一标识，UUID 格式
`status_code`	integer	任务状态码，范围通常为 `10000-60000`；完整列表参考：`/v3/appendix/errors`
`status_message`	string	任务状态信息
`time`	string	任务执行耗时
`cost`	float	任务费用，单位 USD
`result_count`	integer	`result` 数组数量
`path`	array	URL 路径
`data`	object	与请求中提交的参数一致
`result`	array	结果数组

result 数组字段

字段名	类型	说明
`se_type`	string	搜索引擎类型
`location_code`	integer	请求中的地区编码
`language_code`	string	请求中的语言编码
`items_count`	integer	`items` 数组返回的结果数
`items`	array	及数据

items 字段说明

字段名	类型	说明
`se_type`	string	搜索引擎类型
`keyword`	string	。返回时会解码 `%##`，并将 `+` 号解码为空格
`location_code`	integer	请求中的地区编码；若无数据则为 `null`
`language_code`	string	请求中的语言编码
`search_partners`	boolean	是否 Google 合作搜索网络数据。`true` 表示 Google 及合作站点；`false` 表示 Google 搜索站点
`keyword_info`	object	基础数据
`keyword_info_normalized_with_bing`	object	使用 Bing 搜索量归一化后的搜索量数据
`keyword_info_normalized_with_clickstream`	object	使用点击流数据归一化后的搜索量数据
`clickstream_keyword_info`	object	点击流数据；在 `include_clickstream_data=true` 时返回
`keyword_properties`	object	附加属性
`serp_info`	object	SERP 数据；在 `include_serp_info=true` 且数据库中存在数据时返回，否则为 `null`
`avg_backlinks_info`	object	该对应自然搜索前 10 名页面的平均反链信息
`search_intent_info`	object	搜索意图信息

keyword_info 字段说明

字段名	类型	说明
`se_type`	string	搜索引擎类型
`last_updated_time`	string	数据更新时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`
`competition`	float	竞争度，范围 `0-1`，基于 Google Ads 数据
`competition_level`	string	付费搜索竞争等级，可选值：`LOW`、`MEDIUM`、`HIGH`；未知时为 `null`
`cpc`	float	历史平均点击费用，单位 USD
`search_volume`	integer	月均搜索量
`low_top_of_page_bid`	float	首页顶部广告展示的较低出价参考值，约高于 20% 最低出价
`high_top_of_page_bid`	float	首页顶部广告展示的较高出价参考值，约高于 80% 最低出价
`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	相比上一年的搜索量变化百分比

keyword_info_normalized_with_bing 字段说明

该对象表示使用 Bing 搜索量归一化后的搜索量。

字段名	类型	说明
`last_updated_time`	string	数据集更新时间，UTC 格式
`search_volume`	integer	当前搜索量
`is_normalized`	boolean	是否已归一化；`true` 表示使用 Bing 数据归一化
`monthly_searches`	array	分年月的搜索量数组

keyword_info_normalized_with_clickstream 字段说明

该对象表示使用点击流数据归一化后的搜索量。

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

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 岁用户指标

keyword_properties 字段说明

字段名	类型	说明
`se_type`	string	搜索引擎类型
`core_keyword`	string	同义词聚类分组中的主；若无可识别同义词则为 `null`
`synonym_clustering_algorithm`	string	同义词识别算法。可选值：`keyword_metrics`（基于指标）、`text_processing`（基于文本处理）；无结果时为 `null`
`keyword_difficulty`	integer	难度，范围 `0-100`，表示自然搜索前 10 的难度
`detected_language`	string	系统识别出的语言
`is_another_language`	boolean	识别语言是否与请求中设置的语言不同

serp_info 字段说明

如未设置 include_serp_info=true，或数据库中无 SERP 数据，则该字段为 null。

字段名	类型	说明
`se_type`	string	搜索引擎类型
`check_url`	string	可直接打开的搜索结果页 URL，用于核验结果
`serp_item_types`	array	SERP 中检测到的结果类型
`se_results_count`	string	搜索结果总量
`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	平均 Rank 值
`main_domain_rank`	float	平均主域名 Rank 值
`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 格式

错误处理

顶层 status_code 表示整体请求状态
tasks[].status_code 表示单个任务状态
完整错误码与状态说明参考：/v3/appendix/errors

建议在接时同时处理以下：

HTTP 请求成功，但业务 status_code 非成功
部分无返回结果
serp_info、clickstream_keyword_info 等可选字段为空
某些因数据库缺失而被自动忽略

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/dataforseo_labs/google/keyword_overview/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "keywords": ["iphone", "buy iphone"],
 "language_name": "English",
 "location_code": 2840,
 "include_serp_info": true,
 "include_clickstream_data": true,
 "tag": "keyword-overview-demo"
 }
]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/google/keyword_overview/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

payload = [
 {
 "keywords": ["iphone", "buy iphone"],
 "location_name": "United States",
 "language_name": "English",
 "include_serp_info": True,
 "include_clickstream_data": True,
 "tag": "keyword-overview-demo"
 }
]

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

TypeScript

typescript

import axios from "axios";

// 请求体为 JSON 数组
const postArray = [
 {
 keywords: ["iphone", "buy iphone"],
 language_name: "English",
 location_code: 2840,
 include_serp_info: true,
 include_clickstream_data: true,
 tag: "keyword-overview-demo"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/dataforseo_labs/google/keyword_overview/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);
 });

响应示例

json

{
 "version": "0.1.20241227",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1845 sec.",
 "cost": 0.0201,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "dataforseo_labs",
 "function": "keyword_overview",
 "se_type": "google",
 "language_code": "en",
 "location_code": 2840,
 "include_clickstream_data": true,
 "include_serp_info": true,
 "keywords": ["iphone"]
 },
 "result": [
 {
 "items": [
 {
 "keyword_info": {
 "monthly_searches": [],
 "search_volume_trend": {
 "monthly": 0,
 "quarterly": -19,
 "yearly": 22
 }
 },
 "keyword_info_normalized_with_bing": {
 "last_updated_time": "2025-02-15 06:43:28 +00:00",
 "search_volume": 600417,
 "is_normalized": true,
 "monthly_searches": []
 },
 "keyword_info_normalized_with_clickstream": {
 "last_updated_time": "2025-02-15 06:43:28 +00:00",
 "search_volume": 1176877,
 "is_normalized": true,
 "monthly_searches": []
 },
 "clickstream_keyword_info": {
 "search_volume": 737851,
 "last_updated_time": "2025-01-04 00:08:42 +00:00",
 "gender_distribution": {
 "female": 51,
 "male": 49
 },
 "age_distribution": {
 "18-24": 22,
 "25-34": 19,
 "35-44": 25,
 "45-54": 32,
 "55-64": 2
 },
 "monthly_searches": []
 },
 "keyword_properties": {
 "se_type": "google",
 "core_keyword": null,
 "synonym_clustering_algorithm": "text_processing",
 "keyword_difficulty": 89,
 "detected_language": "en",
 "is_another_language": false
 },
 "serp_info": {
 "se_type": "google",
 "check_url": "https://www.google.com/search?q=iphone&num=100&hl=en&gl=US&gws_rd=cr&ie=UTF-8&oe=UTF-8&glp=1&uule=w+CAIQIFISCQs2MuSEtepUEUK33kOSuTsc",
 "serp_item_types": [],
 "se_results_count": 13380000000,
 "last_updated_time": "2025-02-26 21:10:59 +00:00",
 "previous_updated_time": "2025-01-16 07:38:29 +00:00"
 },
 "avg_backlinks_info": {
 "se_type": "google",
 "backlinks": 1333333.7,
 "dofollow": 1048624.3,
 "referring_pages": 1077104.1,
 "referring_domains": 9109.9,
 "referring_main_domains": 8417.2,
 "rank": 415.6,
 "main_domain_rank": 818.7,
 "last_updated_time": "2025-02-26 19:11:00 +00:00"
 },
 "search_intent_info": {
 "se_type": "google",
 "main_intent": "informational",
 "foreign_intent": null,
 "last_updated_time": "2023-02-28 15:25:15 +00:00"
 }
 }
 ]
 }
 ]
 }
 ]
}

使用建议

批量查询时控制规模：单次最多支持 700 个，建议按业务批次拆分，降低时和错误处理复杂度。
按需开启附加数据：只有在确实需要 SERP 或点击流指标时再开启 include_serp_info / include_clickstream_data，以控制响应体大小和成本。
重点缺失：若提交的未出现在结果中，通常表示数据库暂无收录，不会产生费用。
结合搜索意图与难度筛词：search_intent_info 与 keyword_properties.keyword_difficulty 适合用于规划和投放优级排序。

实用场景

筛选投放：批量获取 CPC、竞争度和搜索量，快速找出高流量且竞争适中的付费投放词。
制定选题：结合搜索意图、月度搜索趋势和难度，确定更值得布局的专题。
评估 SERP 竞争环境：读取 serp_info 与 avg_backlinks_info，判断某首页结果类型、反链强度和自然排名门槛。
识别季节性需求：通过 monthly_searches 与 search_volume_trend 观察波动规律，电商大促、节日营销和行业周期选题。
分析用户画像倾向：开启点击流数据后，利用年龄与性别分布判断受众结构，优化落地页和广告创意。

概览（Google）实时接口 ​

接口说明 ​

请求信息 ​

计费说明 ​

调用限制 ​

请求参数 ​

地区与语言查询 ​

返回结构 ​

顶层字段 ​

tasks 数组字段 ​

result 数组字段 ​

items 字段说明 ​

keyword_info 字段说明 ​

monthly_searches 子字段 ​

search_volume_trend 子字段 ​

keyword_info_normalized_with_bing 字段说明 ​

keyword_info_normalized_with_clickstream 字段说明 ​

clickstream_keyword_info 字段说明 ​

gender_distribution 子字段 ​

age_distribution 子字段 ​

keyword_properties 字段说明 ​

serp_info 字段说明 ​

serp_item_types 可能值 ​

avg_backlinks_info 字段说明 ​

search_intent_info 字段说明 ​

错误处理 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

使用建议 ​