Google 创意（实时）

POST /v3/dataforseo_labs/google/keyword_ideas/live

接口说明

该接口用于基于一组种子，返回与所属产品/服务类别的创意。系统会对提交的种子词进行类别识别，并从同类中生成的搜索词建议。

一次请求最多可传 200 个种子，返回结果中可：

建议本身
最近一个月搜索量
过去 12 个月搜索趋势
当前 CPC（单次点击成本）
竞争度与竞争等级
点击量与 CPC 的最小值、最大值、平均值数据
可选的 SERP 信息
可选的点击流归因数据

数据源： 本平台数据库（按产品类别分段） 搜索算法： 基于性的同类目检索

示例说明

当传种子词：

keyword research
content marketing

且不附加额外排序参数，并设置 "closely_variants": false 时，可能返回的创意：

free adword tools
find longtail keywords
how to do keywords research
seo keyword research template

请求信息

POSThttps://api.seermartech.cn/v3/dataforseo_labs/google/keyword_ideas/live

计费说明

该接口按请求计费。

原文未提供固定单价，因此无法直接换算为人民币。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

调用限制

每分钟最多：2000 次 API 调用
最大并发请求数：30

请求体格式

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

json

[
 {
 "keywords": ["phone", "watch"],
 "location_code": 2840,
 "language_code": "en",
 "include_serp_info": true,
 "limit": 3
 }
]

请求参数

以下为任务设置字段说明。

字段名	类型	说明
`keywords`	array	填。种子数组，UTF-8 编码。最多可提交 200 个。系统会将统一转换为小写。
`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`。示例：`en`。如省略，将默认使用该地区中记录最多的语言。
`closely_variants`	boolean	搜索模式，可选。`true` 表示基于短语匹；`false` 表示基于广泛匹。默认：`false`
`ignore_synonyms`	boolean	是否忽略高度相似，可选。`true` 时返回核心，排除高相似词。默认：`false`
`include_serp_info`	boolean	是否为每个返回 SERP 数据，可选。`true` 时响应中会 `serp_info` 数组。默认：`false`
`include_clickstream_data`	boolean	是否返回点击流指标，可选。`true` 时响应中会 `clickstream_keyword_info`、`keyword_info_normalized_with_clickstream`、`keyword_info_normalized_with_bing`。默认：`false`。开启后请求价格翻倍，扣费以响应头 `X-SeerMarTech-Charge-CNY` 为准。
`limit`	integer	返回数量上限，可选。默认：`700`，最大：`1000`
`offset`	integer	结果偏移量，可选。默认：`0`。例如设置为 `10`，则跳过前 10 条结果并返回后续。建议在获取不 10,000 条结果时使用。
`offset_token`	string	后续翻页令牌，可选。用于获取 10,000 条结果时的后续数据，单次请求时。该值来自上一响应中的同名字段。若请求中传 `offset_token`，除 `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`（降序）。默认按 `relevance` 排序，以返回最的创意。`relevance` 用于排序，不能作为过滤字段，也不会出现在 `result` 中。一次请求最多设置 3 条排序规则。
`tag`	string	自定义任务标识，可选。最大长度 255。可用于将响应结果与业务任务，返回时会出现在响应 `data` 对象中。

过滤与排序补说明

`filters` 支持说明

最多 8 个条件
条件之间使用逻辑连接符：and / or
支持模糊匹、正则、比较、集合判断等常用方式
不能使用 relevance 作为过滤字段

示例：

json

[
 ["keyword_info.search_volume", ">", 1000],
 "and",
 ["keyword_properties.keyword_difficulty", "<=", 30]
]

`order_by` 支持说明

默认 relevance 降序返回，即优给出与种子词最的建议。如需自定义排序，可传排序字段与方向。

示例：

json

