Google Play 应用排名查询

POST /v3/dataforseo_labs/google/keywords_for_app/live

/v3/dataforseo_labs/google/keywords_for_app/live 用于查询某个应用在 Google Play 中已获得排名的列表。

接口会返回目标应用对应的数据，以及该应用在每个下的排名位置。返回结果与请求中指定的 app_id 。

app_id 可从 Google Play 应用页 URL 中获取。例如：

https://play.google.com/store/apps/details?id=org.telegram.messenger

说明：

org.telegram.messenger 即该应用的 app_id

接口地址

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

计费说明

本接口按请求计费。

参考价约 ¥0.1760 / 次

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

请求说明

请求方法：POST
请求体格式：JSON
编码：UTF-8
请求体为 JSON 数组：[{ ... }]
接口限频：最高 2000 次/分钟
支持通过 limit 控制返回数量
支持通过 filters 过滤结果
支持通过 order_by 排序结果

请求参数

字段名	类型	说明
`app_id`	string	填。Google Play 应用 ID。可从应用页 URL 中获取。例如 `org.telegram.messenger`
`location_name`	string	`location_code` 未填写时填。地区名。填写 `location_name` 或 `location_code` 之一。可通过 `/v3/dataforseo_labs/locations_and_languages` 获取可用地区。注意：当前支持美国。示例：`United States`
`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`
`filters`	array	可选。结果过滤条件数组。最多支持 8 个过滤条件。多个条件之间可使用逻辑运算符 `and`、`or`。支持的比较运算符：`<`、`<=`、`>`、`>=`、`=`、`<>`、`in`、`not_in`
`order_by`	array	可选。结果排序规则。可使用与 `filters` 相同的字段进行排序。排序方式支持：`asc`（升序）、`desc`（降序）。单次请求最多支持 3 条排序规则
`limit`	integer	可选。返回的最大数量。默认值：`100`；最大值：`1000`
`offset`	integer	可选。结果偏移量。默认值：`0`。例如设置为 `10` 时，将跳过前 10 个，从后续结果开始返回
`tag`	string	可选。自定义任务标识，最长 `255` 个字符。可用于请求结果对账；响应中的 `data` 对象会原样返回该值

过滤与排序说明

filters

filters 用于筛选返回结果，适合按搜索量、排名等条件缩小结果范围。

支持：

最多 8 个过滤条件
条件间逻辑：and、or
运算符：<、<=、>、>=、=、<>、in、not_in

示例：

json

[
 {
 "app_id": "org.telegram.messenger",
 "location_code": 2840,
 "language_name": "English",
 "filters": [
 ["keyword_data.keyword_info.search_volume", ">=", 500]
 ],
 "limit": 10
 }
]

更多可过滤字段可参考文档中的返回字段路径。

order_by

order_by 用于结果排序。

asc：升序
desc：降序
最多 3 条排序规则

示例：

json

[
 {
 "app_id": "org.telegram.messenger",
 "location_code": 2840,
 "language_name": "English",
 "order_by": [
 "keyword_data.keyword_info.search_volume,desc"
 ],
 "limit": 10
 }
]

返回结果

