排名（旧版）实时查询

POST /v3/dataforseo_labs/ranked_keywords/live

接口说明

注意：本接口为旧版结构（Legacy）。平台 API 已在 2022-03-19 更新请求与响应结构，但本旧版接口仍保持容支持。如需新版本能力，请参考对应的新结构文档。

该接口用于查询任意域名当前正在排名的列表。除了本身外，响应还会返回：

目标域名在该下命中的 SERP素
排名位置信息
展现量与预估流量数据
月搜索量、CPC、竞争度等指标

如果希望查询某个网页的排名，而不是整个域名，应通过 filters 对 ranked_serp_element.serp_item.relative_url 进行过滤。

请求方式：POST
请求地址：https://api.seermartech.cn/v3/dataforseo_labs/ranked_keywords/live
请求体格式：JSON 数组 [{ ... }]
频率限制：最高 2000 次 API 调用/分钟
计费方式：按请求计费，扣费以响应头 X-SeerMarTech-Charge-CNY 为准

请求参数

以下为任务对象中的可用字段。

字段名	类型	说明
`target`	string	填。目标网站域名，不要 `https://` 或 `www.`。如需查询某个页面，请结合 `filters` 按 `ranked_serp_element.serp_item.relative_url` 过滤。
`location_name`	string	可选。地点完整名称。设置后可不传 `location_code`。可通过 `/v3/dataforseo_labs/locations_and_languages` 获取支持的地点列表。不传则返回所有可用地点的数据。示例：`United Kingdom`
`location_code`	integer	可选。地点编码。设置后可不传 `location_name`。可通过 `/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`
`item_types`	array	可选。指定响应中的搜索结果类型。若数组中除 `organic` 外的类型，结果将按数组中的首个类型排序。未的类型无法用于排序和过滤。
`limit`	integer	可选。返回数量上限。默认 `100`，最大 `1000`。
`offset`	integer	可选。结果偏移量。默认 `0`。如传 `10`，则跳过前 10 条结果，从第 11 条开始返回。
`load_rank_absolute`	boolean	可选。是否返回按 `rank_absolute` 聚合的排名分布。默认 `false`。设置为 `true` 时，响应中会返回 `metrics_absolute`。
`filters`	array	可选。结果过滤条件数组。最多可设置 `8` 个过滤条件，条件之间需使用逻辑运算符 `and` 或 `or`。支持运算符：`<`、`<=`、`>`、`>=`、`=`、`<>`、`in`、`not_in`、`like`、`not_like`。`like` / `not_like` 支持 `%` 通符。
`order_by`	array	可选。排序规则。可使用与 `filters` 相同的字段路径。排序方式：`asc` 升序、`desc` 降序。单次请求最多设置 `3` 条排序规则。
`tag`	string	可选。自定义任务标识，最长 `255` 个字符。便于将请求与响应匹，返回结果中的 `data` 对象会原样带回该值。

`item_types` 可选值

响应支持返回以下 SERP素类型的数据：

organic
paid
featured_snippet
local_pack

`filters` 示例

查询某个页面的排名时，可使用：

json

[
 ["ranked_serp_element.serp_item.relative_url", "=", "/blog/seo-guide/"]
]

组合过滤示例：

json

[
 ["keyword_data.keyword_info.search_volume", "<>", 0],
 "and",
 [
 ["ranked_serp_element.serp_item.type", "<>", "paid"],
 "or",
 ["ranked_serp_element.serp_item.is_malicious", "=", false]
 ]
]

`order_by` 示例

json

[
 "keyword_data.keyword_info.search_volume,desc",
 "ranked_serp_element.serp_item.rank_group,asc"
]

默认排序规则由平台 API 按逻辑处理；如需稳定分页，建议显式指定排序。

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/dataforseo_labs/ranked_keywords/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "target": "example.com",
 "language_name": "English",
 "location_code": 2840,
 "filters": [
 ["keyword_data.keyword_info.search_volume", "<>", 0],
 "and",
 [
 ["ranked_serp_element.serp_item.type", "<>", "paid"],
 "or",
 ["ranked_serp_element.serp_item.is_malicious", "=", false]
 ]
 ],
 "limit": 5
 }
]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/ranked_keywords/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
payload = [
 {
 "target": "example.com",
 "location_name": "United States",
 "language_name": "English",
 "filters": [
 ["keyword_data.keyword_info.search_volume", "<>", 0],
 "and",
 [
 ["ranked_serp_element.serp_item.type", "<>", "paid"],
 "or",
 ["ranked_serp_element.serp_item.is_malicious", "=", False]
 ]
 ]
 }
]

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