[
 "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	任务结果数组

`tasks[]` 字段

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

`result[]` 字段

字段名	类型	说明
`se_type`	string	搜索引擎类型
`seed_keywords`	array	请求中提交的种子。返回时会对编码进行解码，`+` 会被解析为空格。
`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	竞争度，基于 Google Ads 数据，取值 `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`；无结果时为 `null`
`keyword_difficulty`	integer	难度，`0-100`，表示自然搜索前 10 名的难度
`detected_language`	string	系统识别出的语言
`is_another_language`	boolean	识别语言是否与请求语言不同
`words_count`	integer	词数

`serp_info`

SERP 数据。若未设置 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 数据更新时间
`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	是否已归一化；`true` 表示使用 Bing 数据归一化
`monthly_searches`	array	月度搜索量数据

`keyword_info_normalized_with_clickstream`

基于点击流数据归一化后的搜索量数据。

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

请求示例

cURL

bash

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

Python

python

import requests

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

payload = [
 {
 "keywords": ["phone", "watch"],
 "location_name": "United States",
 "language_name": "English",
 "filters": [
 ["keyword_info.search_volume", ">", 10]
 ],
 "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

typescript

import axios from "axios";

const postArray = [
 {
 keywords: ["phone", "watch"],
 location_code: 2840,
 language_name: "English",
 filters: [
 ["keyword_info.search_volume", ">", 10]
 ],
 limit: 3
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/dataforseo_labs/google/keyword_ideas/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.20240801",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.7097 sec.",
 "cost": 0.0103,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "dataforseo_labs",
 "function": "keyword_ideas",
 "se_type": "google",
 "keywords": ["phone", "watch"],
 "location_code": 2840,
 "language_code": "en",
 "include_serp_info": true,
 "limit": 3
 },
 "result": [
 {
 "location_code": 2840,
 "language_code": "en",
 "total_count": 533763,
 "items_count": 3,
 "offset": 0,
 "offset_token": "eyJDdXJyZW50T2Zmc2V0IjozLCJSZXF1ZXN0RGF0YSI6...",
 "items": [
 {
 "se_type": "google",
 "keyword": "phone",
 "location_code": 2840,
 "language_code": "en",
 "keyword_info": {
 "se_type": "google",
 "last_updated_time": "2024-08-11 18:11:54 +00:00",
 "competition": 1,
 "competition_level": "HIGH",
 "cpc": 1.05,
 "search_volume": 22200,
 "low_top_of_page_bid": 0.31,
 "high_top_of_page_bid": 1.15,
 "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": 83,
 "detected_language": "en",
 "is_another_language": false,
 "words_count": 1
 },
 "serp_info": {
 "se_type": "google",
 "check_url": "https://www.google.com/search?q=phone&num=100&hl=en&gl=US&gws_rd=cr&ie=UTF-8&oe=UTF-8&glp=1&uule=...",
 "serp_item_types": ["organic", "paid"],
 "se_results_count": 19880000000,
 "last_updated_time": "2024-07-14 21:43:34 +00:00",
 "previous_updated_time": "2024-05-18 19:29:28 +00:00"
 }
 }
 ]
 }
 ]
 }
 ]
}

状态码与异常处理

顶层 status_code 表示整次请求的处理结果
tasks[].status_code 表示单个任务的处理结果
建议同时检查：
HTTP 状态码
顶层 status_code
任务级 tasks[].status_code

如需完整错误码说明，请参考 /v3/appendix/errors。

使用建议

默认按 relevance 排序 如果目标是拿到最的扩展，建议不主动覆盖默认排序。
大结果集优使用 offset_token 当结果数可能 10,000 时，使用 offset 容易带来性能和时问题，建议改用 offset_token 翻页。
按需开启 SERP 与点击流数据

开启 include_serp_info 可增强 SERP 侧分析能力
开启 include_clickstream_data 可获得更丰富的人群与归一化搜索量指标，但会提高扣费

过滤再分页 对于海量结果，建议通过 filters 控制范围，再合 limit 和 offset_token 拉取，无效数据传输。

实用场景

扩展种子词库：基于已有核心词批量挖掘同类，快速补 SEO规划和广告投放词。
筛选低难度机会词：结合 keyword_properties.keyword_difficulty 与 keyword_info.search_volume，找出“有量但竞争相对低”的长尾词。
评估商业投放价值：通过 cpc、competition、competition_level 判断商业价值， SEM 出价与预算分。
识别搜索趋势变化：利用 monthly_searches 与 search_volume_trend 跟踪热度变化，及时调整专题和季节性运营策略。
分析 SERP 版位结构：开启 include_serp_info 后识别对应的 SERP 特征类型，判断该词更适合做自然排名、地图优化还是精选摘要争夺。

Google 创意（实时） ​

接口说明 ​

示例说明 ​

请求信息 ​

计费说明 ​

调用限制 ​

请求体格式 ​

请求参数 ​

过滤与排序补说明 ​

filters 支持说明 ​

order_by 支持说明 ​

响应结构 ​

顶层字段 ​

tasks[] 字段 ​

result[] 字段 ​

items[] 字段说明 ​

基础字段 ​

keyword_info ​

monthly_searches[] ​

search_volume_trend ​

clickstream_keyword_info ​

gender_distribution ​

age_distribution ​

keyword_properties ​

serp_info ​

avg_backlinks_info ​

search_intent_info ​

keyword_info_normalized_with_bing ​

keyword_info_normalized_with_clickstream ​

请求示例 ​

cURL ​

Python ​

Google 创意（实时）

接口说明

示例说明

请求信息

计费说明

调用限制

请求体格式

请求参数

过滤与排序补说明

`filters` 支持说明

`order_by` 支持说明

响应结构

顶层字段

`tasks[]` 字段

`result[]` 字段

`items[]` 字段说明

基础字段

`keyword_info`

`monthly_searches[]`

`search_volume_trend`

`clickstream_keyword_info`

`gender_distribution`

`age_distribution`

`keyword_properties`

`serp_info`

`avg_backlinks_info`

`search_intent_info`

`keyword_info_normalized_with_bing`

`keyword_info_normalized_with_clickstream`

请求示例

cURL

Python