通过 API 获取铜、铝、锌和原油价格：开发者指南

工业金属与能源品种

贵金属往往占据新闻头条，但许多企业更关心铜、铝、钢材和燃料。它们决定着电缆和电机、易拉罐和汽车车身、建筑钢材以及每一辆运货卡车的成本。MetalAPI 在黄金和白银之外，还提供四种工业金属和五种能源合约的报价，使用相同的端点和相同的响应格式。

品种页面列出了这些品种及其实时价格，GET /api/v1/symbols?details=1 则以 JSON 格式返回每个品种的类别和单位。该调用免费，不计入您的配额。

市场惯用单位与 API 的统一计价

这些市场各有各的惯例。在纽约，铜按磅交易；铝和锌按公吨交易，美国钢材按短吨，原油按桶，天然气按百万英热单位（MMBtu），成品油按加仑。一旦混淆，数字就会相差一千倍甚至更多。

MetalAPI 对金属统一计价，而能源保留其合约单位：

• 所有金属（包括贵金属和工业金属）默认均以金衡盎司计价。这样所有金属都可以直接比较，并且只需一个参数就能换算任意金属。没有人会按金衡盎司交易铜，因此对于工业金属，您几乎总是需要传入 unit。
• 能源按合约单位计价：WTI 和 BRENT 按桶，NATURALGAS 按 MMBtu，GASOLINE 和 HEATINGOIL 按美制加仑。unit 参数不适用于能源、货币和加密货币。

unit 可选 troy_oz（默认）、gram、kilogram、ounce、pound、metric_ton 和 short_ton。按各金属市场惯用的单位获取价格：

# 铜，美元/磅
curl "https://metalapi.com/api/v1/latest?currencies=XCU&unit=pound" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 铝和锌，美元/公吨
curl "https://metalapi.com/api/v1/latest?currencies=ALU,ZNC&unit=metric_ton" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 热轧卷板钢材，美元/短吨
curl "https://metalapi.com/api/v1/latest?currencies=HRC&unit=short_ton" \
  -H "Authorization: Bearer YOUR_API_KEY"

使用非默认单位时，响应会通过 unit 字段注明。您需要的价格是带基础货币前缀的键（USDXCU）；不带前缀的 XCU 键是它的倒数，保留它是为了兼容较早的集成：

{
  "success": true,
  "timestamp": 1792834892,
  "date": "2026-10-24",
  "base": "USD",
  "unit": "pound",
  "rates": {
    "XCU": 0.2222222222,
    "USDXCU": 4.5
  }
}

基于期货的价格与“近月”的含义

现货黄金在场外市场全天候交易，而工业金属和能源的价格在期货交易所最为透明。MetalAPI 从 COMEX 和 NYMEX（均隶属于芝商所 CME Group）以及 ICE 获取这些价格。期货合约是一种标准化协议，约定在特定月份按约定价格买入或卖出约定数量的商品。每个交割月份都是一份独立的合约，有各自的价格。

近月（front month）是仍在交易的最近交割月份。连续的近月序列会跟踪该合约，直到其临近到期，然后切换（即移仓，roll）到下一份合约。对开发者而言，有三点影响值得注意：

• 移仓跳变。在移仓日，序列可能出现跳变，这并非因为市场波动，而是因为下一份合约的交易价格不同。当远月合约更贵时（升水，contango），序列会向上跳；当远月合约更便宜时（贴水，backwardation），序列会向下跳。在合约到期前后基于单日变化发出提醒之前，请记住这一点。
• 单个交易所并不代表整个市场。COMEX 铜价是美国交易所的价格。全球大部分实物铜、铝和锌以伦敦金属交易所（LME）的价格为定价基准，而实物交割还要加上地区升水、运费和税费。不同交易场所的价格走势紧密相关，但并不完全一致。如果供货合同指定了特定的参考价格，例如 LME 官方价格或某个公开发布的价格评估，那么您的发票应以该参考价格为准。交易所期货数据是监控和估算的好工具，但不能替代合同中约定的价格指数。
• 交易时间。这些合约遵循各自交易所的交易时间：从纽约时间周日晚间到周五下午几乎全天候交易，每天有短暂休市。周末期间，MetalAPI 会持续返回最后的价格。

