API ile Bakır, Alüminyum, Çinko ve Petrol Fiyatları: Geliştirici Rehberi

Endüstriyel metal ve enerji sembolleri

Manşetlerde çoğunlukla değerli metaller yer alır, ancak birçok işletme için bakır, alüminyum, çelik ve yakıt daha önemlidir. Kablo ve motorların, içecek kutuları ve araç gövdelerinin, inşaat çeliğinin ve mal taşıyan her kamyonun maliyetini bunlar belirler. MetalAPI, altın ve gümüşün yanında dört endüstriyel metal ve beş enerji kontratını da aynı endpoint'ler üzerinden ve aynı yanıt formatında sunar.

Semboller sayfası bunları canlı fiyatlarıyla listeler; GET /api/v1/symbols?details=1 ise her sembolün kategorisini ve birimini JSON olarak döndürür. Bu çağrı ücretsizdir ve kotanızdan düşülmez.

Doğal birimler ve API'nin normalizasyonu

Bu piyasaların her birinin kendi teamülü vardır. New York'ta bakır libre başına işlem görür; alüminyum ve çinko metrik ton, ABD çeliği kısa ton, ham petrol varil, doğal gaz milyon İngiliz ısı birimi (MMBtu), rafine ürünler ise galon başına işlem görür. Bunları karıştırırsanız sayılarınız bin kat veya daha fazla sapar.

MetalAPI metalleri normalize eder, enerjiyi ise kontrat birimlerinde bırakır:

• Değerli ve endüstriyel tüm metaller varsayılan olarak troy ons başına fiyatlanır. Bu, tüm metalleri doğrudan karşılaştırılabilir kılar ve her birini tek bir parametreyle dönüştürmenizi sağlar. Troy ons başına bakır, kimsenin işlem yaptığı bir fiyat değildir; bu nedenle endüstriyel metallerde neredeyse her zaman unit göndereceksiniz.
• Enerji kontrat birimi başına fiyatlanır: WTI ve BRENT için varil, NATURALGAS için MMBtu, GASOLINE ve HEATINGOIL için ABD galonu. unit parametresi enerjiye, para birimlerine ve kriptoya uygulanmaz.

unit; troy_oz (varsayılan), gram, kilogram, ounce, pound, metric_ton ve short_ton değerlerini kabul eder. Her metali kendi piyasasının kullandığı birimde almak için:

# Libre başına USD cinsinden bakır
curl "https://metalapi.com/api/v1/latest?currencies=XCU&unit=pound" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Metrik ton başına USD cinsinden alüminyum ve çinko
curl "https://metalapi.com/api/v1/latest?currencies=ALU,ZNC&unit=metric_ton" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Kısa ton başına USD cinsinden sıcak haddelenmiş rulo çelik
curl "https://metalapi.com/api/v1/latest?currencies=HRC&unit=short_ton" \
  -H "Authorization: Bearer YOUR_API_KEY"

Varsayılan dışında bir birim kullanıldığında yanıt bunu bir unit alanında belirtir. İhtiyacınız olan fiyat, baz para birimiyle ön eklenmiş anahtardır (USDXCU); yalın XCU anahtarı ise eski entegrasyonlarla uyumluluk için korunan ters değerdir:

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

Vadeli işlemlere dayalı fiyatlar ve en yakın vade ne demek

Spot altın tezgâh üstü piyasada günün her saatinde işlem görür; endüstriyel metaller ve enerji ise en şeffaf biçimde vadeli işlem borsalarında fiyatlanır. MetalAPI bu fiyatları COMEX ve NYMEX'ten (her ikisi de CME Group'a bağlıdır) ve ICE'tan alır. Vadeli işlem kontratı, belirli bir miktarın belirli bir fiyattan, belirli bir ayda teslim edilmek üzere alınması veya satılması için yapılan standart bir sözleşmedir. Her teslimat ayı, kendi fiyatına sahip ayrı bir kontrattır.

En yakın vade (front month), hâlâ işlem gören en yakın teslimat ayıdır. Sürekli bir en yakın vade serisi, bu kontratı vadesi yaklaşana kadar izler ve ardından bir sonrakine geçer; buna devir (roll) denir. Geliştiriciler için üç sonucu önemlidir:

