Google Play 应用列表搜索（实时）

本接口用于实时检索 Google Play 已发布应用列表，并返回应用的基础与扩展信息应用 ID、图标、评论数、评分、价格、量、开发信息、更新时间等。

搜索结果会根据请求中传的 title、description 和 categories 条件进行匹。

注意：

• 当前数据支持美国地区，即 location_code=2840
• 请求方式为 POST
• 请求体为 JSON 数组 [{ ... }]
• 接口容路径需保持不变：/v3/app_data/google/app_listings/search/live
• 频率限制：最高支持每分钟 2000 次 API 调用
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

接口地址

POST https://api.seermartech.cn/v3/app_data/google/app_listings/search/live

计费说明

该接口按请求计费。原文未提供固定单价，因此无法换算为固定人民币参考价。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

---

请求参数

以下为任务对象中的可用字段。请按 JSON 数组形式提交，例如：[{ ... }]

字段名	类型	说明
categories	array	应用分类。可选。用于按分类检索应用列表。最多可指定 10 个分类。可通过 /v3/app_data/google/app_listings/categories 获取可用分类列表。
description	string	应用描述中的。可选。用于匹应用描述文本，最大长度 200 字符。
title	string	应用标题中的。可选。用于匹应用标题文本，最大长度 200 字符。
filters	array	结果过滤条件数组。可选。单次请求最多支持 8 个过滤条件。多个条件之间需设置逻辑，如 and、or。
order_by	array	排序规则数组。可选。可使用与 filters 相同的字段进行排序。单次请求最多支持 3 条排序规则。
limit	integer	返回的最大应用数量。可选。默认值：100；最大值：1000。
offset	integer	结果偏移量。可选。默认值：0。例如设置为 10 时，将跳过前 10 条结果并返回后续数据。建议在获取 10000 条结果时使用。
offset_token	string	后续分页请求令牌。可选。用于在获取大结果集时时，适合 ** 100000 条结果**的场景。若请求中指定该参数，则参数与上一次请求保持一致。
tag	string	自定义任务标识。可选。最大长度 255 字符。可用于请求与结果的业务，响应中的 data 对象会返回该值。

filters 支持的运算符

支持以下操作符：

• regex
• not_regex
• <
• <=
• >
• >=
• =
• <>
• in
• not_in
• like
• not_like

说明：

• like 和 not_like 支持 % 通符，用于匹任意长度字符串
• 可通过 /v3/app_data/google/app_listings/available_filters 获取可用过滤字段列表

filters 示例

[
 ["item.rating.value", ">", 4],
 "and",
 ["item.is_free", "=", true]
]

order_by 说明

排序规则格式：

字段名,排序方向

排序方向支持：

• asc：升序
• desc：降序

order_by 示例

[
 "item.rating.value,desc",
 "item.reviews_count,desc"
]

---

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/app_data/google/app_listings/search/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "title": "vpn",
 "description": "vpn",
 "order_by": [
 "item.rating.value,desc"
 ],
 "filters": [
 ["item.rating.value", ">", 4],
 "and",
 ["item.is_free", "=", true]
 ],
 "limit": 10
 }
]'

Python

import requests

url = "https://api.seermartech.cn/v3/app_data/google/app_listings/search/live"
payload = [
 {
 "title": "vpn",
 "description": "vpn",
 "order_by": [
 "item.rating.value,desc"
 ],
 "filters": [
 ["item.rating.value", ">", 4],
 "and",
 ["item.is_free", "=", True]
 ],
 "limit": 3
 }
]
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

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

TypeScript

import axios from "axios";

const postData = [
 {
 title: "vpn",
 description: "vpn",
 categories: ["Tools"],
 order_by: [
 "item.rating.value,desc"
 ],
 filters: [
 ["item.rating.value", ">", 4],
 "and",
 ["item.is_free", "=", true]
 ],
 limit: 10
 }
];

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

---

响应结构

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

顶层字段

字段名	类型	说明
version	string	当前 API 版本。
status_code	integer	通用状态码。完整错误码见 /v3/appendix/errors。建议在系统中对异常和错误状态做完整处理。
status_message	string	通用状态说明。完整说明见 /v3/appendix/errors。
time	string	执行耗时，单位秒。
cost	float	本次请求总费用，单位 USD。
tasks_count	integer	tasks 数组中的任务数量。
tasks_error	integer	返回错误的任务数量。
tasks	array	任务结果数组。

tasks[] 字段

字段名	类型	说明
id	string	任务 ID，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[] 字段

字段名	类型	说明
total_count	integer	数据库中匹结果总数。
count	integer	当前结果集返回的项目数量。
offset	integer	当前结果偏移量。
offset_token	string	下一次分页请求可使用的令牌。适用于大规模结果集拉取。
items	array	应用列表及数据。

items[] 字段

字段名	类型	说明
app_id	string	返回应用的 ID。
se_domain	string	请求中的搜索引擎域名。
location_code	integer	请求中的地区代码。
language_code	string	请求中的语言代码。
check_url	string	可直接访问的 Google Play 页面地址，用于人工校验结果准确性。
time_update	string	数据最近更新时间，ISO 8601 / UTC 时间。示例：2023-05-23 10:16:19 +00:00
item	object	应用详细信息。

item 字段