TypeScript

typescript

import axios from "axios";

const payload = [
 {
 target: "example.com",
 language_name: "English",
 location_code: 2840,
 filters: [
 ["keyword_data.keyword_info.search_volume", "<>", 0],
 "and",
 [
 ["ranked_serp_element.serp_item.type", "<>", "paid"],
 "or",
 ["ranked_serp_element.serp_item.is_malicious", "=", false]
 ]
 ]
 }
];

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

响应结构

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

顶层字段

字段名	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	通用状态码
`status_message`	string	通用状态消息
`time`	string	执行时间，单位秒
`cost`	float	本次请求总费用，单位 USD；参考价约按响应头中的扣费金额估算，扣费以响应头 `X-SeerMarTech-Charge-CNY` 为准
`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[]` 字段

字段名	类型	说明
`target`	string	请求中的目标域名
`location_code`	integer	请求中的地点编码；无数据时为 `null`
`language_code`	string	请求中的语言编码；无数据时为 `null`
`total_count`	integer	数据库中符合当前条件的总结果数
`items_count`	integer	当前 `items` 数组返回的结果数
`metrics`	object	按 `rank_group` 统计的排名分布与流量数据
`metrics_absolute`	object	按 `rank_absolute` 统计的排名分布；在 `load_rank_absolute=true` 时返回
`items`	array	排名及数据

`metrics` 字段说明

metrics 按 rank_group（只在相同 SERP素类型计位）返回分布数据。可能以下对象：

organic
paid
featured_snippet
local_pack

每个对象通常都以下字段：

字段名	类型	说明
`pos_1`	integer	排名第 1 位的数量
`pos_2_3`	integer	排名第 2-3 位的数量
`pos_4_10`	integer	排名第 4-10 位的数量
`pos_11_20`	integer	排名第 11-20 位的数量
`pos_21_30`	integer	排名第 21-30 位的数量
`pos_31_40`	integer	排名第 31-40 位的数量
`pos_41_50`	integer	排名第 41-50 位的数量
`pos_51_60`	integer	排名第 51-60 位的数量
`pos_61_70`	integer	排名第 61-70 位的数量
`pos_71_80`	integer	排名第 71-80 位的数量
`pos_81_90`	integer	排名第 81-90 位的数量
`pos_91_100`	integer	排名第 91-100 位的数量
`etv`	float	预估流量
`impressions_etv`	float	基于展现量估算的预估流量
`count`	integer	命中的 SERP 总数
`estimated_paid_traffic_cost`	float	预估将该流量通过付费广告获取所需成本
`is_new`	integer	新增排名数量
`is_up`	integer	排名上升的数量
`is_down`	integer	排名下降的数量
`is_lost`	integer	丢失排名的数量

指标解释

etv：预估自然/付费月流量，通常由 CTR 与搜索量估算。
impressions_etv：基于展现量估算的流量，更适合作为搜索量的替代参考。
estimated_paid_traffic_cost：将当前自然流量等效为 PPC 流量时的估算成本。

`metrics_absolute` 字段说明

当 load_rank_absolute=true 时返回。结构与 metrics 类似，但统计口径改为 rank_absolute，即在所有 SERP素中的绝对位置，而不是在同类型计位。

支持的子对象同样：

organic
paid
featured_snippet
local_pack

字段：

pos_1
pos_2_3
pos_4_10
pos_11_20
pos_21_30
pos_31_40
pos_41_50
pos_51_60
pos_61_70
pos_71_80
pos_81_90
pos_91_100
is_new
is_up
is_down
is_lost

`items[]` 字段说明

每个 items素两个核心部分：

keyword_data：数据
ranked_serp_element：目标域名在该下命中的 SERP素及排名信息

`keyword_data`