• Devir sıçramaları. Devir tarihinde seri, piyasa hareket ettiği için değil, bir sonraki kontrat farklı bir fiyattan işlem gördüğü için sıçrayabilir. İleri vadeler daha pahalıysa (contango) seri yukarı, daha ucuzsa (backwardation) aşağı doğru basamak yapar. Vade sonu civarında tek günlük bir değişime göre alarm kurmadan önce bunu göz önünde bulundurun.
• Tek bir borsa piyasanın tamamı değildir. COMEX bakır fiyatı bir ABD borsası fiyatıdır. Dünyadaki fiziksel bakır, alüminyum ve çinkonun büyük bölümü Londra Metal Borsası (LME) referans alınarak fiyatlanır; fiziksel teslimatlara ise bölgesel primler, navlun ve vergiler eklenir. Farklı piyasalardaki fiyatlar birbirini yakından izler, ancak birebir aynı değildir. Bir tedarik sözleşmesi LME resmi fiyatı veya yayımlanan bir fiyat değerlendirmesi gibi belirli bir referansı adıyla belirtiyorsa faturanızı o referans belirler. Borsadan gelen bir vadeli işlem fiyat akışı, izleme ve tahmin için iyi bir araçtır, ancak sözleşmede belirtilen endeksin yerini tutmaz.
• İşlem saatleri. Bu kontratlar borsalarının çalışma saatlerini izler: New York saatiyle pazar akşamından cuma öğleden sonrasına kadar, kısa bir günlük ara dışında neredeyse kesintisiz. Hafta sonu MetalAPI son fiyatı döndürmeye devam eder.

Vadeli işlemlerden geldikleri için bu semboller tek bir fiyat olarak yayınlanır; alış ve satış son ekleri bu semboller için kullanılamaz. Metaller ve enerji için günlük geçmiş veriler 2000 yılına uzanır; geçmiş veriler rehberi kapanış fiyatlarının, tarih aralıklarının ve OHLC çubuklarının nasıl sorgulanacağını gösterir.

Birim ve para birimi dönüştürme

Birden fazla metale farklı birimlerde ihtiyacınız varsa en ucuz yol, troy ons cinsinden tek bir istek yapıp dönüşümü kendi kodunuzda gerçekleştirmektir. Bir veri isteği kaç sembol döndürürse döndürsün tek istek sayılır; bu yöntem de üç istek yerine bir isteğe mal olur. Aşağıdaki sabitler birimlerin tanımlarından türetilir:

// Bir kütle birimindeki troy ons miktarı
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]; // troy ons başına USD
  if (perTroyOz === undefined) continue;
  console.log(symbol, (perTroyOz * TROY_OZ_PER[unit]).toFixed(2), "USD per", unit);
}

Para birimleri metaller ve enerji için de aynı şekilde çalışır. base=EUR veya desteklenen 57 para biriminden herhangi birini ekleyin; yanıttaki tüm fiyatlar aynı anlık görüntüden dönüştürülerek o para birimiyle ifade edilir. Bir miktarı doğrudan değerlemek için /convert bir tutar ve bir birim alır:

# 25 metrik ton bakırın euro karşılığı
curl "https://metalapi.com/api/v1/convert?from=XCU&to=EUR&amount=25&unit=metric_ton" \
  -H "Authorization: Bearer YOUR_API_KEY"

Enerji dönüşümleri kendi kodunuzda yapılır. İşinize yarayacak standart katsayılar: bir varil 42 ABD galonu ya da yaklaşık 158,987 litredir; bir ABD galonu 3,785411784 litredir; bir MMBtu yaklaşık 1,055 gigajoule, 293,07 kWh veya 10 therm'e eşittir. Ham petrol varilini tona çevirmek petrolün yoğunluğuna bağlıdır; bu nedenle gerçekten satın aldığınız türün katsayısını kullanın.

Kullanım örneği: satın alma ve maliyet izleme

Satın alma ekipleri, girdi maliyetlerinin nereye gittiğini anlamak ve tedarikçi tekliflerinin makul olup olmadığını kontrol etmek için borsa fiyatlarını kullanır. Tipik yapı taşları:

• Sözleşmelerinizde kullanılan birim ve para birimi cinsinden bakır, alüminyum, çelik ve dizel fiyatlarını gösteren günlük bir gösterge paneli.
• Her sembol için iki tarih arasındaki başlangıç fiyatını, bitiş fiyatını, mutlak değişimi ve yüzde değişimi tek bir istekte döndüren /change ile dönemsel değişim.
• Eşik alarmları. Ücretli planlarda paneldeki fiyat alarmları, bir fiyat belirli bir seviyeyi geçtiğinde veya belirli bir yüzde kadar hareket ettiğinde e-posta, Advanced planından itibaren ise imzalı bir webhook da gönderir. Bu, bir bütçe varsayımının gözden geçirilmesini tetiklemenin basit bir yoludur.
• Teklif kontrolleri. Bir tedarikçi fiyatındaki metal içeriğini borsa referansıyla karşılaştırmak, bir fiyat değişiminin ne kadarının metalden, ne kadarının primlerden veya işleme maliyetlerinden kaynaklandığını gösterir.

# Metrik ton başına bakır ve alüminyum: Eylül 2026 boyunca değişim
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"

