<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API
provided by 极数本源 (https://apizero.cn). Prefer Authorization: Bearer.
Success is business code === 0 (do not treat HTTP 200 as success).
Generate working backend code; never put the API Key in a frontend or app.
API Key: https://apizero.cn/account/keys
Human docs: https://apizero.cn/aidocs/app-store -->

# App Store 查询

输入 App 数字 ID 或应用商店链接，查询 App Store 应用的名称、开发者、版本、评分、价格、截图、兼容性等完整信息。

支持全球多国家/地区（cn/us/jp 等）查询，可用于应用竞品分析、上架状态监控、ASO 运营、开发者工具集成等场景。数据实时聚合、结构清晰，数值/日期已标准化。完全免费。

## 平台约定

- 网关：`https://v1.apizero.cn`
- 鉴权：`Authorization: Bearer <API Key>`（兼容 X-API-Key 与 Query api_key / apikey / key）
- 回包：`{ code, msg, data, tips, request_id }`。成功看 `code === 0`

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `app-store` |
| 接口名称 | App Store 查询 |
| 接口地址 | `https://v1.apizero.cn/api/app-store` |
| 请求方法 | `POST` |
| 分类 | 开发工具 |
| 提供方 | 极数本源 |
| 计费模式 | 完全免费 |
| QPS 限制 | QPS 3 |
| 登录免费额度 | 1,000 次 |
| 匿名每日额度 | 500 次 |

### 会员每日额度

| 会员档位 | 每日免费 | QPS |
| --- | --- | --- |
| 黄金会员 | 50,000 次/日 | QPS 10 |
| 钻石会员 | 100,000 次/日 | QPS 30 |
| 企业会员 | 1,000,000 次/日 | QPS 120 |

## 2. 认证

登录用户每日 1000 次免费（QPS 10），匿名用户每日 500 次（QPS 5）。可选携带 API Key（Authorization: Bearer <key>）以享受更高额度。

获取 API Key：https://apizero.cn/account/keys

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `app_id` | `string` | 否 | App 数字 ID（与 url 二选一，优先） | `414478124` |
| `url` | `string` | 否 | 应用商店链接，自动提取数字 ID（与 app_id 二选一） | `https://apps.apple.com/cn/app/id414478124` |
| `country` | `string` | 否 | 两位国家/地区码，非法自动回退 cn | `cn` |

## 6. 响应字段

顶层固定 code / msg / data。下表一般是 data 内字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `app_id` | `number` | 应用数字 ID |
| `name` | `string` | 应用名称 |
| `bundle_id` | `string` | 应用包名（Bundle ID） |
| `developer` | `object` | 开发者信息（id/name/url/seller_name/seller_url） |
| `developer.name` | `string` | 名称 |
| `developer.seller_name` | `string` | seller_name |
| `developer.url` | `string` | 地址 |
| `icon` | `object` | 多尺寸图标（small 60 / medium 100 / large 512） |
| `icon.small` | `string` | small |
| `icon.medium` | `string` | medium |
| `icon.large` | `string` | large |
| `price` | `object` | 价格（amount/currency/formatted/is_free） |
| `price.amount` | `number` | amount |
| `price.currency` | `string` | currency |
| `price.formatted` | `string` | formatted |
| `price.is_free` | `boolean` | is_free |
| `version` | `object` | 版本信息（current/release_date/release_notes/days_since_update 距上次更新天数） |
| `version.current` | `string` | current |
| `version.release_date` | `string` | release_date |
| `version.release_notes` | `string` | release_notes |
| `version.days_since_update` | `number` | days_since_update |
| `rating` | `object` | 评分（average/count/当前版本评分） |
| `rating.average` | `number` | average |
| `rating.count` | `number` | count |
| `rating.current_version_average` | `number` | current_version_average |
| `rating.current_version_count` | `number` | current_version_count |
| `category` | `object` | 分类（primary 主分类 / all 全部分类） |
| `category.primary` | `string` | primary |
| `category.primary_id` | `number` | primary_id |
| `category.all` | `array` | all |
| `category.all[]` | `string` | category.all 的一项 |
| `compatibility` | `object` | 兼容性（min_os_version/supported_devices_count/features/game_center） |
| `compatibility.min_os_version` | `string` | min_os_version |
| `compatibility.supported_devices_count` | `number` | supported_devices_count |
| `compatibility.features` | `array` | features |
| `compatibility.features[]` | `string` | compatibility.features 的一项 |
| `compatibility.game_center` | `boolean` | game_center |
| `content_rating` | `string` | 内容分级（如 4+/12+/17+） |
| `advisories` | `array` | 内容提示（如含成人题材、内购等） |
| `advisories[]` | `string` | advisories 的一项 |
| `file_size` | `object` | 应用体积（bytes 字节 / display 可读） |
| `file_size.bytes` | `number` | bytes |
| `file_size.display` | `string` | display |
| `description` | `string` | 应用简介全文 |
| `screenshots` | `object` | 截图（iphone/ipad/appletv 数组） |
| `screenshots.iphone` | `array` | iphone |
| `screenshots.iphone[]` | `string` | screenshots.iphone 的一项 |
| `screenshots.ipad` | `array` | ipad |
| `screenshots.ipad[]` | `string` | screenshots.ipad 的一项 |
| `screenshots.appletv` | `array` | appletv |
| `screenshots.appletv[]` | `string` | screenshots.appletv 的一项 |
| `languages` | `array` | 支持语言（ISO 两位码） |
| `languages[]` | `string` | languages 的一项 |
| `language_count` | `number` | 支持语言数量 |
| `store_url` | `string` | 应用商店详情页链接 |
| `first_release_date` | `string` | 首次发布日期（YYYY-MM-DD） |
| `country` | `string` | 查询的国家/地区码（大写） |
| `tips` | `string` | 品牌提示（所有接口统一返回）：极数本源 · https://apizero.cn |

## 7. 响应示例

```json
{
  "code": 0,
  "msg": "成功",
  "data": {
    "app_id": 414478124,
    "name": "微信",
    "bundle_id": "com.tencent.xin",
    "developer": {
      "name": "WeChat",
      "seller_name": "Tencent Technology (Shenzhen) Company Limited",
      "url": "https://.../developer/..."
    },
    "icon": {
      "small": "https://.../60x60.jpg",
      "medium": "https://.../100x100.jpg",
      "large": "https://.../512x512.jpg"
    },
    "price": {
      "amount": 0,
      "currency": "CNY",
      "formatted": "免费",
      "is_free": true
    },
    "version": {
      "current": "8.0.75",
      "release_date": "2026-06-14",
      "release_notes": "本次更新：解决了一些已知问题。",
      "days_since_update": 17
    },
    "rating": {
      "average": 4.15,
      "count": 8010302,
      "current_version_average": 4.15,
      "current_version_count": 8010302
    },
    "category": {
      "primary": "Social Networking",
      "primary_id": 6005,
      "all": [
        "社交",
        "效率"
      ]
    },
    "compatibility": {
      "min_os_version": "15.0",
      "supported_devices_count": 128,
      "features": [
        "iosUniversal"
      ],
      "game_center": false
    },
    "content_rating": "12+",
    "advisories": [],
    "file_size": {
      "bytes": 851213312,
      "display": "811.78 MB"
    },
    "description": "微信是一个生活方式……",
    "screenshots": {
      "iphone": [
        "https://.../1.jpg"
      ],
      "ipad": [],
      "appletv": []
    },
    "languages": [
      "ZH",
      "EN",
      "JA"
    ],
    "language_count": 25,
    "store_url": "https://apps.apple.com/cn/app/id414478124",
    "first_release_date": "2011-01-21",
    "country": "CN"
  },
  "request_id": "a1b2c3d4",
  "tips": "极数本源 · https://apizero.cn"
}
```


## 5. 请求示例

Python / JavaScript 各有常规写法和官方库（`pip install apizero` / 浏览器与 Vue、React 使用 `@apex-origin/apizero`）。成功后先判断 `code == 0` 再读 `data`。

### cURL

```bash
curl -sS -X POST "https://v1.apizero.cn/api/app-store" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "app_id": "414478124",
  "url": "https://apps.apple.com/cn/app/id414478124",
  "country": "cn"
}'
```

### Python

```python
# 服务端常规写法：标准库 urllib，不用 pip
import json
import ssl
import urllib.error
import urllib.request

key = "YOUR_API_KEY"

url = "https://v1.apizero.cn/api/app-store"
payload = {
    "app_id": 414478124,
    "url": "https://apps.apple.com/cn/app/id414478124",
    "country": "cn",
}
req = urllib.request.Request(
    url,
    data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + key,
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(
        req, timeout=20, context=ssl.create_default_context()
    ) as resp:
        raw = resp.read().decode("utf-8")
except urllib.error.HTTPError as e:
    raw = e.read().decode("utf-8", "replace")
body = json.loads(raw)
print(json.dumps(body, ensure_ascii=False, indent=2))
if body.get("code") == 0:
    print(body.get("data"))
```

### Python 官方库

```python
# 官方库（服务端）：先执行一次 pip install apizero
import apizero

key = "YOUR_API_KEY"
client = apizero.key(key)
r = client.app_store(
    app_id=414478124,
    url="https://apps.apple.com/cn/app/id414478124",
    country="cn",
)
if not r.ok:
    raise RuntimeError(r.msg)
print(r.ok, r.code)
print(r.json)
```

### JavaScript

```javascript
// 服务端 Node 18+ fetch
const key = "YOUR_API_KEY";
const url = "https://v1.apizero.cn/api/app-store";
const res = await fetch(url, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${key}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "app_id": 414478124,
  "url": "https://apps.apple.com/cn/app/id414478124",
  "country": "cn",
}),
});
const body = await res.json();
console.log(body);
if (body.code === 0) console.log(body.data);
```

### JavaScript 官方库（Node）

```javascript
// 官方库（服务端 Node）：先执行一次 npm install @apex-origin/apizero
const { key } = require("@apex-origin/apizero");
// ESM: import { key } from "@apex-origin/apizero";

const apiKey = "YOUR_API_KEY";
const client = key(apiKey);
const r = await client.app_store({
  "app_id": 414478124,
  "url": "https://apps.apple.com/cn/app/id414478124",
  "country": "cn",
});
if (!r.ok) throw new Error(r.msg);
console.log(r.ok, r.code);
console.log(r.json);
```

### Go

```go
// 服务端常规写法：net/http
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	key := "YOUR_API_KEY"

	url := "https://v1.apizero.cn/api/app-store"
	payload, err := json.Marshal(map[string]any{
		"app_id": "414478124",
		"url": "https://apps.apple.com/cn/app/id414478124",
		"country": "cn",
	})
	if err != nil {
		panic(err)
	}
	req, err := http.NewRequest(http.MethodPost, url, bytes.NewReader(payload))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+key)
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	raw, _ := io.ReadAll(resp.Body)
	fmt.Println(string(raw))
}
```

### Java

```java
// 服务端常规写法：Java 11+ HttpClient
// Jackson：com.fasterxml.jackson.databind.ObjectMapper
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

import java.net.URI;
import java.util.LinkedHashMap;
import java.util.Map;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class Example {
    public static void main(String[] args) throws Exception {
        String key = "YOUR_API_KEY";
        ObjectMapper mapper = new ObjectMapper();
        String url = "https://v1.apizero.cn/api/app-store";

        Map<String, Object> payload = new LinkedHashMap<>();
        payload.put("app_id", "414478124");
        payload.put("url", "https://apps.apple.com/cn/app/id414478124");
        payload.put("country", "cn");
        String json = mapper.writeValueAsString(payload);

        HttpClient client = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(10))
                .build();
        HttpRequest req = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("Authorization", "Bearer " + key)
                .timeout(Duration.ofSeconds(20))
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(json))
                .build();
        HttpResponse<String> resp = client.send(req, HttpResponse.BodyHandlers.ofString());
        JsonNode body = mapper.readTree(resp.body());
        System.out.println(resp.body());
        if (body.path("code").asInt() == 0) {
            System.out.println(body.path("data"));
        }
    }
}
```

### PHP

```php
<?php
// 服务端常规写法：curl，强制 TLS 1.2
$key = "YOUR_API_KEY";

$ch = curl_init("https://v1.apizero.cn/api/app-store");
$opts = [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 20,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.$key,
        'Content-Type: application/json',
    ],
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode([
    "app_id" => "414478124",
    "url" => "https://apps.apple.com/cn/app/id414478124",
    "country" => "cn",
], JSON_UNESCAPED_UNICODE),
];
if (defined('CURL_SSLVERSION_TLSv1_2')) {
    $opts[CURLOPT_SSLVERSION] = CURL_SSLVERSION_TLSv1_2;
}
curl_setopt_array($ch, $opts);
$raw = curl_exec($ch);
if ($raw === false) {
    fwrite(STDERR, 'cURL Error: '.curl_error($ch).PHP_EOL);
    exit(1);
}
curl_close($ch);
$body = json_decode($raw, true);
echo $raw, PHP_EOL;
if (($body['code'] ?? null) === 0) {
    echo json_encode($body['data'] ?? null, JSON_UNESCAPED_UNICODE), PHP_EOL;
}
```

### Rust

```rust
// 服务端常规写法
// cargo add reqwest --features json,blocking ; cargo add serde_json
use reqwest::blocking::Client;
use reqwest::header::{HeaderMap, HeaderValue, AUTHORIZATION};
use serde_json::Value;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let key = "YOUR_API_KEY";

    let url = "https://v1.apizero.cn/api/app-store";
    let mut headers = HeaderMap::new();
    headers.insert(
        AUTHORIZATION,
        HeaderValue::from_str(&format!("Bearer {key}"))?,
    );
    headers.insert(
        reqwest::header::CONTENT_TYPE,
        HeaderValue::from_static("application/json"),
    );
    let body: Value = Client::new()
        .post(url)
        .json(&serde_json::json!({
        "app_id": "414478124",
        "url": "https://apps.apple.com/cn/app/id414478124",
        "country": "cn",
    }))
        .headers(headers)
        .timeout(std::time::Duration::from_secs(20))
        .send()?
        .json()?;
    println!("{}", serde_json::to_string_pretty(&body)?);
    Ok(())
}
```

## 8. 错误码

先看业务 code。HTTP 也可能不是 200。

| 业务码 | HTTP | 说明 |
| --- | --- | --- |
| 0 | 200 | 成功 |
| 4000 | 400 | 参数错误 |
| 4011 | 401 | API Key 无效 |
| 4013 | 403 | API Key 已暂停 |
| 4014 | 403 | 当前 IP 不在 Key 白名单 |
| 4015 | 401 | 此接口需要 API Key |
| 4022 | 402 | 余额不足 |
| 4029 | 429 | 调用过快（QPS） |
| 4030 | 429 | 今日免费额度已用完 |
| 4040 | 503 | 接口已下线 |
| 4041 | 404 | 接口不存在 |
| 5000 | 500 | 服务器内部错误 |
| 5020 | 502 | 上游暂时不可用 |
| 5021 | 502 | 上游返回格式异常 |
| 5030 | 502 | 暂无可用节点 |


## 9. 变更日志

- **v1.0** (2026-07-01): 首次上线：支持 app_id/链接查询，返回名称/开发者/版本/评分/价格/截图/兼容性等完整信息，支持多国家/地区。