适用场景与接口能力在金融资讯应用、电商计价系统或个人投资分析工具中实时获取黄金用量说明是一项常见需求。黄金用量说明数据通常分为国际贵金属报价、国内现货价以及各大品牌金店的零售价来源分散、格式不统一。本文介绍的聚合查询API一次性提供上述三个维度的数据开发者只需一次请求即可获得完整金价视图。接口核心能力国际报价涵盖国际金价、国际银价、国际铂金、国际钯金每项含最新价、涨跌额、涨跌幅、最高价、最低价及报价时间。国内报价包括国内金价、国内银价、投资金条、黄金回收价、铂金回收价、18K金回收价、钯金回收价。品牌金店覆盖周大福、周生生、六福、老凤祥、老庙、中国黄金、周六福、菜百、明牌珠宝、潮宏基等17家头部品牌的黄金、铂金、金条当日售价元/克。通过可选的type参数开发者可以按需获取全部数据或仅拉取某一类别减少不必要的数据传输。请求参数与鉴权接口信息属性值请求方法GET端点 URLhttps://v1.apizero.cn/api/goldQPS 限制5 / 秒数据缓存10 分钟Query 参数参数名必需类型说明示例type否string返回类型all全部默认、brand品牌金店、international国际黄金、domestic国内黄金all鉴权方式接口支持两种鉴权模式匿名调用无需提供任何认证头但存在每日调用次数上限具体配额以官方文档为准。API Key 鉴权在 HTTP 头中传入X-API-Key或Authorization: Bearer sk_live_xxx可获取更高的调用额度。建议生产环境使用 API Key。注意原始文档 curl 示例使用X-API-Key头实际以官方最新文档为准两种方式均可在部分版本中生效。可复制的 curl 请求示例以下示例展示如何通过带 API Key 的 curl 获取全部金价数据将$APIZERO_API_KEY替换为真实密钥curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/gold?typeall若不使用 API Key可省略-H部分curl -sS -X GET https://v1.apizero.cn/api/gold?typeall若只需品牌金店数据curl -sS \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/gold?typebrandPython 代码接入实践以下 Python 脚本封装了请求与解析逻辑包含基本的超时处理和返回值检查。使用requests库需预先安装pip install requests。import requests import json import time def fetch_gold_prices(api_key: str None, request_type: str all) - dict: 查询黄金价格聚合数据。 :param api_key: API Key若为 None 则匿名调用 :param request_type: 数据类型可选 all/brand/international/domestic :return: 解析后的 JSON 字典 url https://v1.apizero.cn/api/gold params {type: request_type} headers {} if api_key: headers[X-API-Key] api_key try: # 设置超时 10 秒避免长时间阻塞 resp requests.get(url, paramsparams, headersheaders, timeout10) resp.raise_for_status() # 非 2xx 状态码抛出异常 data resp.json() return data except requests.exceptions.RequestException as e: raise RuntimeError(f请求失败: {e}) def parse_gold_response(response: dict): 提取主要字段并打印。 if response.get(code) ! 0: print(f接口返回异常: {response.get(msg)}) return data response[data] print(f数据来源: {data.get(source)}) print(f更新时间: {data.get(update_time)}) # 国际报价 for item in data.get(international, []): print(f[国际] {item[name]}: {item[price]} 涨跌 {item[change]} ({item[percent]})) # 国内报价 for item in data.get(domestic, []): print(f[国内] {item[name]}: {item[price]} 涨跌 {item[change]} ({item[percent]})) # 品牌金店 for item in data.get(brand, []): print(f[品牌] {item[brand]}: 金价 {item[gold_price]}, 铂金 {item[pt_price]}, 金条 {item[bar_price]}) if __name__ __main__: # 请替换为你的 API Key或设为 None 以匿名方式调用 API_KEY sk_live_your_key_here try: raw fetch_gold_prices(api_keyAPI_KEY, request_typeall) parse_gold_response(raw) except Exception as e: print(f发生错误: {e})该脚本在__main__中演示了完整流程并包含了异常捕获可直接在本地运行验证。返回值结构与字段解读成功响应的 HTTP 状态码为 200Content-Type 为application/json。整体结构如下{ code: 0, msg: 成功, request_id: abc123def456, data: { source: huangjinjiage.cn, type: all, update_time: 2026-05-06 15:30:00, brand: [...], domestic: [...], international: [...] } }顶层字段字段类型说明codeint状态码0 表示成功非 0 表示错误msgstring状态描述request_idstring请求唯一标识可用于排查问题dataobject业务数据主体data内部字段source(string): 数据来源固定为huangjinjiage.cn。type(string): 请求时指定的type参数值。update_time(string): 数据最新更新时间格式YYYY-MM-DD HH:mm:ss。international(array): 国际贵金属报价数组每个元素包含name: 名称如“国际金价”price: 最新价美元/盎司change: 涨跌额percent: 涨跌幅字符串含百分号high: 当日最高价low: 当日最低价time: 报价日期如2026-5-6domestic(array): 国内金银及回收报价字段与international类似但用量说明单位为元/克。brand(array): 品牌金店数据每个元素包含brand: 品牌名称如“内地周大福”gold_price: 黄金售价元/克pt_price: 铂金售价元/克可能为 - 表示未提供bar_price: 金条售价元/克time: 报价日期unit: 用量说明单位固定为“元/克”常见错误与排查HTTP 状态码code值可能原因处理建议200非 0API Key 无效或过期检查密钥是否准确或重新生成2001xxx参数错误如type值不合法确认type为all/brand/international/domestic400-Query 参数格式有误检查 URL 编码避免中文空格429-请求频率超过 QPS5/s添加调用间隔或使用 API Key 提升配额5xx-服务端异常等待后重试若持续请联系技术支持网络层面建议为 API 调用配置合理的超时如 10 秒并针对ConnectionError或Timeout实现指数退避重试。工程化注意事项1. 缓存策略接口已内置 10 分钟数据缓存但客户端仍建议按业务场景增设本地缓存避免每次页面刷新都触发网络请求。例如对于展示金价的 web 页面可在内存或 Redis 中缓存 5–10 分钟并在后台异步更新。2. 数据类型与精度返回的用量说明字段均为字符串解析时注意转换为数值类型如float时可能存在的精度问题。前端显示时保留合理小数位数。品牌表中的pt_price可能为-代码中应做特殊处理。3. 错误重试对于网络抖动的瞬态错误采用以下策略重试 3 次间隔分别为 1s、2s、4s指数退避。4. 编码兼容数据源原为 GBK 编码接口已修复乱码问题但若自行扩展解析注意响应 Content-Type 中的 charset 声明。参考文档黄金用量说明查询 API 官方文档原始接口说明Markdown
