Google Play 批量应用指标（实时）

接口说明

该接口用于批量获取 Google Play 应用的排名指标数据，单次请求最多支持 1000 个应用。

返回结果与请求中传的 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/bulk_app_metrics/live

计费说明

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

根据示例响应，本接口参考价约为 ¥0.1632 / 次，费用会随请求变化。

请求格式

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

[
 {
 "app_ids": ["org.telegram.messenger"],
 "language_name": "English",
 "location_code": 2840
 }
]

接口频率上限为：每分钟最多 2000 次 API 调用。

请求参数

字段名	类型	说明
app_ids	array	填。Google Play 应用 ID 数组。可从应用页 URL 中提取 id 参数值。单次最多传 1000 个 ID。
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
tag	string	可选。用户自定义任务标识，最长 255 个字符。可用于在响应结果中回溯任务。

返回结果说明

接口返回 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 数组中出错的任务数量
tasks	array	任务结果数组

tasks 数组字段

字段名	类型	说明
id	string	任务唯一标识，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000，完整列表参考 /v3/appendix/errors
status_message	string	任务状态信息
time	string	任务执行耗时，单位秒
cost	float	单个任务费用，单位 USD
result_count	integer	result 数组中的结果数量
path	array	请求路径
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 数组字段

字段名	类型	说明
se_type	string	搜索引擎类型
app_id	string	请求中的应用 ID
metrics	object	应用排名对应的指标数据

metrics 字段

metrics 用于描述指定应用在 Google Play 排名上的表现。

google_play_search_organic

字段名	类型	说明
pos_1	integer	应用在自然搜索结果中排名第 1 的 SERP 数量
pos_2_3	integer	应用在自然搜索结果中排名第 2-3 位的 SERP 数量
pos_4_10	integer	应用在自然搜索结果中排名第 4-10 位的 SERP 数量
pos_11_100	integer	应用在自然搜索结果中排名第 11-100 位的 SERP 数量
count	integer	含该应用的自然搜索 SERP 总数
search_volume	integer	该应用所有排名在 Google Play 自然搜索中的总搜索量

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/dataforseo_labs/google/bulk_app_metrics/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "app_ids": ["org.telegram.messenger", "com.whatsapp"],
 "language_name": "English",
 "location_code": 2840,
 "tag": "app-metrics-batch-001"
 }
]'

Python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/google/bulk_app_metrics/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "app_ids": ["org.telegram.messenger", "com.whatsapp"],
 "location_name": "United States",
 "language_name": "English",
 "tag": "app-metrics-batch-001"
 }
]

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

TypeScript

import axios from "axios";

const postArray = [
 {
 app_ids: ["org.telegram.messenger", "com.whatsapp"],
 language_name: "English",
 location_code: 2840,
 tag: "app-metrics-batch-001"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/dataforseo_labs/google/bulk_app_metrics/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);
 });

响应示例

{
 "version": "0.1.20220428",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.2718 sec.",
 "cost": 0.0102,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.2718 sec.",
 "cost": 0.0102,
 "result_count": 1,
 "path": [
 "v3",
 "dataforseo_labs",
 "google",
 "bulk_app_metrics",
 "live"
 ],
 "data": {
 "api": "dataforseo_labs",
 "function": "bulk_app_metrics",
 "se_type": "google",
 "app_ids": [
 "org.telegram.messenger",
 "com.whatsapp"
 ],
 "location_code": 2840,
 "language_code": "en"
 },
 "result": [
 {
 "se_type": "google",
 "app_id": "org.telegram.messenger",
 "location_code": 2840,
 "language_code": "en",
 "total_count": 1,
 "items_count": 1,
 "items": [
 {
 "se_type": "google",
 "app_id": "org.telegram.messenger",
 "metrics": {
 "google_play_search_organic": {
 "pos_1": 12,
 "pos_2_3": 25,
 "pos_4_10": 86,
 "pos_11_100": 340,
 "count": 463,
 "search_volume": 128000
 }
 }
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理

建议对接口返回的 status_code 与任务级 status_code 做统一处理，重点以下场景：

• 顶层 status_code 非 20000：表示请求整体失败
• tasks_error 大于 0：表示部分任务执行失败
• 任务级 status_code 非成功状态：表示对应任务未正常返回结果
• 参数缺失或格式错误：常见于 app_ids 为空，或 location_name/location_code、language_name/language_code 未按要求二选一传

完整错误码与说明请参考：

• /v3/appendix/errors

使用建议

• 批量查询时，建议单次控制在合理范围，一次传过多 app_id 导致结果处理复杂
• 由于该接口当前支持 美国地区 与 英文语言，请在请求前做好参数校验
• 若需稳定追踪同一批任务，建议为每次请求设置 tag
• 若需要枚举可用地区和语言，可调用 /v3/dataforseo_labs/locations_and_languages

实用场景

• 批量评估应用自然排名覆盖度：一次性查询多个应用在 Google Play 自然搜索中的排名分布，快速判断不同产品的占位能力。
• 监控竞品可见性变化：定期拉取竞品 pos_1、pos_2_3、search_volume 等指标，识别竞品在应用商店搜索中的增长或下滑。
• 筛选重点优化应用：通过 pos_11_100 与 search_volume 组合，找出“有搜索量但排名偏后”的应用，优 ASO 优化资源。
• 比较品牌矩阵应用表现：对同旗下多个应用进行统一批量分析，识别头部应用与长尾应用的自然差距。
• 评估流量承接能力：结合应用排名总搜索量，判断某个应用当前在 Google Play 搜索场景下的潜在自然流量规模。