Prix du cuivre, de l'aluminium, du zinc et du pétrole par API : le guide du développeur

Les symboles industriels et énergétiques

Les métaux précieux font la plupart des gros titres, mais beaucoup d'entreprises sont davantage concernées par le cuivre, l'aluminium, l'acier et le carburant. Ce sont eux qui déterminent le coût des câbles et des moteurs, des canettes et des carrosseries, de l'acier de construction et de chaque camion qui transporte des marchandises. MetalAPI cote quatre métaux industriels et cinq contrats énergétiques aux côtés de l'or et de l'argent, via les mêmes endpoints et dans le même format de réponse.

La page des symboles les liste avec leurs prix en direct, et GET /api/v1/symbols?details=1 renvoie la catégorie et l'unité de chaque symbole en JSON. Cet appel est gratuit et n'est pas décompté de votre quota.

Unités de marché et normalisation de l'API

Chacun de ces marchés a sa propre convention. À New York, le cuivre se négocie à la livre ; l'aluminium et le zinc à la tonne métrique, l'acier américain à la tonne courte, le pétrole brut au baril, le gaz naturel au million de British thermal units (MMBtu) et les produits raffinés au gallon. Confondez-les et vos chiffres seront faux d'un facteur mille, voire davantage.

MetalAPI normalise les métaux et laisse l'énergie dans ses unités de contrat :

• Tous les métaux, précieux et industriels, sont cotés par once troy par défaut. Ainsi, tous les métaux restent directement comparables et chacun peut être converti avec un seul paramètre. Le cuivre à l'once troy n'est un prix que personne ne négocie : pour les métaux industriels, vous passerez donc presque toujours unit.
• L'énergie est cotée dans son unité de contrat : le baril pour WTI et BRENT, le MMBtu pour NATURALGAS, le gallon américain pour GASOLINE et HEATINGOIL. Le paramètre unit ne s'applique ni à l'énergie, ni aux devises, ni aux cryptos.

unit accepte troy_oz (par défaut), gram, kilogram, ounce, pound, metric_ton et short_ton. Pour obtenir chaque métal dans l'unité de son marché :

# Cuivre en USD par livre
curl "https://metalapi.com/api/v1/latest?currencies=XCU&unit=pound" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Aluminium et zinc en USD par tonne métrique
curl "https://metalapi.com/api/v1/latest?currencies=ALU,ZNC&unit=metric_ton" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Acier laminé à chaud (HRC) en USD par tonne courte
curl "https://metalapi.com/api/v1/latest?currencies=HRC&unit=short_ton" \
  -H "Authorization: Bearer YOUR_API_KEY"

Lorsqu'une unité autre que celle par défaut est utilisée, la réponse l'indique dans un champ unit. Le prix qui vous intéresse est la clé préfixée par la devise de base (USDXCU) ; la clé simple XCU en est l'inverse, conservée pour la compatibilité avec les anciennes intégrations :

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

Des prix issus des contrats à terme : que signifie « première échéance » ?

L'or au comptant se négocie de gré à gré 24 heures sur 24, mais c'est sur les marchés à terme que les métaux industriels et l'énergie sont cotés de la manière la plus transparente. MetalAPI tire ces prix du COMEX et du NYMEX (tous deux membres du CME Group) ainsi que de l'ICE. Un contrat à terme (future) est un accord standardisé d'achat ou de vente d'une quantité donnée à un prix donné, pour une livraison lors d'un mois précis. Chaque mois de livraison est un contrat distinct, avec son propre prix.

La première échéance (front month) est le mois de livraison le plus proche encore négocié. Une série continue de première échéance suit ce contrat jusqu'à l'approche de son expiration, puis bascule (roll) sur le suivant. Trois conséquences comptent pour les développeurs :

