（旧版）实时查询

POST /v3/dataforseo_labs/related_keywords/live

接口说明

注意：本平台 Labs API 的请求与响应结构已在 2022-03-19 更新，但本页所述旧版接口仍保持容并继续支持。若需新版结构，请参考对应新版文档。

该接口用于获取搜索结果页中“搜索（searches related to）”模块出现的。

通过设置 depth 搜索深度，最多可获取 4680 个建议。每个可返回以下数据：

产品/服务分类
最近一个月搜索量
过去 12 个月搜索趋势
当前 CPC（单次点击费用）
竞争度
每日展示、点击、CPC 的最小值、最大值和平均值
可选 SERP 信息

数据来源： 本平台 SERP 数据库 搜索算法： 针对指定种子词，基于 SERP 中“搜索”执行深度优搜索

示例说明

假设：

depth = 1
种子词：keyword research

可能返回的：

free keyword research
keyword research tools
best free keyword research tool
keyword research tips
seo keyword research tool
keyword research step by step
how to do keyword research 2019
keyword research google ads

请求方式

POST https://api.seermartech.cn/v3/dataforseo_labs/related_keywords/live

计费说明

该接口按请求计费。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求限制

请求体为 UTF-8 编码的 JSON
POST 请求体格式为 JSON 数组：[{ ... }]
每分钟最多可发送 2000 次 API 调用
支持通过 limit 控制返回数量
支持通过 filters 过滤结果
支持通过 order_by 对结果排序

请求参数

字段名	类型	说明
`keyword`	string	填。种子。需使用 UTF-8 编码；最少 3 个字符；系统会自动转为小写。
`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` 时填。`language_name` 与 `language_code` 二选一。可通过 `/v3/dataforseo_labs/locations_and_languages` 获取支持的语言列表。示例：`English`
`language_code`	string	语言代码。未填写 `language_name` 时填。`language_name` 与 `language_code` 二选一。可通过 `/v3/dataforseo_labs/locations_and_languages` 获取支持的语言列表。示例：`en`
`depth`	integer	可选。搜索深度，默认 `1`。可设置 `0` 到 `4`。不同深度对应的最大数量估算如下：`0`=返回 `keyword` 本身；`1`=8 个；`2`=72 个；`3`=584 个；`4`=4680 个。
`include_seed_keyword`	boolean	可选。是否在响应中的 `seed_keyword_data` 返回种子词自身数据。默认 `false`。
`include_serp_info`	boolean	可选。是否为每个返回 `serp_info`。若为 `true`，将返回搜索结果数量、 URL、SERP 特征等信息。默认 `false`。
`replace_with_core_keyword`	boolean	可选。是否返回核心词数据。若为 `true`，则返回指定 `keyword` 所属组的核心词对应的 `serp_info` 和 `related_keywords`；若为 `false`，则返回指定词本身的数据（若可用）。默认 `false`。
`filters`	array	可选。结果过滤条件数组，最多支持 8 个过滤条件。多个条件之间需使用逻辑运算符 `and` 或 `or` 连接。支持操作符：`<`, `<=`, `>`, `>=`, `=`, `<>`, `in`, `not_in`, `like`, `not_like`。 `like` 与 `not_like` 支持 `%` 通符。
`order_by`	array	可选。结果排序规则。可使用与 `filters` 相同的字段路径。排序方式支持：`asc` 升序、`desc` 降序。单次请求最多支持 3 条排序规则。
`limit`	integer	可选。返回数量上限。默认 `100`，最大 `1000`。
`offset`	integer	可选。结果偏移量，默认 `0`。例如设置为 `10` 时，将跳过前 10 条结果并返回后续数据。
`tag`	string	可选。用户自定义任务标识，最大长度 255。可用于请求与结果对，响应中的 `data` 对象会返回该值。

filters 用法说明

filters 为嵌套数组结构，可组合多个条件。

支持的逻辑与比较操作：

逻辑运算：and、or
比较运算：<, <=, >, >=, =, <>, in, not_in, like, not_like

filters 示例

json

[
 [
 "keyword_data.impressions_info.ad_position_average", ">", 1
 ],
 "and",
 [
 [
 "keyword_data.impressions_info.cpc_max", "<", 0.5
 ],
 "or",
 [
 "keyword_data.impressions_info.daily_clicks_max", ">=", 10
 ]
 ]
]

更多筛选字段可参考 /v3/dataforseo_labs/filters。

order_by 用法说明

order_by 用于设置排序规则，格式为字段路径与排序方向的组合。

默认排序

默认，系统按性排序。

示例

json

[
 "keyword_data.keyword_info.search_volume,desc",
 "keyword_data.keyword_info.cpc,asc"
]

单次请求最多支持 3 条排序规则。

响应结构

