适用场景App Store 查询接口主要用于按 App 数字 ID 或应用商店链接获取应用的元数据。对开发者来说常见的落地场景包括竞品分析批量采集竞品的版本迭代节奏、评分变化与用量说明策略。上架状态监控定时轮询自己或合作方 App 的当前版本与最近更新时间。ASO 运营关注应用名称、分类、内容分级、语言数量等影响关键词覆盖的基础字段。开发者工具集成在 CI/CD 流程或运营后台中按需拉取应用信息辅助自动化生成报表。该接口输入输出均为结构化的 JSON适合在服务端脚本中直接对接也可以用于原型验证和数量较小的运维场景。接口能力边界在动手写代码之前先明确接口能做什么、不能做什么可以避免后续重复联调。输入方式同时支持app_id与url两种入参二者二选一即可app_id优先。区域设置通过country参数指定商店区域两位国家/地区码非法值会自动回退到cn。返回内容包含应用名称、开发者、当前版本、评分、用量说明、截图、兼容性、文件大小、语言列表、首次上架日期等字段。QPS 限制接口目前的配额为每秒 10 次超出后大概率触发限流需要在客户端做好重试与退避。数据时效接口返回的是实时聚合数据但版本信息受 App Store 侧更新延迟影响具体以实际返回值为准。注意接口可以返回版本更新说明release_notes但不会提供应用内查看文档项目、关键词排名、广告位等不在字段清单里的数据。请求参数与鉴权Header 参数参数是否必需类型说明Content-Type是string请求体格式固定为application/jsonX-API-Key是stringAPI 密钥用于请求鉴权请求体字段请求体为一个 JSON 对象字段说明如下字段类型是否必需说明app_idstring否App 数字 ID与url二选一优先使用urlstring否应用商店链接服务端会自动提取其中携带的数字 IDcountrystring否两位国家/地区码例如cn、us、jp非法值回退到cn一个合法的请求体示例如下{ app_id: 414478124, url: https://apps.apple.com/cn/app/id414478124, country: cn }为了减少歧义实际调用时建议只传一种应用标识。如果希望优先使用app_id可以不传url反之只传url同样可以工作。curl 接入示例以下是一个可直接复制的 curl 请求将其中的$APIZERO_API_KEY替换为你自己的密钥即可curl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d {app_id: 414478124, country: cn} \ https://v1.apizero.cn/api/app-store如果只想通过链接查询请求体可以改成curl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d {url: https://apps.apple.com/cn/app/id414478124, country: cn} \ https://v1.apizero.cn/api/app-store响应中的request_id是单次请求的唯一标识。如果后续排查问题可以把该 ID 与请求参数一并保留便于对照日志。返回字段解读接口成功时返回外层code、msg、data、request_id四个字段。其中data是核心语义所在下面按模块拆解。应用基本信息字段类型说明app_idnumber应用数字 IDbundle_idstring应用包名例如com.tencent.xinnamestring应用名称descriptionstring应用描述文案store_urlstringApp Store 中的官方页面链接分类与评级category对象包含primary主分类的本地化名称例如Social Networking。primary_id主分类对应的数字 ID。all应用所属的全部分类名称数组。content_rating表示内容分级返回值为类似12的字符串。版本信息version: { current: 8.0.75, days_since_update: 17, release_date: 2026-06-14, release_notes: 本次更新解决了一些已知问题。 }注意days_since_update是相对当前日期的整数适合用来判断应用是否处于活跃更新周期。release_notes的文案由开发商在 App Store Connect 中填写可能存在空字符串。评分与用量说明rating对象包含average历史平均分。count历史评分总数。current_version_average当前版本的平均分。current_version_count当前版本的评分总数。price对象包含amount数值型用量说明。currency货币代码。formatted格式化后的用量说明文本。is_free是否为应用。截图与图标screenshots按设备类型分组通常包含iphone、ipad、appletv数组。不同应用的截图数量差异较大接收入库前请先判断数组长度。icon对象提供small、medium、large三种尺寸分别是 60x60、100x100、512x512 左右的图片。兼容性信息compatibility: { features: [iosUniversal], game_center: false, min_os_version: 15.0, supported_devices_count: 128 }其中min_os_version为最低系统版本要求supported_devices_count是当前所有支持设备的总数。该字段可能随 App Store 设备列表变化而调整不建议作为固定值缓存太久。常见错误排查实际接入时最常见的几类问题如下1. 返回鉴权失败或不识别 API Key检查请求头中的X-API-Key是否完整填写注意不要在值两侧误加空格。确认密钥使用的是当前环境的有效值。如果是在团队内共享脚本建议通过环境变量引用密钥避免硬编码到代码仓库。2. 返回 400 参数错误确认请求体是合法的 JSON不能有多余的尾逗号。app_id与url同时不传时无法定位目标应用。app_id只能包含数字不要传入带id前缀的内容。3. 返回区域不符合预期查看请求体中的country是否为两位小写国家码。如果传入了非法值接口会回退到cn此时返回的country字段会与预期不同。4. 限流触发接口 QPS 为 10循环调用时建议控制并发数。可以用信号量或令牌桶把请求速率压在阈值以下同时捕获限流响应后执行指数退避重试。工程化注意事项1. 参数校验前置在发起 HTTP 请求前先在本地对app_id和url做基础校验import re def normalize_app_id(value: str) - str: 提取 App 数字 ID兼容纯数字与商店链接。 value value.strip() if value.isdigit(): return value match re.search(r/id(\d), value) if match: return match.group(1) raise ValueError(f无法从入参中解析 app_id: {value})这样可以减少无效请求降低触发限流的概率。2. 缓存策略App 的基础信息名称、分类、开发者变化频率很低而评分、版本号、文件大小属于中频数据。建议把响应写入本地缓存设置 TTL 为 30 分钟到 1 小时。对于批量任务可先查缓存再请求网络。3. 字段落库前的类型处理JSON 响应中的数值类型需要特别留意app_id在返回体中是数字但在请求体中推荐使用字符串防止精度丢失。release_date是YYYY-MM-DD格式适合直接作为日期类型存储。rating.current_version_count可能为0不要直接做除法或写入非空约束。4. 网络层容错不要假设接口每次都会成功。建议实现连接超时3 秒。读取超时10 秒。重试策略对 429/5xx 做最多 3 次退避重试间隔为 1 秒、2 秒、4 秒。5. 使用请求 ID 做全链路追踪每次响应的request_id字段可以在出错时提供给服务端排查。建议在日志中打印请求参数、HTTP 状态码、耗时和request_id并将它们关联到业务单号。小结通过app_id或url两种入参配合country区域设置即可在一条请求内拿到 App Store 应用的版本、评分、用量说明、截图、兼容性等核心字段。对接过程本身不复杂真正的注意点集中在参数校验、限流控制和返回字段的缓存策略上。建议先以小批量脚本验证返回结构再逐步扩展到批量任务和监控系统。参考文档接口文档https://apizero.cn/aidocs/app-store原始文档https://apizero.cn/aidocs/app-store/raw.md
App Store 查询 API 零基础接入：参数说明与返回字段解析
适用场景App Store 查询接口主要用于按 App 数字 ID 或应用商店链接获取应用的元数据。对开发者来说常见的落地场景包括竞品分析批量采集竞品的版本迭代节奏、评分变化与用量说明策略。上架状态监控定时轮询自己或合作方 App 的当前版本与最近更新时间。ASO 运营关注应用名称、分类、内容分级、语言数量等影响关键词覆盖的基础字段。开发者工具集成在 CI/CD 流程或运营后台中按需拉取应用信息辅助自动化生成报表。该接口输入输出均为结构化的 JSON适合在服务端脚本中直接对接也可以用于原型验证和数量较小的运维场景。接口能力边界在动手写代码之前先明确接口能做什么、不能做什么可以避免后续重复联调。输入方式同时支持app_id与url两种入参二者二选一即可app_id优先。区域设置通过country参数指定商店区域两位国家/地区码非法值会自动回退到cn。返回内容包含应用名称、开发者、当前版本、评分、用量说明、截图、兼容性、文件大小、语言列表、首次上架日期等字段。QPS 限制接口目前的配额为每秒 10 次超出后大概率触发限流需要在客户端做好重试与退避。数据时效接口返回的是实时聚合数据但版本信息受 App Store 侧更新延迟影响具体以实际返回值为准。注意接口可以返回版本更新说明release_notes但不会提供应用内查看文档项目、关键词排名、广告位等不在字段清单里的数据。请求参数与鉴权Header 参数参数是否必需类型说明Content-Type是string请求体格式固定为application/jsonX-API-Key是stringAPI 密钥用于请求鉴权请求体字段请求体为一个 JSON 对象字段说明如下字段类型是否必需说明app_idstring否App 数字 ID与url二选一优先使用urlstring否应用商店链接服务端会自动提取其中携带的数字 IDcountrystring否两位国家/地区码例如cn、us、jp非法值回退到cn一个合法的请求体示例如下{ app_id: 414478124, url: https://apps.apple.com/cn/app/id414478124, country: cn }为了减少歧义实际调用时建议只传一种应用标识。如果希望优先使用app_id可以不传url反之只传url同样可以工作。curl 接入示例以下是一个可直接复制的 curl 请求将其中的$APIZERO_API_KEY替换为你自己的密钥即可curl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d {app_id: 414478124, country: cn} \ https://v1.apizero.cn/api/app-store如果只想通过链接查询请求体可以改成curl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d {url: https://apps.apple.com/cn/app/id414478124, country: cn} \ https://v1.apizero.cn/api/app-store响应中的request_id是单次请求的唯一标识。如果后续排查问题可以把该 ID 与请求参数一并保留便于对照日志。返回字段解读接口成功时返回外层code、msg、data、request_id四个字段。其中data是核心语义所在下面按模块拆解。应用基本信息字段类型说明app_idnumber应用数字 IDbundle_idstring应用包名例如com.tencent.xinnamestring应用名称descriptionstring应用描述文案store_urlstringApp Store 中的官方页面链接分类与评级category对象包含primary主分类的本地化名称例如Social Networking。primary_id主分类对应的数字 ID。all应用所属的全部分类名称数组。content_rating表示内容分级返回值为类似12的字符串。版本信息version: { current: 8.0.75, days_since_update: 17, release_date: 2026-06-14, release_notes: 本次更新解决了一些已知问题。 }注意days_since_update是相对当前日期的整数适合用来判断应用是否处于活跃更新周期。release_notes的文案由开发商在 App Store Connect 中填写可能存在空字符串。评分与用量说明rating对象包含average历史平均分。count历史评分总数。current_version_average当前版本的平均分。current_version_count当前版本的评分总数。price对象包含amount数值型用量说明。currency货币代码。formatted格式化后的用量说明文本。is_free是否为应用。截图与图标screenshots按设备类型分组通常包含iphone、ipad、appletv数组。不同应用的截图数量差异较大接收入库前请先判断数组长度。icon对象提供small、medium、large三种尺寸分别是 60x60、100x100、512x512 左右的图片。兼容性信息compatibility: { features: [iosUniversal], game_center: false, min_os_version: 15.0, supported_devices_count: 128 }其中min_os_version为最低系统版本要求supported_devices_count是当前所有支持设备的总数。该字段可能随 App Store 设备列表变化而调整不建议作为固定值缓存太久。常见错误排查实际接入时最常见的几类问题如下1. 返回鉴权失败或不识别 API Key检查请求头中的X-API-Key是否完整填写注意不要在值两侧误加空格。确认密钥使用的是当前环境的有效值。如果是在团队内共享脚本建议通过环境变量引用密钥避免硬编码到代码仓库。2. 返回 400 参数错误确认请求体是合法的 JSON不能有多余的尾逗号。app_id与url同时不传时无法定位目标应用。app_id只能包含数字不要传入带id前缀的内容。3. 返回区域不符合预期查看请求体中的country是否为两位小写国家码。如果传入了非法值接口会回退到cn此时返回的country字段会与预期不同。4. 限流触发接口 QPS 为 10循环调用时建议控制并发数。可以用信号量或令牌桶把请求速率压在阈值以下同时捕获限流响应后执行指数退避重试。工程化注意事项1. 参数校验前置在发起 HTTP 请求前先在本地对app_id和url做基础校验import re def normalize_app_id(value: str) - str: 提取 App 数字 ID兼容纯数字与商店链接。 value value.strip() if value.isdigit(): return value match re.search(r/id(\d), value) if match: return match.group(1) raise ValueError(f无法从入参中解析 app_id: {value})这样可以减少无效请求降低触发限流的概率。2. 缓存策略App 的基础信息名称、分类、开发者变化频率很低而评分、版本号、文件大小属于中频数据。建议把响应写入本地缓存设置 TTL 为 30 分钟到 1 小时。对于批量任务可先查缓存再请求网络。3. 字段落库前的类型处理JSON 响应中的数值类型需要特别留意app_id在返回体中是数字但在请求体中推荐使用字符串防止精度丢失。release_date是YYYY-MM-DD格式适合直接作为日期类型存储。rating.current_version_count可能为0不要直接做除法或写入非空约束。4. 网络层容错不要假设接口每次都会成功。建议实现连接超时3 秒。读取超时10 秒。重试策略对 429/5xx 做最多 3 次退避重试间隔为 1 秒、2 秒、4 秒。5. 使用请求 ID 做全链路追踪每次响应的request_id字段可以在出错时提供给服务端排查。建议在日志中打印请求参数、HTTP 状态码、耗时和request_id并将它们关联到业务单号。小结通过app_id或url两种入参配合country区域设置即可在一条请求内拿到 App Store 应用的版本、评分、用量说明、截图、兼容性等核心字段。对接过程本身不复杂真正的注意点集中在参数校验、限流控制和返回字段的缓存策略上。建议先以小批量脚本验证返回结构再逐步扩展到批量任务和监控系统。参考文档接口文档https://apizero.cn/aidocs/app-store原始文档https://apizero.cn/aidocs/app-store/raw.md