• Sauts au roll. À une date de roll, la série peut sauter, non parce que le marché a bougé, mais parce que le contrat suivant se négocie à un autre prix. Quand les échéances ultérieures sont plus chères (report, ou contango), la série monte d'un cran ; quand elles sont moins chères (déport, ou backwardation), elle baisse d'un cran. Gardez-le en tête avant de déclencher une alerte sur une variation d'un jour autour d'une expiration.
• Une bourse n'est pas tout le marché. Un prix du cuivre COMEX est un prix de bourse américain. Une grande partie du cuivre, de l'aluminium et du zinc physiques dans le monde est cotée par rapport au London Metal Exchange, et les livraisons physiques ajoutent primes régionales, fret et taxes. Les prix des différentes places évoluent de près, mais pas à l'identique. Si un contrat d'approvisionnement désigne une référence précise, comme un prix officiel du LME ou une évaluation de prix publiée, c'est cette référence qui fait foi pour votre facture. Un flux de contrats à terme est un bon outil de suivi et d'estimation, pas un substitut à l'indice contractuel.
• Horaires de cotation. Ces contrats suivent les horaires de leurs bourses : presque 24 heures sur 24 du dimanche soir au vendredi après-midi, heure de New York, avec une courte pause quotidienne. Le week-end, MetalAPI continue de renvoyer le dernier prix.

Comme ils proviennent de contrats à terme, ces symboles sont publiés avec un prix unique ; les suffixes bid et ask ne sont pas disponibles pour eux. L'historique quotidien des métaux et de l'énergie remonte à 2000, et le guide des données historiques montre comment interroger les cours de clôture, les périodes et les barres OHLC.

Convertir unités et devises

Si vous avez besoin de plusieurs métaux dans des unités différentes, l'approche la plus économique consiste à faire une seule requête en onces troy et la conversion dans votre propre code. Une requête de données compte une fois, quel que soit le nombre de symboles renvoyés : cela coûte donc une requête au lieu de trois. Les constantes ci-dessous découlent des définitions des unités :

// Onces troy dans une unité de masse
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]; // USD par once troy
  if (perTroyOz === undefined) continue;
  console.log(symbol, (perTroyOz * TROY_OZ_PER[unit]).toFixed(2), "USD per", unit);
}

Les devises fonctionnent de la même façon pour les métaux et l'énergie. Ajoutez base=EUR, ou l'une des 57 devises prises en charge, et chaque prix de la réponse est exprimé dans cette devise, converti à partir du même instantané. Pour valoriser directement une quantité, /convert accepte un montant et une unité :

# 25 tonnes métriques de cuivre en euros
curl "https://metalapi.com/api/v1/convert?from=XCU&to=EUR&amount=25&unit=metric_ton" \
  -H "Authorization: Bearer YOUR_API_KEY"

Les conversions d'énergie se font dans votre code. Quelques facteurs standard utiles : un baril vaut 42 gallons américains, soit environ 158,987 litres ; un gallon américain vaut 3,785411784 litres ; un MMBtu vaut environ 1,055 gigajoule, 293,07 kWh ou 10 therms. La conversion de barils de pétrole brut en tonnes dépend de la densité du pétrole : utilisez le facteur correspondant à la qualité que vous achetez réellement.

Cas d'usage : achats et suivi des coûts

Les équipes achats utilisent les prix de marché pour comprendre l'évolution de leurs coûts d'intrants et vérifier la cohérence des devis fournisseurs. Les briques typiques :

• Un tableau de bord quotidien du cuivre, de l'aluminium, de l'acier et du gazole dans les unités et la devise de vos contrats.
• La variation d'une période à l'autre avec /change, qui renvoie en une seule requête le prix de départ, le prix de fin, la variation absolue et la variation en pourcentage entre deux dates pour chaque symbole.
• Des alertes de seuil. Sur les plans payants, les alertes de prix du tableau de bord envoient un e-mail, et à partir du plan Advanced également un webhook signé, lorsqu'un prix franchit un niveau ou varie d'un certain pourcentage. C'est un moyen simple de déclencher la révision d'une hypothèse budgétaire.
• Le contrôle des devis. Comparer la part métal du prix d'un fournisseur avec la référence de marché montre quelle part d'une hausse de prix vient du métal et quelle part vient des primes ou de la transformation.

# Cuivre et aluminium à la tonne métrique : variation sur septembre 2026
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"

