一、适用场景何时需要使用 App Store 查询 APIApp Store 查询 API 能够根据 App 数字 ID 或应用商店链接获取应用的名称、开发者、版本、评分、用量说明、截图、兼容性等完整信息并支持全球多国家/地区cn、us、jp 等查询。该接口非常适合以下场景应用竞品分析定期拉取竞品的版本更新记录、评分变化、用量说明策略辅助产品决策。例如监控竞争对手是否在短时间内提升了评分或者增加了支持的语言数量。应用上架状态监控自动检测自己的应用是否被下架、是否有新版本发布、兼容性要求是否变化。尤其在多国家/地区同时上架时手动检查维护复杂度极高。ASO 运营优化分析应用截图、描述、分类标签等元数据结合市场定位调整关键词和素材。也可以对比不同国家/地区本地化程度的差异。开发者工具集成在 CI/CD 流水线中验证版本号是否与预期一致发布前检查应用元数据是否完整或在自动化测试中获取当前在线版本信息。市场研究与数据看板聚合多个应用的公开信息构建行业数据看板用于内部汇报或战略规划。这些场景的共同要求是数据实时、字段完整、调用简单。该 API 通过标准化 JSON 返回无需解析 App Store 网页极大降低了开发维护复杂度。二、接口能力边界在集成前开发者需要明确该 API 的能力范围与限制维度说明请求方式仅支持 POST不支持 GET。请求地址https://v1.apizero.cn/api/app-store数据来源实时聚合 App Store 公开元数据返回结构化字段数值和日期已标准化处理。国家/地区支持全球主流国家码如 cn、us、jp、kr、gb 等非法或未支持的国家码会自动回退为cn。参数灵活性app_id和url二选一同时提供时app_id优先。country可选默认为cn。限流策略QPS 为 10 次/秒超出会返回 429 状态码。建议实现请求间隔或退避重试。响应内容返回应用完整元数据包括名称、开发者、版本、评分、用量说明、截图、兼容性、语言数、分类等。需要注意的是该接口不能用于搜索应用或获取用户评论/评分明细只能获取整体评分和评分总数。如需搜索功能需要配合其他接口。三、请求参数与鉴权配置3.1 鉴权方式所有请求需要在 HTTP Header 中携带 API KeyX-API-Key: your_api_key同时必须设置Content-Type: application/json。3.2 请求体结构请求体为一个 JSON对象注原始文档中请求体示例为数组格式但经实际验证单对象即可若批量查询需查阅最新文档包含以下字段字段名类型必填说明app_idstring否与 url 二选一App 的数字 ID例如414478124。与 url 同时提供时优先使用。urlstring否与 app_id 二选一应用商店完整链接例如https://apps.apple.com/cn/app/id414478124系统会自动提取数字 ID。countrystring否两位国家/地区码例如cn、us、jp。不传或非法值默认回退为cn。3.3 参数组合示例仅提供app_idcountry{app_id: 414478124, country: us}仅提供url自动使用链接中的国家码如果链接中包含或默认cn{url: https://apps.apple.com/jp/app/id414478124}同时提供app_id和url系统使用app_id{app_id: 414478124, url: ..., country: cn}四、curl 接入示例以下是一个可直接运行的 curl 命令请将$APIZERO_API_KEY替换为你的真实 API Keycurl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d {app_id: 414478124, url: https://apps.apple.com/cn/app/id414478124, country: cn} \ https://v1.apizero.cn/api/app-store若只关注返回数据可以配合jq解析curl -sS ... | jq .data五、返回字段逐层解读成功响应的 HTTP 状态码为 200返回 JSON 格式顶层字段如下字段类型说明codeint业务状态码0表示成功非 0 表示失败。msgstring状态描述。dataobject应用详细数据。request_idstring本次请求的唯一标识可用于排查问题。data对象中包含丰富的应用信息以下按模块解读5.1 基本信息app_idint数字 ID。namestring应用名称。bundle_idstring例如com.tencent.xin。descriptionstring应用描述可能较长。countrystring返回国家码大写如CN。5.2 版本与更新versionobject包含current当前版本号、days_since_update距离上次更新天数、release_date发布日期格式YYYY-MM-DD、release_notes更新日志。first_release_datestring首次发布日。5.3 评分与评价ratingobject包含average均分float、count总评价数、current_version_average当前版本均分、current_version_count当前版本评价数。注意current_version_average可能与average相同代表近期版本评分。5.4 用量说明信息priceobject包含amount数值float、currency货币码如CNY、formatted格式化的用量说明字符串如或¥6.00、is_free布尔值。5.5 开发者信息developerobject包含name开发者名称、seller_name销售方名称、url开发者页面链接。5.6 分类与评级categoryobject包含primary主分类名英文、primary_idint主分类ID、all数组所有分类的中文或本地化名称。content_ratingstring例如12。5.7 兼容性与文件大小compatibilityobject包含features数组如[iosUniversal]、game_center布尔、min_os_version最低系统版本如15.0、supported_devices_count支持的设备数量int。file_sizeobject包含bytesint、display可读形式如811.78 MB。5.8 截图与图标screenshotsobject按设备类型分组iphone、ipad、appletv每个数组包含URL字符串。若无截图则为空数组。iconobject包含small、medium、large三种尺寸的URL。5.9 其他language_countint支持语言数量。languages数组语言代码如[ZH, EN, JA]。advisories数组版权或警告信息通常为空。store_urlstring应用商店链接。六、常见错误与排查HTTP 状态码业务 codemsg 含义常见原因及处理4001001参数错误app_id 和 url 均缺失或格式不正确。检查请求体 JSON 是否合法。4011002未授权X-API-Key 缺失或无效。确认 API Key 已正确配置。4041003应用不存在提供的 app_id 未找到或者在该国家/地区未上架。尝试更换 country 或检查 ID。4291004请求过于频繁超过 QPS 限制10次/秒。实现请求间隔推荐使用指数退避策略初始退避 1 秒。5009999服务器内部错误服务端异常可稍后重试。所有错误响应都会包含request_id在联系技术支持时务必提供。七、工程化注意事项7.1 API Key 安全管理不要将 API Key 硬编码在代码仓库中应使用环境变量或密钥管理服务如 Vault。在生产环境中建议为不同环境开发、测试、生产创建独立的 Key 并分别授权。7.2 限流处理QPS 为 10意味着每秒最多发送 10 个请求。对于批量查询比如监控 100 个应用需要将请求分散在 10 秒以上并控制并发数。建议使用队列或信号量限制并发并设置重试机制import time import requests API_KEY os.environ[APIZERO_API_KEY] URL https://v1.apizero.cn/api/app-store HEADERS {X-API-Key: API_KEY, Content-Type: application/json} def query_app(app_id, countrycn, retries3): for i in range(retries): resp requests.post(URL, headersHEADERS, json{app_id: app_id, country: country}) if resp.status_code 429: time.sleep(2 ** i) continue return resp.json() return None7.3 缓存策略应用的版本、评分、描述等数据变化频率较低通常几天到几周更新一次建议引入缓存减少请求次数。例如使用 Redis 缓存一天过期后重新拉取。对于需要实时监控的场景可以每 6 小时刷新一次。7.4 字段兼容性返回的screenshots对象可能缺少某个设备类型如 appletv 截图不存在解析时应使用.get()方法避免 KeyError。compatibility中的min_os_version可能为空字符串表示无限制。7.5 多国家/地区查询如果需要同一个应用在不同国家的数据需要分别请求。注意 country 参数不区分大小写但返回的data.country为大写。另外某些应用在部分国家/地区可能未上线会返回 404。7.6 批量查询示例假设要查询 10 个 app_id每个 app_id 需要 cn 和 us 两个国家的数据总共 20 个请求。建议按国家分组每个国家内的请求间隔 100msimport time import requests app_ids [414478124, ...] countries [cn, us] results [] for country in countries: for app_id in app_ids: resp requests.post(URL, headersHEADERS, json{app_id: app_id, country: country}) if resp.status_code 200: results.append(resp.json()[data]) time.sleep(0.1) # 控制每秒10个请求八、参考文档App Store 查询 API 原始文档API 文档页以上文档包含最新的参数说明、国家码列表以及更新日志建议集成前仔细阅读。