黄金价格API怎么选沪金银行贵金属与历史行情如何分流
黄金价格 API 不能只按“金价”两个字接入：展示上海黄金、期货、香港黄金、银行贵金属、伦敦金、金店报价或历史行情，对应不同接口和字段。先确定市场、品种和时间范围，再设计统一行情模型。
为什么同一个金价页面会有多个接口
“黄金价格”可能指交易市场最新价、银行买卖价、金店每克报价，也可能指某个品种一段时间内的历史行情。这些数据的主体、单位、更新时间和可用字段不同，强行合并会让用户误把银行卖出价当成交易所最新价，或把金店饰品价当成投资金价格。
极速数据的黄金价格 API 文档把相关能力拆成多个端点：
| 业务问题 | 接口 | 关键字段 |
|---|---|---|
| 查看上海黄金交易相关品种 | /gold/shgold | type、typename、price、openingprice、maxprice、minprice、updatetime |
| 查看上海黄金期货行情 | /gold/shfutures | price、buyprice、sellprice、tradeamount、holdamount |
| 查看香港黄金 | /gold/hkgold | buyprice、sellprice、openingprice、closingprice、updatetime |
| 查看银行账户贵金属 | /gold/bank | typename、midprice、buyprice、sellprice、updatetime |
| 查看伦敦金、银相关行情 | /gold/london | price、changepercent、openingprice、lastclosingprice、updatetime |
| 查看金店零售报价 | /gold/storegold | store_name、date、gold、goldbar、jewelry、solid_gold |
| 查询一段时间的历史行情 | /gold/history | market、type、date、开高低收、涨跌和成交量 |
选择接口的第一步应是写出页面标题和数据口径。例如，“某银行账户黄金买入价”应进入银行接口，“某金店今日足金价格”应进入金店接口，“伦敦金最近十日走势”则应进入历史查询，而不是先抓取一个字段名叫 price 的值再猜它代表什么。
实时类接口怎么接
上海黄金、上海期货、香港黄金、银行账户黄金和伦敦金接口当前都使用 GET，并且页面未列出额外业务请求参数，只需要服务端 APPKEY。以下请求仅表示结构，没有执行真实行情查询：
GET https://api.jisuapi.com/gold/shgold?appkey=YOUR_APPKEY
GET https://api.jisuapi.com/gold/bank?appkey=YOUR_APPKEY
GET https://api.jisuapi.com/gold/london?appkey=YOUR_APPKEY
接入时不要只落库 price。不同端点的核心价格字段并不相同：银行接口以 midprice、buyprice、sellprice 表达中间价和买卖价；上海黄金与伦敦金包含 price；香港黄金则同时给出买价、卖价和收市价。统一模型至少需要保存：
source_market 数据来源市场或接口类别
instrument_code 品种代号
instrument_name 品种名称
price_type latest / buy / sell / mid / close
price_value 转换后的十进制定点数
quote_unit 元/克、港币/两或对应市场报价单位
source_time 接口返回的更新时间
fetched_at 本系统请求时间
raw_payload 可选的原始响应或归档引用
price_type 和 quote_unit 是业务系统自建字段，不是所有端点都会直接返回这两个字段。它们用于防止不同价格语义或单位落进同一列后失去来源。金额和报价不适合使用二进制浮点数直接累计，入库前应先处理空值，再使用定点小数，并保留原始字符串供追溯。
金店报价的 date 参数怎么处理
金店报价接口地址为 https://api.jisuapi.com/gold/storegold。文档显示 date 为非必填字符串，仅支持最近七天；不传时默认当天，更新时间不固定。
GET https://api.jisuapi.com/gold/storegold?appkey=YOUR_APPKEY&date=YYYY-MM-DD
返回数据按 store_name 区分金店，可能包含 gold、platinum、goldbar、jewelry 和 solid_gold 等字段。官方示例中部分字段为 null，因此前端不能假设每家金店每天都有全部品类报价。正确做法是按“金店 + 日期 + 品类”判断值是否存在，没有值时显示暂无报价，而不是自动复制上一条或用 0 替代。
页面还列出了香港报价字段，并明确标注港币/两；内地黄金、金条、饰品和足金字段则标注元/克。单位属于数据含义的一部分，必须与数值同时保存、同时展示，不能只比较数字大小。
历史行情查询怎么限制范围
历史接口 https://api.jisuapi.com/gold/history 支持 GET、POST，market、startdate、enddate 和 type 都是必填项。文档列出的市场值包括伦敦 london、纽约 ny、TD td 和期货 futures；type 用于指定具体品种。
GET https://api.jisuapi.com/gold/history?appkey=YOUR_APPKEY&market=london&type=xau&startdate=YYYY-MM-DD&enddate=YYYY-MM-DD
返回结构包含查询市场、品种、起止日期、总数，以及逐日的 openingprice、maxprice、minprice、price、lastclosingprice、change_amount、changepercent 和 tradeamount 等字段。
在业务层应先校验开始日期不晚于结束日期，并限制单次跨度，避免一个图表请求反复拉取过大区间。历史数据适合按市场、品种和日期做唯一键；重新同步时记录覆盖版本或更新时间，不要无痕覆盖已经用于报表的数据。
返回状态和更新时点怎么判断
黄金文档列出的接口业务错误码 201 表示没有信息；系统错误码 101、102、103、104 分别表示 APPKEY 不存在、已过期、无请求权限和超过次数限制。后端应依次判断 HTTP 状态、JSON 解析、业务状态和结果集合，不能因为请求返回 200 就直接渲染价格。
行情页面尤其要区分两个时间：
updatetime或历史记录的date：数据来源所表达的时间；fetched_at：本系统获得响应的时间。
若接口响应成功但 updatetime 没有推进，应继续展示来源时间并提示数据时点，而不是把本次请求时间伪装成行情更新时间。缓存也应按具体市场和端点设置，不能用一套固定时间覆盖所有数据。
安全与业务边界
APPKEY 只保存在服务端，通过环境变量或密钥管理服务注入；浏览器和移动端访问自有后端，再由后端代理查询。日志中记录端点、耗时、业务状态和数据时间即可，不记录完整 APPKEY。
黄金行情接口可以为报价展示、数据看板、行情分析和历史图表提供结构化数据，但接口返回不等于交易成交价，也不构成投资建议。涉及交易、结算、估值或合规披露时，仍需确认市场口径、单位、授权和业务规则，不能仅凭一个最新价字段自动下单或生成保证性结论。
截至 2026 年 8 月 11 日，上述端点与字段来自极速数据当前黄金价格 API 文档。上线前应重新核对权限、配额、数据更新和授权条件。
总结
黄金价格 API 的正确接法是先分市场和用途，再分端点、价格类型与时间口径。把来源市场、品种、价格语义、单位、数据时间和拉取时间一起保存，才能避免不同“金价”在展示、比较和历史分析中被错误混用。
