App Store 应用排名实时查询

接口说明

该接口用于查询指定 App 在 App Store 中已获得排名的列表，并返回每个的数据及该 App 在对应下的排名信息。

返回结果严格对应请求中指定的 app_id。

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/keywords_for_app/live

计费说明

该接口按请求次数计费。参考价约 ¥0.1760 / 次扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求规则

请求方法：POST
请求体格式：JSON
编码：UTF-8
请求体为 JSON 数组格式：[{ ... }]
支持结果筛选、排序、分页
频率限制：最高 2000 次 API 调用/分钟

请求参数

字段名	类型	说明
`app_id`	string	填。App Store 应用 ID。可从应用 URL 中获取，例如 `https://apps.apple.com/us/app/id835599320` 中的 `835599320`。
`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`。参考过滤规则文档：`/v3/dataforseo_labs/filters`
`order_by`	array	可选。结果排序规则。可使用与 `filters` 相同的字段路径。排序方式支持：`asc`（升序）、`desc`（降序）。单次请求最多支持 3 条排序规则。默认排序规则由平台 API 确定。
`limit`	integer	可选。返回的最大数量。默认值：`100`；最大值：`1000`
`offset`	integer	可选。结果偏移量。默认值：`0`。例如传 `10` 时，将跳过前 10 条结果，从第 11 条开始返回。
`tag`	string	可选。自定义任务标识，最长 `255` 个字符。可用于请求与响应结果的业务，返回时会出现在响应 `data` 对象中。

filters 使用说明

filters 为数组结构，可组合多个条件。例如按搜索量过滤：

json

[
 ["keyword_data.keyword_info.search_volume", ">=", 500]
]

多个条件组合时，可在条件间使用 and / or，例如：

json

[
 ["keyword_data.keyword_info.search_volume", ">=", 500],
 "and",
 ["ranked_serp_element.serp_item.rank_absolute", "<=", 10]
]

order_by 使用说明

可按字段进行排序，例如：

json

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

响应结构

接口返回 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[] 字段

items 中的每一项表示该 App 已排名的一个及对应数据、排名信息。

字段名	类型	说明
`se_type`	string	搜索引擎类型
`keyword_data`	object	数据
`ranked_serp_element`	object	该下命中的 App Store 搜索结果

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	竞争度，取值范围 `0-1`。该接口场景下通常为 `null`
`competition_level`	string	竞价竞争等级，可能值：`LOW`、`MEDIUM`、`HIGH`；未知时为 `null`。该接口场景下通常为 `null`
`cpc`	float	平均点击成本（USD）。该接口场景下通常为 `null`
`search_volume`	integer	平均月搜索量，表示该在 App Store 中的大致搜索次数
`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/object	命中的 SERP素数据

serp_item 字段

字段名	类型	说明
`type`	string	SERP素类型。固定可能值：`app_store_search_organic`
`rank_group`	integer	在相同 `type`素组的排名
`rank_absolute`	integer	在整个 SERP 中的绝对排名
`position`	string	素位置，可能值：`left`、`right`
`app_id`	string	应用 ID
`title`	string	应用标题
`url`	string	App Store 应用页 URL
`icon`	string	应用图标 URL
`reviews_count`	integer	应用评论总数
`rating`	object	应用评分信息
`is_free`	boolean	是否
`price`	object	应用价格信息
`check_url`	string	结果校验链接，可用于核验返回结果
`se_results_count`	string	该对应的搜索结果数
`last_updated_time`	string	SERP 数据最近更新时间，UTC 格式
`previous_updated_time`	string	上一次 SERP 数据更新时间，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/apple/keywords_for_app/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "app_id": "686449807",
 "language_name": "English",
 "location_code": 2840,
 "filters": [
 ["keyword_data.keyword_info.search_volume", ">=", 500]
 ],
 "limit": 10
 }
]'

Python

python

import requests

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

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

TypeScript

typescript

import axios from "axios";

const postData = [
 {
 app_id: "686449807",
 location_name: "United States",
 language_name: "English",
 filters: [
 ["keyword_data.keyword_info.search_volume", ">=", 500]
 ],
 limit: 10
 }
];

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

响应示例

json

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

状态码与错误处理

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

常用判断方式：

20000：请求成功
状态码：表示参数错误、权限问题、额度不足、频率限制或平台处理异常

完整错误码请参考：/v3/appendix/errors

使用建议

优使用 location_code 和 language_code，便于程序稳定处理。
通过 filters 限制 search_volume、rank_absolute 等字段，可快速聚焦高价值。
使用 limit + offset 做分页拉取，适合大规模应用词库分析。
若需要做任务追踪或结果回写，建议使用 tag 传业务主键。

实用场景

挖掘应用自然流量词：查询目标 App 当前已获得排名的，快速识别自然来源， ASO 词库扩展。
监控核心词排名变化：定期拉取指定应用在重点下的排名位置，及时发现排名波动并优化标题、字幕和字段。
筛选高潜力：结合 search_volume 过滤高搜索量，优优化资源，提升自然下载增长效率。
分析竞品覆盖词：对竞品应用执行相同查询，找出已覆盖而自身未覆盖的，补齐布局缺口。
构建应用资产库：批量采集多个应用的排名词与排名位次，沉淀为 ASO 监控库，用于后续趋势分析与投放协同。

App Store 应用排名实时查询 ​

接口说明 ​

请求地址 ​

计费说明 ​

请求规则 ​

请求参数 ​

filters 使用说明 ​

order_by 使用说明 ​

响应结构 ​

顶层字段 ​

tasks[] 字段 ​

result[] 字段 ​

items[] 字段 ​

keyword_data 字段 ​

keyword_info 字段 ​

ranked_serp_element 字段 ​

serp_item 字段 ​

rating 字段 ​

price 字段 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

状态码与错误处理 ​

使用建议 ​

实用场景 ​

App Store 应用排名实时查询

接口说明

请求地址

计费说明

请求规则

请求参数

filters 使用说明

order_by 使用说明

响应结构

顶层字段

tasks[] 字段

result[] 字段

items[] 字段

keyword_data 字段

keyword_info 字段

ranked_serp_element 字段

serp_item 字段

rating 字段

price 字段

请求示例

cURL

Python

TypeScript

响应示例

状态码与错误处理

使用建议

实用场景