接口返回 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` 数组中失败任务数量。
`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 数组字段

字段名	类型	说明
`seed_keyword`	string	请求中提交的种子词。
`seed_keyword_data`	array	种子词数据。在 `include_seed_keyword=true` 时返回。字段结构与 `keyword_data` 一致。
`location_code`	integer	请求中的地区编码。
`language_code`	string	请求中的语言代码。
`total_count`	integer	数据库中与请求的结果总数。
`items_count`	integer	`items` 数组返回条数。
`items`	array	及详细数据。

items 字段说明

`keyword_data`

返回主体数据。

字段名	类型	说明
`keyword`	string	。
`location_code`	integer	地区编码。
`language_code`	string	语言代码。
`keyword_info`	object	基础指标。
`keyword_properties`	object	附加属性。
`impressions_info`	object	展示与广告预估数据。
`bing_keyword_info`	object	基于 Bing Ads 的数据。部分地区和语言支持。
`serp_info`	object / null	SERP 信息。若未设置 `include_serp_info=true`，或数据库中无数据，则为 `null`。

`keyword_info`

字段名	类型	说明
`last_updated_time`	string	数据更新时间，UTC 格式：`yyyy-mm-dd hh:mm:ss +00:00`。
`competition`	float	竞争度，基于 Google Ads 数据，取值范围 `0` 到 `1`。
`cpc`	float	历史平均单次点击费用，单位 USD。
`search_volume`	integer	平均月搜索量。
`categories`	array	产品与服务分类。
`monthly_searches`	array	过去 12 个月的月度搜索量数据。

`monthly_searches` 子字段

字段名	类型	说明
`year`	integer	年份。
`month`	integer	月份。
`search_volume`	integer	该月搜索量。

`keyword_properties`

字段名	类型	说明
`core_keyword`	string / null	组中的核心词。若为 `null`，表示数据库中没有符合该聚类规则的核心词。
`keyword_difficulty`	integer	难度，范围 `0`–`100`。表示自然搜索前 10 的难度，基于 SERP 前 10 页面的链接画像等因素计算。

`impressions_info`

该对象提供比搜索量更细粒度的展示与点击估算数据。daily_impressions 通常可作为搜索量的更准确补。系统使用 999 出价以尽量降低账户差异因素。

字段名	类型	说明
`last_updated_time`	string	展示数据更新时间，UTC 格式。
`bid`	integer	最大 CPC 出价，固定使用 `999` 以获得尽可能完整的展示估算。
`match`	string	匹类型，可为 `exact`、`broad`、`phrase`。
`ad_position_min`	float	广告最小位置。
`ad_position_max`	float	广告最大位置。
`ad_position_average`	float	广告平均位置。
`cpc_min`	float	在出价 `999` 条件下的最小 CPC，单位 USD。不是 CPC。 CPC 请看 `keyword_info.cpc`。
`cpc_max`	float	在出价 `999` 条件下的最大 CPC，单位 USD。不是 CPC。
`cpc_average`	float	在出价 `999` 条件下的平均 CPC，单位 USD。不是 CPC。
`daily_impressions_min`	float	最小日展示量。
`daily_impressions_max`	float	最大日展示量。
`daily_impressions_average`	float	平均日展示量。
`daily_clicks_min`	float	最小日点击量。
`daily_clicks_max`	float	最大日点击量。
`daily_clicks_average`	float	平均日点击量。
`daily_cost_min`	float	最小日花费，单位 USD。
`daily_cost_max`	float	最大日花费，单位 USD。
`daily_cost_average`	float	平均日花费，单位 USD。

`bing_keyword_info`

注意：Bing 数据覆盖部分地区与语言。

字段名	类型	说明
`last_updated_time`	string	Bing 数据更新时间，UTC 格式。
`search_volume`	integer	Bing 最近一个月搜索量。
`monthly_searches`	array	Bing 月度搜索量历史。

`serp_info`

字段名	类型	说明
`check_url`	string	搜索结果直达链接，可用于校验返回结果。
`serp_item_types`	array	SERP 中出现的结果类型。可能：`answer_box`、`app`、`carousel`、`multi_carousel`、`featured_snippet`、`google_flights`、`google_reviews`、`images`、`jobs`、`knowledge_graph`、`local_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`。 `organic`、`paid`、`featured_snippet`、`local_pack` 会返回结果数据。
`se_results_count`	integer	搜索结果总数。
`last_updated_time`	string	SERP 数据更新时间，UTC 格式。
`depth`	integer	当前所在的搜索深度。
`related_keywords`	array	与该的搜索词列表。

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/dataforseo_labs/related_keywords/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "keyword": "phone",
 "language_name": "English",
 "location_code": 2840,
 "include_serp_info": true,
 "filters": [
 ["keyword_data.impressions_info.ad_position_average", ">", 1],
 "and",
 [
 ["keyword_data.impressions_info.cpc_max", "<", 0.5],
 "or",
 ["keyword_data.impressions_info.daily_clicks_max", ">=", 10]
 ]
 ],
 "limit": 5
 }
]'

