iTunes Lookup API 规则具体（查包名）

苹果 iTunes Lookup API（也常称 App Store Lookup API）是苹果官方提供的公开 REST 接口，用于查询 App Store 上已上架应用 / 内购商品 / 艺人等内容的基础信息，核心规则可总结为「参数规范、返回逻辑、使用限制」三部分，以下是最核心、实用的规则：

一、核心基础规则

规则项	具体说明
接口基础 URL	通用地址：`https://itunes.apple.com/lookup`（HTTPS 强制，HTTP 无法访问）
请求方式	仅支持 `GET` 请求（无需 POST，参数直接拼在 URL 后）
返回格式	默认 JSON（可通过`output=json/xml`指定，推荐 JSON）
语言 / 地区	可通过`lang`（语言，如`zh_CN`）、`country`（地区，如`CN`）指定返回语言 / 地区适配的信息（比如价格、应用描述）

二、关键参数规则（查询 App 核心用）

这是最容易出错的部分，也是你之前查询失败的核心原因：

参数名	作用	取值要求	示例（正确 / 错误）
`id`	查询 App 的Apple ID（苹果给每个上架 App 分配的唯一纯数字 ID）	必须是纯数字（如 902861234），不能填 bundle_id（字符串包名）	正确：`id=902861234`错误：`id=com.**.ios`
`bundleId`	查询 App 的Bundle ID（包名，如 com.xxx.xxx）	必须是完整、准确的 bundle_id 字符串，仅支持上架 App 的包名	正确：`bundleId=com..ios`错误：`bundleId=`（不完整）
`country`	指定查询的 App Store 地区（不同地区上架状态 / 价格可能不同）	两位 ISO 国家 / 地区码（如`CN`中国、`US`美国、`HK`中国香港）	`country=CN`
`limit`	返回结果数量（仅批量查询时有用，单 App 查询默认 1）	数字，最大 50	`limit=10`

重要补充：参数优先级

同时传id和bundleId时，id优先级更高（接口优先按 Apple ID 查询）；
仅查单个 App 时，推荐用bundleId（包名固定，Apple ID 可能记混）。

三、返回结果规则

场景	返回结果特征
查询到匹配上架 App	`resultCount=1`，`results`数组内包含 App 的详细信息（名称、开发者、bundle_id、价格、评分等）
未查询到匹配 App	`resultCount=0`，`results`为空数组（如你之前查`com.**.ios`的结果）
参数格式错误	返回`errorMessage`（如你之前遇到的`Invalid value(s) for key(s): [itunesId]`）

常见返回字段（查 App 时核心关注）：

复制代码

{
  "resultCount": 1,
  "results": [
    {
      "bundleId": "com.xxx.xxx", // 包名
      "trackId": 902861234, // Apple ID（纯数字）
      "trackName": "App名称", // App显示名
      "sellerName": "开发者显示名", // 非真实身份，仅展示用
      "country": "CN", // 上架地区
      "price": 0, // 价格（免费为0）
      "version": "722", // 版本号
      "releaseDate": "2020-07-21T13:18:24Z" // 上架时间
    }
  ]
}

四、使用限制规则（避免接口调用失败）

频率限制：苹果未公开具体阈值，但短时间内大量调用（如每秒数十次）会触发 IP 封禁，建议单 IP 每秒调用≤5 次；
查询范围 ：仅能查已上架 App Store 的正式包，未上架的测试包、沙盒环境的 App 均无法查询；
信息权限：仅返回公开信息（开发者显示名、App 基本信息），无法获取开发者真实身份、注册邮箱、证书信息等隐私数据；
跨地区限制 ：若 App 仅在某地区上架（如仅美国），用country=CN查询会返回resultCount=0。

五、正确查询示例

正确用法（查 bundle_id）：

复制代码

https://itunes.apple.com/lookup?bundleId=com.**.ios&country=CN

→ 结果：resultCount=0（说明该包未上架）。

正确用法（查已知 Apple ID）：

复制代码

https://itunes.apple.com/lookup?id=12**&country=CN

→ 结果：返回该 Apple ID 对应的 App 信息（若上架）。

总结

iTunes Lookup API 核心规则可记为：

查包名用bundleId参数，查数字 Apple ID 用id参数，别混用；
仅能查上架 App，未上架测试包返回空；
仅返回公开信息，隐私数据（如开发者真实身份）查不到；
按频率限制调用，避免 IP 封禁。