字段名	类型	说明
`keyword`	string	返回的
`location_code`	integer	请求中的地点编码
`language_code`	integer	请求中的语言编码
`keyword_info`	object	基础指标
`impressions_info`	object	展现量数据
`bing_keyword_info`	object	基于 Bing Ads 的数据部分地点和语言可用
`serp_info`	object	该的 SERP 信息

`keyword_data.keyword_info`

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

monthly_searches[] 子字段：

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

`keyword_data.impressions_info`

该部分提供基于广告展现量的数据，可作为搜索量更精细的替代参考。平台使用 bid=999 以尽量减少账户差异对数据的影响。

字段名	类型	说明
`last_updated_time`	string	数据更新时间
`bid`	integer	最大 CPC 出价，固定用于估算，通常为 `999`
`match` / `match_type`	string	匹类型：`exact`、`broad`、`phrase`
`ad_position_min`	float	广告最小位置
`ad_position_max`	float	广告最大位置
`ad_position_average`	float	广告平均位置
`cpc_min`	float	在 `bid=999` 条件下的最小 CPC 估值，不等同于真实 CPC
`cpc_max`	float	在 `bid=999` 条件下的最大 CPC 估值，不等同于真实 CPC
`cpc_average`	float	在 `bid=999` 条件下的平均 CPC 估值，不等同于真实 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

`keyword_data.bing_keyword_info`

字段名	类型	说明
`last_updated_time`	string	数据更新时间
`search_volume`	integer	Bing 过去一个月的搜索量
`monthly_searches`	array	指定地点下的 Bing 月度搜索量

`keyword_data.serp_info`