Python

python

import requests

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

payload = [
 {
 "keyword": "phone",
 "location_name": "United States",
 "language_name": "English",
 "filters": [
 ["keyword_data.impressions_info.ad_position_average", ">", 1],
 "and",
 [
 ["keyword_data.impressions_info.cpc_max", "<", 0.5],
 "or",
 ["keyword_data.impressions_info.daily_clicks_max", ">=", 10]
 ]
 ]
 }
]

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

TypeScript

typescript

import axios from "axios";

const postArray = [
 {
 keyword: "phone",
 language_name: "English",
 location_code: 2840,
 filters: [
 ["keyword_data.impressions_info.ad_position_average", ">", 1],
 "and",
 [
 ["keyword_data.impressions_info.cpc_max", "<", 0.5],
 "or",
 ["keyword_data.impressions_info.daily_clicks_max", ">=", 10]
 ]
 ]
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/dataforseo_labs/related_keywords/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.20220131",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1277 sec.",
 "cost": 0.0103,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "dataforseo_labs",
 "function": "related_keywords",
 "keyword": "phone",
 "language_name": "English",
 "location_code": 2840,
 "include_serp_info": true,
 "filters": [
 ["keyword_data.impressions_info.ad_position_average", ">", 1],
 "and",
 [
 ["keyword_data.impressions_info.cpc_max", "<", 0.5],
 "or",
 ["keyword_data.impressions_info.daily_clicks_max", ">=", 10]
 ]
 ],
 "limit": 5
 },
 "result": [
 {
 "items": [
 {
 "keyword_data": {
 "keyword": "phone",
 "location_code": 2840,
 "language_code": "en",
 "keyword_info": {
 "monthly_searches": []
 },
 "keyword_properties": {
 "core_keyword": null,
 "keyword_difficulty": 100
 },
 "impressions_info": {
 "last_updated_time": "2021-12-30 23:53:30 +00:00",
 "bid": 999,
 "match_type": "exact",
 "ad_position_min": 1.12,
 "ad_position_max": 1,
 "ad_position_average": 1.06,
 "cpc_min": 13.11,
 "cpc_max": 16.02,
 "cpc_average": 14.57,
 "daily_impressions_min": 3682.42,
 "daily_impressions_max": 4500.73,
 "daily_impressions_average": 4091.57,
 "daily_clicks_min": 118.16,
 "daily_clicks_max": 144.42,
 "daily_clicks_average": 131.29,
 "daily_cost_min": 1721.19,
 "daily_cost_max": 2103.68,
 "daily_cost_average": 1912.43
 },
 "bing_keyword_info": {
 "last_updated_time": "2021-12-19 14:26:54 +00:00",
 "search_volume": 54530,
 "monthly_searches": []
 },
 "serp_info": {
 "check_url": "https://www.google.com/search?q=phone&num=100&hl=en&gl=US&gws_rd=cr&ie=UTF-8&oe=UTF-8&uule=w+CAIQIFISCQs2MuSEtepUEUK33kOSuTsc",
 "serp_item_types": [],
 "se_results_count": 3430000000,
 "keyword_difficulty": 100,
 "last_updated_time": "2022-01-13 22:59:31 +00:00",
 "previous_updated_time": null
 }
 },
 "depth": 0,
 "related_keywords": []
 },
 {
 "keyword_data": {
 "keyword": "phone number",
 "location_code": 2840,
 "language_code": "en",
 "keyword_info": {
 "last_updated_time": "2022-01-12 04:30:50 +00:00",
 "competition": 0.16987623914506672,
 "cpc": 1.171982,
 "search_volume": 368000,
 "categories": [],
 "monthly_searches": []
 },
 "keyword_properties": {
 "core_keyword": null,
 "keyword_difficulty": 100
 },
 "impressions_info": {
 "last_updated_time": "2022-01-15 23:06:18 +00:00",
 "bid": 999,
 "match_type": "exact",
 "ad_position_min": 1.17,
 "ad_position_max": 1,
 "ad_position_average": 1.08,
 "cpc_min": 136.18,
 "cpc_max": 166.45,
 "cpc_average": 151.31,
 "daily_impressions_min": 2422.98,
 "daily_impressions_max": 2961.42,
 "daily_impressions_average": 2692.2,
 "daily_clicks_min": 166.36,
 "daily_clicks_max": 203.33,
 "daily_clicks_average": 184.85,
 "daily_cost_min": 25172.88,
 "daily_cost_max": 30766.86,
 "daily_cost_average": 27969.87
 },
 "bing_keyword_info": {
 "last_updated_time": "2022-01-21 21:53:49 +00:00",
 "search_volume": 20090,
 "monthly_searches": []
 },
 "serp_info": {
 "check_url": "https://www.google.com/search?q=phone%20number&num=100&hl=en&gl=US&gws_rd=cr&ie=UTF-8&oe=UTF-8&uule=w+CAIQIFISCQs2MuSEtepUEUK33kOSuTsc",
 "serp_item_types": [],
 "se_results_count": 3650000000,
 "keyword_difficulty": 100,
 "last_updated_time": "2022-01-13 22:33:10 +00:00",
 "previous_updated_time": null
 }
 },
 "depth": 1,
 "related_keywords": []
 },
 {
 "keyword_data": {
 "keyword": "phone samsung",
 "location_code": 2840,
 "language_code": "en",
 "keyword_info": {
 "last_updated_time": "2022-01-21 09:04:53 +00:00",
 "competition": 1,
 "cpc": 5.147537,
 "search_volume": 201000,
 "categories": [],
 "monthly_searches": []
 },
 "keyword_properties": {
 "core_keyword": "samsung phones",
 "keyword_difficulty": 78
 },
 "impressions_info": {
 "last_updated_time": "2022-01-27 14:01:01 +00:00",
 "bid": 999,
 "match_type": "exact",
 "ad_position_min": 1.34,
 "ad_position_max": 1,
 "ad_position_average": 1.21,
 "cpc_min": 285.87,
 "cpc_max": 349.4,
 "cpc_average": 317.63,
 "daily_impressions_min": 765.93,
 "daily_impressions_max": 936.13,
 "daily_impressions_average": 851.03,
 "daily_clicks_min": 52.5,
 "daily_clicks_max": 64.16,
 "daily_clicks_average": 58.33,
 "daily_cost_min": 16674.9,
 "daily_cost_max": 20380.44,
 "daily_cost_average": 18527.67
 },
 "bing_keyword_info": {
 "last_updated_time": "2022-01-31 14:17:06 +00:00",
 "search_volume": 100,
 "monthly_searches": []
 },
 "serp_info": null
 },
 "depth": 1,
 "related_keywords": null
 }
 ]
 }
 ]
 }
 ]
}