接口返回 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`
`status_message`	string	任务状态信息
`time`	string	任务执行耗时
`cost`	float	任务费用，单位 USD
`result_count`	integer	`result` 数组中的数量
`path`	array	URL 路径
`data`	object	与请求中提交的参数基本一致
`result`	array	获取结果数组

result 数组字段

字段名	类型	说明
`se_type`	string	搜索引擎类型
`app_id`	string	请求中的应用 ID
`location_code`	integer	请求中的地区编码
`language_code`	string	请求中的语言代码
`total_count`	integer	本平台数据库中与本次请求的总结果数
`items_count`	integer	`items` 数组中返回的结果数
`items`	array	应用已排名明细

items 字段说明

items 中的每一项表示一个目标应用已获得排名的。

字段名	类型	说明
`se_type`	string	搜索引擎类型
`keyword_data`	object	数据
`ranked_serp_element`	array	该下命中的 Google Play 搜索结果信息

keyword_data

字段名	类型	说明
`se_type`	string	搜索引擎类型
`keyword`	string	返回的
`location_code`	integer	请求中的地区编码
`language_code`	string	请求中的语言代码
`keyword_info`	object	指标信息

keyword_info

字段名	类型	说明
`se_type`	string	搜索引擎类型
`last_updated_time`	string	数据更新时间，UTC 格式，如 `2019-11-15 12:57:46 +00:00`
`competition`	float	竞争度，基于 Google Ads 数据，范围 `0` 到 `1`；本接口场景下该值通常为 `null`
`competition_level`	string	付费搜索竞争等级，可选值：`LOW`、`MEDIUM`、`HIGH`；未知时为 `null`；本接口场景下通常为 `null`
`cpc`	float	历史平均点击价格（USD）；本接口场景下通常为 `null`
`search_volume`	integer	平均月搜索量，表示在 Google Play 上的大致搜索次数
`low_top_of_page_bid`	float	首页顶部最低出价；本接口场景下通常为 `null`
`high_top_of_page_bid`	float	首页顶部最高出价；本接口场景下通常为 `null`
`categories`	array	产品/服务分类；本接口场景下通常为 `null`
`monthly_searches`	array	最近 12 个月的月度搜索量；本接口场景下通常为 `null`

ranked_serp_element 字段说明

该对象表示目标应用在某个下对应的搜索结果。

字段名	类型	说明
`se_type`	string	搜索引擎类型
`serp_item`	array	SERP素

serp_item

字段名	类型	说明
`type`	string	SERP素类型。固定值：`google_play_search_organic`
`rank_group`	integer	在相同 `type`素组中的排名
`rank_absolute`	integer	在整个 SERP 中的绝对排名
`position`	string	展示位置，可选值：`left`、`right`
`app_id`	string	应用 ID
`title`	string	应用标题
`url`	string	Google Play 应用页 URL
`icon`	string	应用图标 URL
`reviews_count`	integer	应用评论总数
`rating`	object	应用评分信息
`is_free`	boolean	是否
`price`	object	应用价格信息
`developer`	string	开发名称
`developer_url`	string	Google Play 开发页面 URL
`check_url`	string	可直接查看搜索结果的校验链接，用于核对返回结果
`se_results_count`	string	该对应的搜索结果数量
`last_updated_time`	string	SERP 数据最近更新时间，UTC 格式
`previous_updated_time`	string	上一次更新时间，UTC 格式；无数据时为 `null`

rating

字段名	类型	说明
`rating_type`	string	评分类型，当前为 `Max5`
`value`	float	平均评分值
`votes_count`	integer	评分/反馈数量；本场景下可能为 `null`
`rating_max`	integer	当前评分制的最大值；`Max5` 对应 `5`

price

字段名	类型	说明
`current`	float	当前价格
`regular`	float	常规价格
`max_value`	float	最高价格
`currency`	string	价格币种，ISO 代码
`is_price_range`	boolean	是否为价格区间
`displayed_price`	string	搜索结果中显示的原始价格字符串

请求示例

curl

bash

curl --location --request POST "https://api.seermartech.cn/v3/dataforseo_labs/google/keywords_for_app/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "app_id": "org.telegram.messenger",
 "location_code": 2840,
 "language_name": "English",
 "filters": [
 ["keyword_data.keyword_info.search_volume", ">=", 500]
 ],
 "limit": 10
 }
]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/google/keywords_for_app/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
payload = [
 {
 "app_id": "org.telegram.messenger",
 "location_name": "United States",
 "language_name": "English",
 "filters": [
 ["keyword_data.keyword_info.search_volume", ">=", 500]
 ],
 "limit": 10
 }
]

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

TypeScript

typescript

import axios from "axios";

// 查询某个应用在 Google Play 中已有排名的
const payload = [
 {
 app_id: "org.telegram.messenger",
 location_code: 2840,
 language_name: "English",
 filters: [
 ["keyword_data.keyword_info.search_volume", ">=", 500]
 ],
 limit: 10
 }
];

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

响应示例

json

{
 "version": "0.1.20220428",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.8401 sec.",
 "cost": 0.011,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "dataforseo_labs",
 "function": "keywords_for_app",
 "se_type": "google",
 "app_id": "org.telegram.messenger",
 "language_name": "English",
 "location_code": 2840,
 "limit": 10
 },
 "result": [
 {}
 ]
 }
 ]
}

状态码与错误处理

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

常见成功状态：

状态码	说明
`20000`	请求成功

完整错误码与说明可参考 /v3/appendix/errors。生产环境中建议建立统一的异常处理与重试机制。

使用建议

确认 app_id 是否正确，因应用 ID 错误导致无结果
当前支持：

地区：United States / 2840
语言：English / en

如果需要筛选高价值，建议结合：

keyword_data.keyword_info.search_volume
ranked_serp_element.serp_item.rank_absolute

翻页时使用：

limit
offset

实用场景

分析应用自然获词：查看某个应用当前在 Google Play 已覆盖的，快速了解自然搜索范围
筛选高搜索量词：按 search_volume 过滤高热度，识别最流量价值的应用商店优化方向
监控排名变化：定期拉取指定应用的与 rank_absolute，用于跟踪 ASO 排名波动
评估竞品获词策略：查询竞品应用已排名的集合，反推出标题、描述和投放策略重点
发现增长机会词：结合搜索量与当前排名，找出“已有排名但仍可继续提升”的，制定 ASO 优化优级

Google Play 应用排名查询 ​

接口地址 ​

计费说明 ​

请求说明 ​

请求参数 ​

过滤与排序说明 ​

filters ​

order_by ​

返回结果 ​

顶层响应字段 ​

tasks 数组字段 ​

result 数组字段 ​

items 字段说明 ​

keyword_data ​

keyword_info ​

ranked_serp_element 字段说明 ​

serp_item ​

rating ​

price ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应示例 ​

状态码与错误处理 ​

使用建议 ​

实用场景 ​

Google Play 应用排名查询

接口地址

计费说明

请求说明

请求参数

过滤与排序说明

filters

order_by

返回结果

顶层响应字段

tasks 数组字段

result 数组字段

items 字段说明

keyword_data

keyword_info

ranked_serp_element 字段说明

serp_item

rating

price

请求示例

curl

Python

TypeScript

响应示例

状态码与错误处理

使用建议

实用场景