字段名	类型	说明
`check_url`	string	搜索结果直达链接，可用于校验结果
`serp_item_types`	array	当前 SERP 中出现的结果类型列表
`se_results_count`	string	搜索结果总数
`keyword_difficulty`	integer	难度，范围 `0-100`，表示自然前 10 的难度
`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、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 四类命中的详细数据。

`ranked_serp_element` 字段说明

该对象表示目标域名针对当前命中的 SERP素。

通用字段

字段名	类型	说明
`serp_item`	object	命中的 SERP素
`check_url`	string	搜索结果直达链接
`serp_item_types`	array	当前 SERP 中出现的结果类型
`se_results_count`	string	搜索结果总数
`keyword_difficulty`	integer	难度
`last_updated_time`	string	最近一次 SERP 更新时间
`previous_updated_time`	string	上一次 SERP 更新时间

`serp_item` 支持的类型

1. `organic`

字段名	类型	说明
`type`	string	固定为 `organic`
`rank_group`	integer	同类型中的位置
`rank_absolute`	integer	在 SERP素中的绝对位置
`position`	string	左右布局位置：`left` / `right`
`xpath`	string	素 XPath
`domain`	string	SERP 中的子域名
`title`	string	标题
`url`	string	落地页 URL
`breadcrumb`	string	面屑路径
`is_image`	boolean	是否图片
`is_video`	boolean	是否视频
`is_featured_snippet`	boolean	是否同时为精选摘要
`is_malicious`	boolean	是否被标记为恶意
`description`	string	描述摘要
`pre_snippet`	string	描述前附加信息
`extended_snippet`	string	描述后附加信息
`amp_version`	boolean	是否有 AMP 版本
`rating`	object	评分信息
`highlighted`	array	描述中加粗高亮词
`links`	array	sitelinks 子链接
`main_domain`	string	主域名
`relative_url`	string	相对路径，不协议与域名
`etv`	float	该对应的预估自然流量
`impressions_etv`	float	基于展现量估算的自然流量
`estimated_paid_traffic_cost`	float	等效付费流量成本
`rank_changes`	object	相对上一次抓取的排名变化

`rating`

字段名	类型	说明
`rating_type`	string	评分类型：`Max5`、`Percents`、`CustomMax`
`value`	integer	评分值
`votes_count`	integer	评价数
`rating_max`	integer	评分上限

`links[]`

字段名	类型	说明
`type`	string	固定为 `link_element`
`title`	string	子链接标题
`description`	string	子链接描述
`url`	string	子链接 URL

`rank_changes`

字段名	类型	说明
`previous_rank_absolute`	integer	上次绝对排名；若为新结果则为 `null`
`is_new`	boolean	是否为新出现的
`is_up`	boolean	是否排名上升
`is_down`	boolean	是否排名下降

2. `paid`

字段名	类型	说明
`type`	string	固定为 `paid`
`rank_group`	integer	同类型中的位置
`rank_absolute`	integer	绝对排名
`position`	string	左右布局位置
`xpath`	string	素 XPath
`title`	string	广告标题
`domain`	string	广告域名
`description`	string	广告描述
`breadcrumb`	string	广告面屑
`url`	string	广告 URL
`highlighted`	array	描述中高亮词
`extra`	array	附加信息
`ad_aclk`	string	广告标识
`description_rows`	array	扩展描述行，无则为 `null`
`links`	array	广告子链接
`main_domain`	string	主域名
`relative_url`	string	相对路径
`etv`	float	预估流量
`impressions_etv`	float	基于展现量的预估流量
`estimated_paid_traffic_cost`	float	预估付费流量成本
`rank_changes`	object	排名变化

links[] 子项字段：

字段名	类型	说明
`type`	string	固定为 `ad_link_element`
`title`	string	子链接标题
`description`	string	子链接描述
`url`	string	子链接 URL
`ad_aclk`	string	广告标识

3. `local_pack`

字段名	类型	说明
`type`	string	固定为 `local_pack`
`rank_group`	integer	同类型中的位置
`rank_absolute`	integer	绝对排名
`position`	string	左右布局位置
`xpath`	string	素 XPath
`title`	string	标题
`description`	string	描述
`domain`	string	域名
`phone`	string	电话号码
`url`	string	链接
`is_paid`	boolean	是否为广告
`rating`	object	评分信息
`main_domain`	string	主域名
`relative_url`	string	相对路径
`etv`	float	预估流量
`impressions_etv`	float	基于展现量的预估流量
`estimated_paid_traffic_cost`	float	等效付费流量成本
`rank_changes`	object	排名变化

4. `featured_snippet`

字段名	类型	说明
`type`	string	固定为 `featured_snippet`
`rank_group`	integer	同类型中的位置
`rank_absolute`	integer	绝对排名
`position`	string	左右布局位置
`xpath`	string	素 XPath
`domain`	string	域名
`title`	string	标题
`featured_title`	string	精选摘要来源页标题
`description`	string	描述
`url`	string	链接
`table`	array	摘要表格，无则为 `null`
`main_domain`	string	主域名
`relative_url`	string	相对路径
`etv`	float	预估流量
`impressions_etv`	float	基于展现量的预估流量
`estimated_paid_traffic_cost`	float	等效付费流量成本
`rank_changes`	object	排名变化

`table[]`

字段名	类型	说明
`table_header`	array	列名
`table_content`	array	表格，每个代表一行

响应示例

json

{
 "version": "0.1.20210917",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.6659 sec.",
 "cost": 0.0102,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "dataforseo_labs",
 "function": "ranked_keywords",
 "target": "example.com",
 "language_name": "English",
 "location_code": 2840,
 "limit": 2,
 "filters": [
 ["keyword_data.keyword_info.search_volume", "<>", 0],
 "and",
 [
 ["ranked_serp_element.serp_item.type", "<>", "paid"],
 "or",
 ["ranked_serp_element.serp_item.is_malicious", "=", false]
 ]
 ]
 },
 "result": [
 {
 "items": [
 {
 "keyword_data": {
 "keyword": "example keyword",
 "keyword_info": {
 "last_updated_time": "2021-09-24 08:13:37 +00:00",
 "competition": 0.12,
 "cpc": 7.46,
 "search_volume": 170,
 "categories": null,
 "monthly_searches": []
 },
 "impressions_info": {
 "last_updated_time": "2021-09-24 08:13:37 +00:00",
 "bid": 999,
 "match_type": "exact",
 "ad_position_min": 1.67,
 "ad_position_max": 1,
 "ad_position_average": 1.52,
 "cpc_min": 507.19,
 "cpc_max": 619.90,
 "cpc_average": 563.54,
 "daily_impressions_min": 2.41,
 "daily_impressions_max": 2.94,
 "daily_impressions_average": 2.68
 },
 "serp_info": {
 "check_url": "https://www.google.com/search?q=example%20keyword&num=100&hl=en&gl=US",
 "serp_item_types": ["organic", "paid"],
 "se_results_count": 606000000,
 "keyword_difficulty": null,
 "last_updated_time": "2021-10-23 12:49:59 +00:00",
 "previous_updated_time": "2021-08-28 14:45:37 +00:00"
 }
 },
 "ranked_serp_element": {
 "serp_item": {
 "type": "organic",
 "rank_group": 1,
 "rank_absolute": 1,
 "position": "left",
 "domain": "example.com",
 "title": "Example Title",
 "url": "https://example.com/",
 "breadcrumb": "https://example.com",
 "is_image": false,
 "is_video": false,
 "is_featured_snippet": false,
 "is_malicious": false,
 "description": "Example description",
 "main_domain": "example.com",
 "relative_url": "/",
 "etv": 15.2,
 "impressions_etv": 24.44,
 "estimated_paid_traffic_cost": 119.48,
 "rank_changes": {
 "previous_rank_absolute": 1,
 "is_new": false,
 "is_up": false,
 "is_down": false
 }
 },
 "check_url": "https://www.google.com/search?q=example%20keyword&num=100&hl=en&gl=US",
 "serp_item_types": ["organic", "paid"],
 "se_results_count": 606000000,
 "keyword_difficulty": null,
 "last_updated_time": "2021-10-23 12:49:59 +00:00",
 "previous_updated_time": "2021-08-28 14:45:37 +00:00"
 }
 }
 ]
 }
 ]
 }
 ]
}

错误码说明

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

常见成功状态：

20000：成功

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

使用建议

按页面筛选：若要查看某个 URL 的排名，请通过 ranked_serp_element.serp_item.relative_url 过滤。
控制结果量：大域名结果很多时，建议结合 limit、offset、order_by 做分页拉取。
区分排名口径：

rank_group：同类型 SERP素排名
rank_absolute：所有 SERP素的绝对排名

优使用展现量指标：若业务更真实流量潜力，可同时参考 impressions_info 与 impressions_etv。
按 SERP 类型分析：通过 item_types 可聚焦自然结果、广告、精选摘要或本地结果。

实用场景

挖掘域名自然流量：批量获取某站已排名及搜索量、CPC、ETV，快速识别带来流量的核心词。
定位单页面排名覆盖：通过 relative_url 过滤页面，评估该页面覆盖了哪些搜索意图，指导优化。
监控 SERP 形态变化：识别下命中的 organic、featured_snippet、local_pack、paid 类型，判断是否需要调整 SEO 或本地化策略。
评估排名波动风险：结合 rank_changes、is_up、is_down、is_lost 追踪与页面排名变化，及时发现流量下滑原因。
估算商业价值：利用 cpc、estimated_paid_traffic_cost 和 etv 评估自然排名节省的广告成本，支持 SEO 投产出分析。

排名（旧版）实时查询 ​

接口说明 ​

请求参数 ​

item_types 可选值 ​

filters 示例 ​

order_by 示例 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

tasks[] 字段 ​

result[] 字段 ​

metrics 字段说明 ​

指标解释 ​

metrics_absolute 字段说明 ​

items[] 字段说明 ​

keyword_data ​

keyword_data.keyword_info ​

keyword_data.impressions_info ​

keyword_data.bing_keyword_info ​

keyword_data.serp_info ​

ranked_serp_element 字段说明 ​

通用字段 ​

serp_item 支持的类型 ​

1. organic ​

rating ​

links[] ​

rank_changes ​

2. paid ​

3. local_pack ​

排名（旧版）实时查询

接口说明

请求参数

`item_types` 可选值

`filters` 示例

`order_by` 示例

请求示例

cURL

Python

TypeScript

响应结构

顶层字段

`tasks[]` 字段

`result[]` 字段

`metrics` 字段说明

指标解释

`metrics_absolute` 字段说明

`items[]` 字段说明

`keyword_data`

`keyword_data.keyword_info`

`keyword_data.impressions_info`

`keyword_data.bing_keyword_info`

`keyword_data.serp_info`

`ranked_serp_element` 字段说明

通用字段

`serp_item` 支持的类型

1. `organic`

`rating`

`links[]`

`rank_changes`

2. `paid`

3. `local_pack`