错误处理

顶层 status_code 表示整次请求的状态
tasks[].status_code 表示单个任务的执行状态
建议同时检查：
HTTP 状态码
顶层 status_code
tasks_error
各任务 status_code

常见成功状态：

20000：成功

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

使用建议

控制深度与成本：depth 越大，候选越多，处理量也越高。
优加过滤条件：建议结合 search_volume、cpc、competition、keyword_difficulty 等字段筛选。
需要 SERP 特征时再开启 include_serp_info：不的数据开销。
分页获取大量结果：通过 limit + offset 分批拉取。
识别词组核心词：如需统一归类，建议结合 replace_with_core_keyword 与 core_keyword 使用。

实用场景

挖掘长尾词：围绕种子词按深度展开搜索，快速发现更的选题与投放词。
筛选低竞争机会词：结合 competition、keyword_difficulty、search_volume 过滤出更易获取排名的。
评估商业价值：根据 cpc、daily_clicks_average、daily_cost_average 判断的广告价值和转化潜力。
构建主题词簇：利用 core_keyword 与 related_keywords 组织分组，支持专题页、栏目页和集群规划。
校验 SERP 意图变化：启用 include_serp_info 查看 SERP 特征类型，判断更偏资讯、交易还是本地搜索场景。

（旧版）实时查询 ​

接口说明 ​

示例说明 ​

请求方式 ​

计费说明 ​

请求限制 ​

请求参数 ​

filters 用法说明 ​

filters 示例 ​

order_by 用法说明 ​

默认排序 ​

示例 ​

响应结构 ​

顶层字段 ​

tasks 数组字段 ​

result 数组字段 ​

items 字段说明 ​

keyword_data ​

keyword_info ​

monthly_searches 子字段 ​

keyword_properties ​

impressions_info ​

bing_keyword_info ​

serp_info ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

错误处理 ​

使用建议 ​

实用场景 ​

（旧版）实时查询

接口说明

示例说明

请求方式

计费说明

请求限制

请求参数

filters 用法说明

filters 示例

order_by 用法说明

默认排序

示例

响应结构

顶层字段

tasks 数组字段

result 数组字段

items 字段说明

`keyword_data`

`keyword_info`

`monthly_searches` 子字段

`keyword_properties`

`impressions_info`

`bing_keyword_info`

`serp_info`

请求示例

cURL

Python

TypeScript

响应示例

错误处理

使用建议

实用场景