由于这些品种的价格来自期货，它们只发布单一价格，不支持买入价和卖出价后缀。金属和能源的每日历史数据可追溯至 2000 年，历史数据指南介绍了如何查询收盘价、区间数据和 OHLC 数据。

单位与货币换算

如果您需要以不同单位获取多种金属的价格，最省配额的做法是以金衡盎司发送一次请求，再在自己的代码中换算。一次数据请求无论返回多少个品种都只计一次，因此这样只需一次请求，而不是三次。下面的常数直接由各单位的定义推出：

// 每个质量单位所含的金衡盎司数
const GRAMS_PER_TROY_OZ = 31.1034768;
const TROY_OZ_PER = {
  lb: 453.59237 / GRAMS_PER_TROY_OZ,        // 14.5833…
  short_ton: 907184.74 / GRAMS_PER_TROY_OZ, // 29,166.67…
  metric_ton: 1e6 / GRAMS_PER_TROY_OZ,      // 32,150.75…
};

const NATURAL_UNIT = { XCU: "lb", ALU: "metric_ton", ZNC: "metric_ton", HRC: "short_ton" };

const url = new URL("https://metalapi.com/api/v1/latest");
url.searchParams.set("currencies", Object.keys(NATURAL_UNIT).join(","));

const res = await fetch(url, { 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);

for (const [symbol, unit] of Object.entries(NATURAL_UNIT)) {
  const perTroyOz = data.rates["USD" + symbol]; // 美元/金衡盎司
  if (perTroyOz === undefined) continue;
  console.log(symbol, (perTroyOz * TROY_OZ_PER[unit]).toFixed(2), "USD per", unit);
}

对于金属和能源，货币的用法相同。添加 base=EUR 或其他 57 种受支持货币中的任意一种，响应中的所有价格都会以该货币表示，并基于同一快照换算。如需直接计算某一数量的价值，可使用接受数量和单位参数的 /convert：

# 25 公吨铜值多少欧元
curl "https://metalapi.com/api/v1/convert?from=XCU&to=EUR&amount=25&unit=metric_ton" \
  -H "Authorization: Bearer YOUR_API_KEY"

能源单位的换算需要在您的代码中完成。常用的标准换算系数：1 桶等于 42 美制加仑，约合 158.987 升；1 美制加仑等于 3.785411784 升；1 MMBtu 约等于 1.055 吉焦、293.07 千瓦时或 10 撒姆（therm）。将原油从桶换算为吨取决于原油的密度，因此请使用您实际采购的油品等级所对应的系数。

应用场景：采购与成本监控

采购团队利用交易所价格了解投入成本的变化方向，并核验供应商报价是否合理。典型的组成部分包括：

• 每日数据看板，以合同所用的单位和货币展示铜、铝、钢材和柴油的价格。
• 期间变化：使用 /change，一次请求即可返回每个品种在两个日期之间的起始价、结束价、绝对变化和百分比变化。
• 阈值提醒。在付费套餐中，当价格突破某一水平或变动达到一定百分比时，控制台中的价格提醒会发送电子邮件；从 Advanced 套餐起还可以发送带签名的 Webhook。这是触发预算假设复核的一种简单方式。
• 报价核验。将供应商价格中的金属成本与交易所参考价进行比较，可以看出价格变化中有多少来自金属本身，又有多少来自升水或加工费用。

# 铜和铝（每公吨）：2026 年 9 月的价格变化
curl "https://metalapi.com/api/v1/change?currencies=XCU,ALU&unit=metric_ton&start_date=2026-09-01&end_date=2026-09-30" \
  -H "Authorization: Bearer YOUR_API_KEY"

请记住前文的提醒：如果合同与某个特定的公开价格挂钩，凡是最终要写入发票的内容，都应以该价格指数为准进行核对。

应用场景：制造成本模型

物料清单（BOM）通常以千克列出金属含量。由于所有金属的 unit 都接受 kilogram，一次请求即可以您的报告货币返回所有金属的每千克价格：

import os
import requests

# 每件产品的金属含量，单位为千克（示例）
BOM = {"XCU": 1.20, "ALU": 0.85, "ZNC": 0.05}

resp = requests.get(
    "https://metalapi.com/api/v1/latest",
    params={"currencies": ",".join(BOM), "unit": "kilogram", "base": "EUR"},
    headers={"X-API-Key": os.environ["METALAPI_KEY"]},
    timeout=10,
)
data = resp.json()
if not data.get("success"):
    raise RuntimeError(data["error"])

total = 0.0
for symbol, kg in BOM.items():
    eur_per_kg = data["rates"]["EUR" + symbol]
    cost = kg * eur_per_kg
    total += cost
    print(f"{symbol}: {kg} kg x {eur_per_kg:.4f} EUR/kg = {cost:.2f} EUR")

print(f"Metal content per unit: {total:.2f} EUR (prices of {data['date']})")

有两项改进能让这类模型更有用。第一，将所用的价格、单位和时间戳与每次成本计算一同保存，这样日后就能解释成本为何变化。第二，考虑使用一段时间的平均价，而不是单一的最新价格，这样可以平滑每日波动和移仓跳变。在付费套餐中，/timeframe 单次请求可返回最多 365 天的每日收盘价（Free 套餐为 30 天），一次调用就足以计算月度或季度平均价。

应用场景：物流与燃油成本

对许多承运商来说，燃油是最大的可变成本，燃油附加费通常每周或每月重新计算一次。HEATINGOIL 即纽约港超低硫柴油合约，是广受关注的柴油批发参考价格。GASOLINE（RBOB）对汽油起着同样的作用，WTI 和 BRENT 则涵盖原油。

批发期货价格和加油站价格是两回事：零售价格还包含分销成本、利润和税费，并且滞后于期货价格变动。许多附加费计算表以某个公开发布的零售平均价为参考；如果您的也是如此，就应使用该平均价。尽管如此，期货数据对于内部成本跟踪和及早发现上游价格变动仍然很有用。

下面的示例计算柴油合约上周每日收盘价的平均值，并将结果从每加仑价格换算为欧元/升：

const LITRES_PER_GALLON = 3.785411784;

const url = new URL("https://metalapi.com/api/v1/timeframe");
url.searchParams.set("currencies", "HEATINGOIL");
url.searchParams.set("base", "EUR");
url.searchParams.set("start_date", "2026-10-19");
url.searchParams.set("end_date", "2026-10-23");

const res = await fetch(url, { 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);

// rates 以日期为键；没有收盘价的日子（周末、节假日）不会出现
const closes = Object.values(data.rates).map((day) => day.EURHEATINGOIL);
const avgPerGallon = closes.reduce((sum, p) => sum + p, 0) / closes.length;

console.log("Average:", (avgPerGallon / LITRES_PER_GALLON).toFixed(4), "EUR per litre");

实用建议

• 按套餐的更新间隔轮询，不要更频繁。Free 获取每日价格，Lite 每 30 分钟更新，Standard 每 10 分钟，Advanced 和 Pro 每分钟，Ultra 和 Business 每 15 秒，Enterprise 每 5 秒。两次更新之间发出的请求返回的是同一快照，但仍会计费。从 Pro 套餐起，可以用实时流代替轮询。
• 批量请求品种。一次请求即可返回全部九个工业金属和能源品种，费用与只请求一个品种相同。
• 保存您获取的数据。将每个价格与其品种、单位、基础货币和 timestamp 一同保存。日后换算很容易，但要猜出一个旧数字的单位却很难。
• 历史数据中会有缺口。每日序列会跳过周末和交易所假日，因此不要假设每个自然日都有一条数据。
• 将长区间分段。在付费套餐中，单次 /timeframe 请求最多覆盖 365 天，因此如需追溯到 2000 年的更长历史，请按年循环请求。
• 发送前先校验。因日期、品种或单位无效而被拒绝的请求仍会计入配额，因此请先在代码中检查。因速率限制被拒绝的请求和服务器错误则不计费。

开始使用：注册获取免费密钥，在品种页面查看工业金属和能源的实时价格，并参阅 API 文档了解所有端点和参数。定价页面列出了各套餐的更新间隔和配额。