<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API endpoint
provided by 极数本源 (https://apizero.cn). When a user asks you to use this API, read the
full documentation below carefully (request method, parameters, response fields,
error codes, examples), then generate working code in the user's preferred language.
API Key acquisition: https://apizero.cn/account/keys -->

# 黄金价格查询

> 实时黄金价格聚合查询，一次返回三大维度的金价数据：

• 国际黄金报价（4 项）：国际金价、国际铂金、国际银价、国际钯金，含最新价 / 涨跌额 / 涨跌幅 / 最高价 / 最低价 / 报价时间

• 国内黄金报价（7 项）：国内金价、国内银价、投资金条、黄金回收价格、铂金回收价格、18K 金回收价格、钯金回收价格

• 十大品牌金店金价（17 家）：内地周大福、周生生、六福珠宝、老凤祥、老庙黄金、中国黄金、周六福、菜百、明牌珠宝、潮宏基等十大品牌的当日黄金 / 铂金 / 金条价格（元/克）

通过参数 type 可只取某一类（all=全部，brand=品牌金店，international=国际，domestic=国内）。

基于 huangjinjiage.cn 数据源，已修复源码 GBK 编码乱码 bug，内建 10 分钟缓存。

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `gold` |
| 接口名称 | 黄金价格查询 |
| 接口地址 | `https://v1.apizero.cn/api/gold` |
| 请求方法 | `GET` |
| 分类 | finance |
| 提供方 | 极数本源 |
| 计费模式 | 免费试用 |
| 单次消耗 | 0 积分 |
| 起步价 | — |
| QPS 限制 | 5 req/s |
| 每日免费额度 | 200 次（已认证用户） |
| 匿名每日额度 | 50 次（无 API Key） |
| VIP 免费 | 否 |
| 调用总次数 | undefined |

## 2. 认证

匿名每日 50 次、QPS 2；登录用户每日 200 次、QPS 5（全部免费）。已内建 10 分钟缓存。

获取 API Key：登录 `https://apizero.cn/account/keys` 申请。

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `type` | `string` | 否 | 返回类型：all=全部（默认）/ brand=品牌金店 / international=国际黄金 / domestic=国内黄金 | `all` |

## 4. 请求头

| Header | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `Authorization` | `string` | 否 | API Key 鉴权头，格式 Bearer sk_live_xxx；匿名调用时可省略（每日 50 次免费） | `Bearer sk_live_xxxxxxxxxxxxxx` |

## 5. 请求示例 (cURL)

```bash
curl "https://v1.apizero.cn/api/gold?type=all&key=YOUR_API_KEY"
```

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `update_time` | `string` | 本次缓存更新时间（YYYY-MM-DD HH:mm:ss） | — |
| `source` | `string` | 数据源标识：huangjinjiage.cn | — |
| `type` | `string` | 返回类型，回传请求中的 type 值 | — |
| `international` | `array` | 国际黄金价格列表（4 项） | — |
| `international[].name` | `string` | 品种名（国际金价/国际铂金/国际银价/国际钯金） | — |
| `international[].price` | `string` | 最新价 | — |
| `international[].change` | `string` | 涨跌额 | — |
| `international[].percent` | `string` | 涨跌幅（含 %） | — |
| `international[].high` | `string` | 日内最高价 | — |
| `international[].low` | `string` | 日内最低价 | — |
| `international[].time` | `string` | 报价时间 | — |
| `domestic` | `array` | 国内黄金价格列表（7 项），结构同 international[] | — |
| `brand` | `array` | 十大品牌金店列表（17 家） | — |
| `brand[].brand` | `string` | 品牌名称（如 内地周大福） | — |
| `brand[].gold_price` | `string` | 黄金价格（元/克） | — |
| `brand[].pt_price` | `string` | 铂金价格（元/克），无数据时为 - | — |
| `brand[].bar_price` | `string` | 金条价格（元/克） | — |
| `brand[].unit` | `string` | 价格单位，固定 元/克 | — |
| `brand[].time` | `string` | 报价时间 | — |

## 7. 响应示例

```json
{
    "code": 0,
    "msg": "成功",
    "data": {
        "update_time": "2026-05-06 15:30:00",
        "source": "huangjinjiage.cn",
        "type": "all",
        "international": [
            {
                "name": "国际金价",
                "price": "4647.3",
                "change": "7.19",
                "percent": "0.39%",
                "high": "1828.34",
                "low": "1815.50",
                "time": "2026-5-6"
            },
            {
                "name": "国际银价",
                "price": "75.28",
                "change": "0.21",
                "percent": "0.91%",
                "high": "23.24",
                "low": "22.78",
                "time": "2026-5-6"
            }
        ],
        "domestic": [
            {
                "name": "国内金价",
                "price": "1022.9",
                "change": "2.08",
                "percent": "0.56%",
                "high": "375",
                "low": "372.76",
                "time": "2026-5-6"
            }
        ],
        "brand": [
            {
                "brand": "内地周大福",
                "gold_price": "1413",
                "pt_price": "-",
                "bar_price": "1239",
                "unit": "元\/克",
                "time": "2026-5-6"
            }
        ]
    },
    "request_id": "abc123def456"
}
```

## 8. 错误码

| code | status | 说明 |
| --- | --- | --- |
| `4000` | `—` | 参数错误：type 非法（仅支持 all/brand/international/domestic） |
| `4015` | `—` | 匿名调用每日额度用完，需要 API Key |
| `4029` | `—` | QPS 超限 |
| `4030` | `—` | 今日额度用完 |
| `5020` | `—` | 上游服务不可用 / HTTP 拉取失败 |
| `5021` | `—` | 上游 HTML 解析失败（页面结构可能已改版） |

## 9. 变更日志

- **1.0.0** (2026-05-06)
  - 首次上线，聚合国际黄金/国内黄金/十大品牌金店三类金价数据
  - 修复源码 GBK 编码 bug（源码用 <?xml encoding="utf-8" ?> 强制 UTF-8 解析 GBK 内容会导致中文乱码）
  - 缓存改用 Redis（10 分钟），不再依赖文件系统
  - 解析失败容错（三个表都空时返回 5021 而非空 200）
  - 支持 type 参数按需返回单类数据（节省带宽）

---

**极数本源** · 全部 API: `https://apizero.cn/aidocs` · 人类版本：`https://apizero.cn/marketplace/gold`

Source: `https://apizero.cn/aidocs/gold/raw.md`
Last updated: 2026-05-11T16:15:07+08:00