Gardez en tête la réserve formulée plus haut : si un contrat est indexé sur un prix publié précis, effectuez le rapprochement avec cet indice pour tout ce qui figure sur une facture.

Cas d'usage : modèles de coûts de fabrication

Une nomenclature indique généralement la teneur en métal en kilogrammes. Comme unit accepte kilogram pour tous les métaux, une seule requête renvoie le prix au kilogramme de chacun d'eux, dans votre devise de reporting :

import os
import requests

# Teneur en métal par unité de produit, en kg (indicatif)
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']})")

Deux améliorations rendent un tel modèle plus utile. D'abord, stockez le prix, l'unité et l'horodatage utilisés à côté de chaque calcul de coût, pour pouvoir expliquer plus tard pourquoi un coût a changé. Ensuite, envisagez une moyenne sur une période plutôt qu'un seul dernier prix ; elle lisse le bruit quotidien et les sauts de roll. /timeframe renvoie les clôtures quotidiennes sur 365 jours maximum par requête sur les plans payants (30 jours sur Free), ce qui suffit pour une moyenne mensuelle ou trimestrielle en un seul appel.

Cas d'usage : logistique et coûts de carburant

Le carburant est le premier coût variable de nombreux transporteurs, et les surcharges carburant sont souvent recalculées chaque semaine ou chaque mois. HEATINGOIL, le contrat de diesel à très basse teneur en soufre de NY Harbor, est une référence de gros du gazole très suivie. GASOLINE (RBOB) joue le même rôle pour l'essence, et WTI et BRENT couvrent le pétrole brut.

Les contrats à terme de gros et les prix à la pompe sont deux choses différentes : les prix de détail ajoutent coûts de distribution, marges et taxes, et suivent les contrats à terme avec un décalage. De nombreux barèmes de surcharge se réfèrent à une moyenne de prix de détail publiée ; si c'est le cas du vôtre, c'est cette moyenne qu'il faut utiliser. Les données des contrats à terme restent utiles pour le suivi interne des coûts et pour repérer tôt les mouvements en amont.

Cet exemple calcule la moyenne des clôtures quotidiennes de la semaine dernière pour le contrat de diesel et convertit le résultat, exprimé par gallon, en EUR par litre :

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 est indexé par date ; les jours sans clôture (week-ends, jours fériés) sont absents
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");

Conseils pratiques

• Interrogez l'API à l'intervalle de votre plan, pas plus vite. Free reçoit des prix quotidiens, Lite toutes les 30 minutes, Standard toutes les 10 minutes, Advanced et Pro toutes les minutes, Ultra et Business toutes les 15 secondes et Enterprise toutes les 5 secondes. Les requêtes intermédiaires renvoient le même instantané et sont quand même décomptées. À partir de Pro, le flux en temps réel remplace le polling.
• Regroupez les symboles. Une seule requête peut renvoyer les neuf symboles industriels et énergétiques, et elle coûte autant qu'une requête pour un seul.
• Stockez ce que vous avez récupéré. Conservez chaque prix avec son symbole, son unité, sa devise de base et son timestamp. Convertir plus tard est facile ; deviner l'unité d'un ancien chiffre ne l'est pas.
• Attendez-vous à des trous dans l'historique. Les séries quotidiennes sautent les week-ends et les jours fériés des bourses : ne supposez pas une entrée par jour calendaire.
• Découpez les longues périodes. Une seule requête /timeframe couvre jusqu'à 365 jours sur les plans payants : bouclez année par année pour les historiques plus longs, jusqu'en 2000.
• Validez avant d'envoyer. Les requêtes rejetées pour des dates, symboles ou unités invalides sont quand même décomptées de votre quota : vérifiez-les d'abord dans votre code. Les rejets pour limite de débit et les erreurs serveur ne sont pas facturés.

Pour commencer, inscrivez-vous pour obtenir une clé gratuite, consultez la page des symboles pour les prix industriels et énergétiques en direct, et la documentation de l'API pour chaque endpoint et paramètre. La page des tarifs indique l'intervalle de mise à jour et le quota de chaque plan.