App Store 批量应用指标（实时）

接口说明

该接口用于批量查询 App Store 应用的排名指标，单次请求最多支持 1000 个应用。

返回结果针对你在请求中提交的 app_ids。 app_id 可从 App Store 应用页 URL 中提取，即 URL 中 id 后面的数字。例如：

https://apps.apple.com/us/app/id835599320

上述应用的 app_id 为：

835599320

请求方式：

POST https://api.seermartech.cn/v3/dataforseo_labs/apple/bulk_app_metrics/live

计费与频率限制

• 本接口按请求计费
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准
• 请求体使用 JSON（UTF-8 编码）
• POST 请求体格式为 JSON 数组：[{ ... }]
• 每分钟最多可发起 2000 次 API 调用

请求参数

以下为任务参数说明：

字段名	类型	说明
app_ids	array	填。App Store 应用 ID 列表。可从应用页面 URL 中获取，例如 https://apps.apple.com/us/app/id835599320 中的 ID 为 835599320。该字段最多可传 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 个字符。可用于在响应结果中识别和任务；返回时会出现在响应的 data 对象中。

响应结构

接口返回 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	URL 路径
data	object	回显你在 POST 请求中提交的参数
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.app_store_search_organic	object	App Store 自然搜索中的排名数据
metrics.app_store_search_organic.pos_1	integer	应用在自然结果中排名第 1 的 SERP 数量
metrics.app_store_search_organic.pos_2_3	integer	应用在自然结果中排名第 2-3 位的 SERP 数量
metrics.app_store_search_organic.pos_4_10	integer	应用在自然结果中排名第 4-10 位的 SERP 数量
metrics.app_store_search_organic.pos_11_100	integer	应用在自然结果中排名第 11-100 位的 SERP 数量
metrics.app_store_search_organic.count	integer	含该应用的自然搜索结果总数
metrics.app_store_search_organic.search_volume	integer	该应用所有有排名在 App Store 自然搜索中的总搜索量

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/dataforseo_labs/apple/bulk_app_metrics/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "app_ids": ["835599320", "389801252"],
 "language_name": "English",
 "location_code": 2840
 }
]'

Python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/apple/bulk_app_metrics/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "app_ids": ["835599320", "389801252"],
 "location_name": "United States",
 "language_name": "English"
 }
]

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

TypeScript

import axios from "axios";

const postArray = [
 {
 app_ids: ["835599320", "389801252"],
 language_name: "English",
 location_code: 2840
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/dataforseo_labs/apple/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.2300 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.2300 sec.",
 "cost": 0.0102,
 "result_count": 1,
 "path": [
 "v3",
 "dataforseo_labs",
 "apple",
 "bulk_app_metrics",
 "live"
 ],
 "data": {
 "api": "dataforseo_labs",
 "function": "bulk_app_metrics",
 "se_type": "apple",
 "app_ids": ["835599320", "389801252"],
 "location_code": 2840,
 "language_name": "English"
 },
 "result": [
 {
 "se_type": "apple",
 "app_id": "835599320",
 "location_code": 2840,
 "language_code": "en",
 "total_count": 1,
 "items_count": 1,
 "items": [
 {
 "se_type": "apple",
 "app_id": "835599320",
 "metrics": {
 "app_store_search_organic": {
 "pos_1": 12,
 "pos_2_3": 18,
 "pos_4_10": 35,
 "pos_11_100": 120,
 "count": 185,
 "search_volume": 54200
 }
 }
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理

• 顶层 status_code 表示整次请求的执行状态
• tasks[].status_code 表示单个任务的执行状态
• 建议同时检查顶层状态码和任务状态码，建立完善的异常处理机制
• 完整错误码与状态说明参考 /v3/appendix/errors

通常可重点以下：

状态码	含义
20000	请求成功
状态码	请求参数错误、认证失败、频率限制或系统错误等，需结合 status_message 排查

使用说明

• app_ids 最多支持 1000 个应用 ID，适合批量评估多个 App 的搜索表现
• 地区当前支持 United States / 2840
• 语言当前支持 English / en
• 若同时传 location_name 与 location_code，建议优保证两一致
• 若同时传 language_name 与 language_code，建议优保证两一致

实用场景

• 批量评估竞品可见度：一次性查询多个竞品 App 的自然搜索排名覆盖，快速判断市场头部应用的流量分布。
• 监控自家应用 ASO 表现：跟踪应用在 App Store 自然搜索中的排名区间数量变化，评估标题、和描述优化效果。
• 筛选高潜力应用标的：通过 search_volume 与各排名区间分布，识别拥有高搜索需求且排名基础较强的应用。
• 构建应用对标看板：将多个 app_id 的指标统一拉取，沉淀为应用市场监控面板，支持产品、增长和 ASO 团队协同分析。
• 识别排名结构变化：对比 pos_1、pos_2_3、pos_4_10 等区间分布，定位应用是头部词下滑还是长尾词扩张，从而优化投放与 ASO 策略。