获取历史数据
查询可追溯至 1999 年的每日价格，获取日期区间数据，比较两个日期之间的涨跌，获取 OHLC 日线数据，并利用 MetalAPI 历史数据分析黄金等品种的价格趋势。
可用的历史数据
MetalAPI 为每个品种每天存储一条日线数据（开盘价、最高价、最低价和收盘价）：
- 货币：自 1999 年起
- 贵金属、工业金属和能源：自 2000 年起
- 加密货币：自 2014 年起
2026 年 10 月之前的金属价格来源于近月期货，因此可能与同一天的现货价格略有差异。所有套餐都可以查询完整的历史数据，各套餐的区别仅在于单次区间请求可覆盖的天数。
单日数据
可将日期作为路径，也可使用带 date 参数的 /historical 端点或 /yesterday。响应包含当天的收盘价（UTC）。以 GET /api/v1/2026-10-01?currencies=XAU,XAG 为例：
{
"success": true,
"timestamp": 1790812800,
"historical": true,
"date": "2026-10-01",
"base": "USD",
"rates": {
"XAU": 0.0002583044893,
"USDXAU": 3871.4,
"XAG": 0.02097315436,
"USDXAG": 47.68
}
}使用 /timeframe 获取日期区间
/timeframe 为 start_date 与 end_date 之间的每一天返回一条数据，并以日期为键。以 GET /api/v1/timeframe?start_date=2026-10-19&end_date=2026-10-23¤cies=XAU 为例：
{
"success": true,
"timeframe": true,
"start_date": "2026-10-19",
"end_date": "2026-10-23",
"base": "USD",
"rates": {
"2026-10-19": { "XAU": 0.0002537298285, "USDXAU": 3941.2 },
"2026-10-20": { "XAU": 0.0002526049889, "USDXAU": 3958.75 },
"2026-10-21": { "XAU": 0.0002517369852, "USDXAU": 3972.4 },
"2026-10-22": { "XAU": 0.0002506642603, "USDXAU": 3989.4 },
"2026-10-23": { "XAU": 0.0002501319446, "USDXAU": 3997.89 }
}
}没有收盘价的日子（例如周末或市场假日）可能会缺失，不要假设每个自然日都有一条数据。/timeseries 是一个别名，它返回 "timeseries": true 而不是 "timeframe": true。
超出套餐允许范围的区间
单次请求的跨度在 Free 套餐中最多 30 天，在付费套餐中最多 365 天，更长的跨度将返回错误 207。请将长区间拆分为多个分段，每个分段发送一次请求：
const DAY = 86_400_000;
const MAX_DAYS = 365; // Free 套餐为 30
const iso = (d) => d.toISOString().slice(0, 10);
async function fetchRange(start, end, currencies) {
const rates = {};
let from = new Date(`${start}T00:00:00Z`);
const last = new Date(`${end}T00:00:00Z`);
while (from <= last) {
const to = new Date(Math.min(from.getTime() + MAX_DAYS * DAY, last.getTime()));
const params = new URLSearchParams({ start_date: iso(from), end_date: iso(to), currencies });
const res = await fetch(`https://metalapi.com/api/v1/timeframe?${params}`, {
headers: { "X-API-Key": process.env.METALAPI_KEY },
});
const data = await res.json();
if (!data.success) throw new Error(`${data.error.code}: ${data.error.info}`);
Object.assign(rates, data.rates);
from = new Date(to.getTime() + DAY);
}
return rates;
}
// 用 10 次请求获取十年的每日黄金价格
const gold = await fetchRange("2016-01-01", "2025-12-31", "XAU");两个日期之间的变化
/change 直接比较两天的数据，无需下载中间的整个区间。以 GET /api/v1/change?start_date=2026-09-30&end_date=2026-10-23¤cies=XAU 为例：
{
"success": true,
"change": true,
"start_date": "2026-09-30",
"end_date": "2026-10-23",
"base": "USD",
"rates": {
"XAU": { "start_rate": 0.0002591613539, "end_rate": 0.0002501319446, "change": -0.000009029409258, "change_pct": -3.48409 },
"USDXAU": { "start_rate": 3858.6, "end_rate": 3997.89, "change": 139.29, "change_pct": 3.60986 }
}
}价格变化请使用带前缀的键，例如 USDXAU。倒数键的变化方向与之相反。
每日 OHLC 数据
/ohlc 返回某一天的开盘价、最高价、最低价和收盘价，这正是绘制 K 线图和计算每日波动区间所需的数据。以 GET /api/v1/ohlc?date=2026-10-22¤cies=XAU 为例：
{
"success": true,
"ohlc": true,
"date": "2026-10-22",
"base": "USD",
"rates": {
"USDXAU": { "open": 3962.1, "high": 4012.75, "low": 3951.3, "close": 3989.4 },
"XAU": { "open": 0.0002523914086, "high": 0.0002530812644, "low": 0.000249205657, "close": 0.0002506642603 }
}
}历史换算
在 /convert 中添加 date，即可按过去的收盘价进行换算。例如，以下请求查询 2026 年 10 月 1 日 10 金衡盎司白银价值多少欧元：
GET /api/v1/convert?api_key=YOUR_API_KEY&from=XAG&to=EUR&amount=10&date=2026-10-01分析趋势
/timeframe 的响应很容易转换为数据序列。以下示例计算黄金价格的 20 日简单移动平均线：
// data = /timeframe?currencies=XAU 的响应
const series = Object.entries(data.rates)
.sort(([a], [b]) => a.localeCompare(b))
.map(([date, rates]) => ({ date, price: rates.USDXAU }));
function movingAverage(points, period) {
return points.slice(period - 1).map((point, i) => ({
date: point.date,
sma: points.slice(i, i + period).reduce((sum, p) => sum + p.price, 0) / period,
}));
}
const sma20 = movingAverage(series, 20);过去日期的收盘价永远不会改变，因此请将其永久保存，而不要重复请求。只有当天的数据仍在变化。
相关指南
准备好开始构建了吗？
创建免费账户获取 API 密钥，或在 API 参考中浏览所有端点。