Yukarıdaki uyarıyı aklınızda tutun: bir sözleşme yayımlanan belirli bir fiyata endeksliyse faturaya yansıyan her şeyi o endeksle mutabık kılın.

Kullanım örneği: üretim maliyet modelleri

Bir malzeme listesi (BOM), metal içeriğini genellikle kilogram cinsinden belirtir. unit her metal için kilogram değerini kabul ettiğinden tek bir istek, hepsinin kilogram başına fiyatını raporlama para biriminizde döndürür:

import os
import requests

# Ürün birimi başına metal içeriği, kg cinsinden (temsili)
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']})")

İki iyileştirme böyle bir modeli daha kullanışlı hale getirir. Birincisi, her maliyet hesaplamasının yanında kullandığınız fiyatı, birimi ve zaman damgasını saklayın; böylece bir maliyetin neden değiştiğini sonradan açıklayabilirsiniz. İkincisi, tek bir güncel fiyat yerine bir dönemin ortalamasını kullanmayı düşünün; bu, günlük dalgalanmaları ve devir sıçramalarını yumuşatır. /timeframe, ücretli planlarda istek başına 365 güne kadar (Free planda 30 gün) günlük kapanış döndürür; bu da aylık veya çeyreklik bir ortalama için tek bir çağrıyla yeterlidir.

Kullanım örneği: lojistik ve yakıt maliyetleri

Yakıt, birçok taşıyıcı için en büyük değişken maliyettir ve yakıt ek ücretleri genellikle haftalık veya aylık olarak yeniden hesaplanır. NY Harbor ultra düşük kükürtlü dizel kontratı olan HEATINGOIL, yaygın olarak takip edilen bir toptan dizel referansıdır. GASOLINE (RBOB) benzin için aynı rolü üstlenir; WTI ve BRENT ise ham petrolü kapsar.

Toptan vadeli işlem fiyatları ile pompa fiyatları farklı şeylerdir: perakende fiyatlara dağıtım maliyetleri, kâr marjları ve vergiler eklenir ve bu fiyatlar vadeli işlemleri gecikmeyle izler. Birçok ek ücret tarifesi yayımlanan bir perakende ortalamayı referans alır; sizinki de öyleyse kullanmanız gereken sayı o ortalamadır. Vadeli işlem verileri yine de dahili maliyet takibi ve piyasanın üst kademelerindeki hareketleri erkenden görmek için faydalıdır.

Bu örnek, dizel kontratının geçen haftaki günlük kapanışlarının ortalamasını alır ve sonucu galon başına USD'den litre başına EUR'ya dönüştürür:

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 tarihe göre anahtarlanır; kapanışı olmayan günler (hafta sonları, tatiller) yer almaz
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");

Pratik ipuçları

• Planınızın güncelleme aralığında sorgulayın, daha sık değil. Free plan günlük fiyatları görür; Lite 30 dakikada bir, Standard 10 dakikada bir, Advanced ve Pro dakikada bir, Ultra ve Business 15 saniyede bir, Enterprise ise 5 saniyede bir güncellenir. Aradaki istekler aynı anlık görüntüyü döndürür ve yine de sayılır. Pro ve üzeri planlarda gerçek zamanlı akış sorgulamanın yerini alır.
• Sembolleri toplu isteyin. Tek bir istek dokuz endüstriyel metal ve enerji sembolünün tamamını döndürebilir ve tek sembollük bir istekle aynı maliyete sahiptir.
• Aldığınız veriyi saklayın. Her fiyatı sembolü, birimi, baz para birimi ve timestamp değeriyle birlikte kaydedin. Sonradan dönüştürmek kolaydır; eski bir sayının birimini tahmin etmek ise değildir.
• Geçmiş verilerde boşluklar bekleyin. Günlük seriler hafta sonlarını ve borsa tatillerini atlar; bu nedenle her takvim günü için bir kayıt olacağını varsaymayın.
• Uzun aralıkları parçalara bölün. Ücretli planlarda tek bir /timeframe isteği 365 güne kadar kapsar; 2000'e uzanan daha uzun geçmişler için yıl yıl döngü kurun.
• Göndermeden önce doğrulayın. Geçersiz tarih, sembol veya birim nedeniyle reddedilen istekler yine de kotanızdan düşülür; bu nedenle bunları önce kendi kodunuzda kontrol edin. İstek limiti nedeniyle yapılan retler ve sunucu hataları ücretlendirilmez.

Başlamak için ücretsiz bir anahtar almak üzere kayıt olun, canlı endüstriyel metal ve enerji fiyatları için semboller sayfasına göz atın ve tüm endpoint'ler ile parametreler için API dokümantasyonunu inceleyin. Fiyatlandırma sayfası her planın güncelleme aralığını ve kotasını listeler.