字段名	类型	说明
type	string	结果类型。当前可能值：google_play_info_organic
rank_group	integer	同类型组排名。
rank_absolute	integer	所有返回应用中的绝对排名。
position	string	结果位置。当前可能值：left
app_id	string	应用 ID。
title	string	应用标题。
url	string	Google Play 应用页链接。
icon	string	应用图标 URL。
description	string	应用描述。
reviews_count	integer	评论总数。
rating	object	平均评分信息。
price	object	价格信息。
is_free	boolean	是否为应用。
main_category	string	主分类。
installs	string	近似量展示文本。
installs_count	integer	精确量。
developer	string	开发名称。
developer_id	string	开发在 Google Play 的 ID。
developer_url	string	开发主页链接。
developer_email	string	开发邮箱。
developer_address	string	开发地址。
developer_website	string	开发官网。
version	string	当前应用版本。
minimum_os_version	string	最低系统版本要求。
size	string	应用大小。
released_date	string	发布时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
last_update_date	string	最近更新时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
update_notes	string	最近更新说明。
images	array	应用截图/图片 URL 列表。
videos	array	应用视频 URL 列表。
similar_apps	array	相似应用列表。
more_apps_by_developer	array	同开发应用列表。
genres	array	应用题材/分类标签。
tags	array	应用标签。

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	结果中展示的原始价格字符串。

similar_apps[] / more_apps_by_developer[] 字段

字段名	类型	说明
app_id	string	应用 ID。
title	string	应用标题。
url	string	应用页链接。

---

响应示例

{
 "version": "0.1.20221214",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1083 sec.",
 "cost": 0.11,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "app_data",
 "function": "search",
 "se": "google",
 "title": "vpn",
 "description": "vpn",
 "categories": [],
 "order_by": [
 "item.rating.value,desc"
 ],
 "filters": [
 ["item.rating.value", ">", 4]
 ],
 "limit": 10
 },
 "result": [
 {
 "total_count": 12345,
 "count": 10,
 "offset": 0,
 "offset_token": "example_offset_token",
 "items": [
 {
 "app_id": "com.oystervpn.app",
 "se_domain": "play.google.com",
 "location_code": 2840,
 "language_code": "en",
 "check_url": "https://play.google.com/store/apps/details?id=com.oystervpn.app&hl=en&gl=us",
 "time_update": "2023-05-23 10:16:19 +00:00",
 "item": {
 "type": "google_play_info_organic",
 "rank_group": 1,
 "rank_absolute": 1,
 "position": "left",
 "app_id": "com.oystervpn.app",
 "title": "OysterVPN: Secure and Fast VPN",
 "url": "https://play.google.com/store/apps/details?id=com.oystervpn.app&hl=en&gl=us",
 "icon": "https://play-lh.googleusercontent.com/sNSk03B05Uj95KPTM5MLpOnMYElXio4sazp8oISXhwcrPJppQ95wIhHo7lUHshfsRw",
 "description": "Buy VPN that protects your privacy on the internet...",
 "reviews_count": 22,
 "rating": {
 "rating_type": "Max5",
 "value": 4.7,
 "votes_count": 22,
 "rating_max": 5
 },
 "price": {
 "current": 0,
 "regular": null,
 "max_value": null,
 "currency": "USD",
 "is_price_range": false,
 "displayed_price": null
 },
 "is_free": true,
 "main_category": "Tools",
 "installs": "100+",
 "installs_count": 184,
 "developer": "Oyster Digital Solutions",
 "developer_id": "Oyster+Digital+Solutions",
 "developer_url": "https://play.google.com/store/apps/developer?id=Oyster+Digital+Solutions",
 "developer_email": "support@oystervpn.com",
 "developer_address": null,
 "developer_website": "https://oystervpn.com",
 "version": "1.15.2",
 "minimum_os_version": "5.0",
 "size": null,
 "released_date": "2022-07-19 03:00:00 +00:00",
 "last_update_date": "2023-05-19 03:00:00 +00:00",
 "update_notes": "This update includes various improvements and bug fixes",
 "images": [],
 "videos": null,
 "similar_apps": [],
 "more_apps_by_developer": null,
 "genres": null,
 "tags": null
 }
 }
 ]
 }
 ]
 }
 ]
}

---

错误处理

请重点以下状态字段：

• 顶层 status_code / status_message
• tasks[].status_code / tasks[].status_message

完整错误码及说明请参考容错误码文档路径：

• /v3/appendix/errors

建议在接时至少处理以下：

• 鉴权失败
• 参数格式错误
• 请求频率限
• 任务级返回错误
• 空结果或分页令牌失效

---

使用建议

1. 小结果集分页

当预计结果不 10000 条时，优使用 offset 分页，逻辑更简单。

2. 大结果集拉取

当需要获取大量结果， 100000 条时，建议改用 offset_token，以降低时风险。

3. 过滤与排序组合

可通过 filters 限定应用范围，再通过 order_by 按评分、评论数等字段排序，从而快速定位高价值应用。

4. 参数一致性要求

如果在后续请求中使用 offset_token，则除 offset_token 外余请求参数与前一次请求保持一致。

实用场景

• 筛选高评分竞品应用：按、分类和评分条件检索 Google Play 应用，快速建立竞品池，用于 ASO 与市场研究。
• 监控细分品类应用分布：按 categories 和描述抓取应用列表，分析某一垂直赛道的产品密度、开发集中度和更新活跃度。
• 挖掘潜在投放对象：结合量、评分、评论数和开发信息，筛选适合商务合作、广告投放或渠道拓展的应用。
• 分析应用与定位：提取标题、描述、标签、分类和更新说明，判断竞品卖点、功能定位与版本迭代方向。
• 追踪开发生态：利用 developer_id、more_apps_by_developer 和 similar_apps，识别同一开发的产品矩阵及相近竞品。