Troy Ons, Gram ve Kilogram: Değerli Metal Fiyatlarını Doğru Dönüştürmek

Birim neden önemli

Değerli metaller neredeyse her yerde troy ons başına kote edilir: toptan piyasalarda, külçe satıcılarının fiyat listelerinde ve fiyat API'lerinde. Öte yandan metal alıp satan insanlar, nerede yaşadıklarına ve ne ticareti yaptıklarına bağlı olarak gram, kilogram, tola veya tael cinsinden düşünür. Bu nedenle insanlara metal fiyatı gösteren her ürün en az bir birim dönüşümü içerir ve bu dönüşüm, sessiz ve makul görünen hataların yaygın bir kaynağıdır.

Klasik hata, troy onsu sıradan bir ons gibi ele almaktır. İkisi arasında %10'a yakın bir fark vardır; bu fark her faturada önem taşıyacak kadar büyük, ancak bir demoda kimsenin fark etmeyeceği kadar küçüktür. Bu yazı kesin tanımları, dönüşüm katsayılarını, dönüşümü API'ye nasıl yaptıracağınızı, sonuçları nasıl yuvarlayıp göstereceğinizi ve test yazmaya değer hataların bir listesini ele alıyor.

Troy ons ile avoirdupois ons

Her iki ons da gren (grain) cinsinden tanımlanır ve grenin kesin bir metrik tanımı vardır: 1 gren = 64,79891 miligram. Geri kalan her şey buradan çıkar:

• Troy ons 480 grendir, yani tam olarak 31,1034768 gramdır. Altın, gümüş, platin ve paladyum bu birimle fiyatlanır.
• ABD ve Birleşik Krallık'ta gıda ve paketler için kullanılan gündelik ons olan avoirdupois ons 437,5 grendir, yani tam olarak 28,349523125 gramdır.
• Bir troy libre 12 troy ons (373,2417216 g) iken avoirdupois libre 16 avoirdupois ons (453,59237 g) eder. Yani troy ons daha ağır olan onstur, ancak troy libre daha hafif olan libredir.

Bir troy ons, bir avoirdupois onstan yaklaşık %9,7 daha ağırdır (480 ÷ 437,5 ≈ 1,0971). Bu oran, ikisi karıştırıldığında ortaya çıkan hatanın tam büyüklüğüdür.

Kaynak aksini belirtmedikçe bir değerli metal fiyatındaki ons, troy onstur ve genellikle oz t veya ozt olarak yazılır. MetalAPI'de varsayılan birim troy_oz'dur ve siz başka bir birim istemedikçe her metal fiyatı troy ons başınadır.

Kesin dönüşüm katsayıları

Bu birimlerin tümü kesin olarak tanımlandığı için dönüşümler hiçbir yaklaşıklık gerektirmez. Troy ons başına bir fiyatı başka bir birim başına fiyata çevirmek için onu o birimdeki troy ons sayısıyla çarpın:

birim başına fiyat = troy ons başına fiyat × birimdeki gram ÷ 31,1034768

Güney Asya'da ve Körfez ülkelerinde altın için hâlâ yaygın olarak kullanılan tola, 180 gren olarak tanımlanır: tam olarak 11,6638038 g, yani bir troy onsun sekizde üçü. Tael ise o kadar düzenli değildir, çünkü ağırlığı piyasaya göre değişir: Hong Kong altın ticaretinde yaklaşık 37,4 g, Tayvan'da 37,5 g ve Çin anakarasında 50 g. Tael destekliyorsanız gram ağırlığını bir yapılandırma değeri yapın ve hangi taeli kastettiğinizi etiketleyin.

Kilogramlık külçeler kullanışlı bir sağlama yöntemi sunar. Bir kilogram yaklaşık 32,15 troy onstur; dolayısıyla kilogram fiyatı her zaman ons fiyatının kabaca 32 katı olmalıdır. 35 katına daha yakınsa biri avoirdupois katsayısını kullanmıştır.

Elle dönüştürme

Elinizde zaten troy ons başına bir fiyat varsa onu kendiniz dönüştürmek tek bir çarpma işlemidir. Kesin sabitleri tek bir modülde tutun ve dönüşümü gram üzerinden yapın; böylece her birim çifti aynı şekilde çalışır:

// Her birimin gram karşılığı. Hepsi kesin: 1 gren = 64.79891 mg.
const GRAMS_PER_UNIT = {
  troy_oz: 31.1034768, // 480 gren
  gram: 1,
  kilogram: 1000,
  ounce: 28.349523125, // avoirdupois, 437.5 gren
  pound: 453.59237, // avoirdupois, 7,000 gren
  metric_ton: 1_000_000,
  short_ton: 907_184.74, // 2,000 lb
  tola: 11.6638038, // 180 gren
  pennyweight: 1.55517384, // 24 gren
};

/** `from` birimi başına bir fiyatı `to` birimi başına fiyata dönüştürür. */
export function convertPrice(price, from, to) {
  const a = GRAMS_PER_UNIT[from];
  const b = GRAMS_PER_UNIT[to];
  if (a === undefined || b === undefined) throw new Error(`Unknown unit: ${a === undefined ? from : to}`);
  return (price / a) * b;
}

console.log(convertPrice(3997.89, "troy_oz", "gram")); // 128.535148…
console.log(convertPrice(3997.89, "troy_oz", "kilogram")); // 128535.148…
console.log(convertPrice(3997.89, "troy_oz", "tola")); // 1499.20875

Python'da sonuç bir faturaya veya muhasebe defterine gidecekse Decimal kullanın. requests, parse_float parametresini JSON ayrıştırıcısına aktarır; böylece fiyatlar hiçbir zaman ikili kayan noktalı sayıya dönüşmez:

import os
from decimal import Decimal, ROUND_HALF_UP

import requests

GRAMS_PER_TROY_OZ = Decimal("31.1034768")
CENT = Decimal("0.01")

r = requests.get(
    "https://metalapi.com/api/v1/latest",
    params={"currencies": "XAU"},
    headers={"X-API-Key": os.environ["METALAPI_KEY"]},
    timeout=10,
)
data = r.json(parse_float=Decimal)
if not data["success"]:
    raise RuntimeError(data["error"])

per_oz = data["rates"]["USDXAU"]  # ör. Decimal("3997.89")
per_gram = per_oz / GRAMS_PER_TROY_OZ
per_kg = per_gram * 1000

print(per_gram.quantize(CENT, rounding=ROUND_HALF_UP))  # örnek fiyatla 128.54
print(per_kg.quantize(CENT, rounding=ROUND_HALF_UP))  # 128535.15

Ters kurlar ise tam tersi işlemi gerektirir. rates.XAU, baz para biriminin bir birimi başına troy ons miktarıdır; bu nedenle para birimi başına gram miktarı rates.XAU × 31,1034768'dir, ÷ değil. Bu tuzak, USDXAU gibi ön ekli fiyat anahtarlarıyla çalışıp ters anahtarlara hiç dokunmamak için bir neden daha.

Dönüşümü API'ye bırakmak: unit parametresi

İhtiyacınız olan birimi doğrudan MetalAPI'den de isteyebilirsiniz. /latest, geçmiş veri endpoint'leri, /timeframe, /ohlc, /convert ve /carat bir unit parametresi kabul eder: troy_oz (varsayılan), gram, kilogram, ounce, pound, metric_ton veya short_ton. Bu istek altın ve gümüşü gram başına euro cinsinden döndürür:

curl "https://metalapi.com/api/v1/latest?base=EUR&currencies=XAU,XAG&unit=gram" \
  -H "X-API-Key: $METALAPI_KEY"

Birim varsayılan değer değilse yanıt bunu üst düzeydeki bir unit alanında tekrarlar. Aşağıdaki değerler canlı fiyatlar değil, dokümantasyondaki bir örnektir:

{
  "success": true,
  "timestamp": 1792765800,
  "date": "2026-10-23",
  "base": "EUR",
  "unit": "gram",
  "rates": {
    "XAU": 0.009057444725,
    "EURXAU": 110.4064149,
    "XAG": 0.6713138244,
    "EURXAG": 1.489616277
  }
}

API, yukarıdaki tablolarla aynı kesin katsayıları kullanır ve ters anahtar da birimi izler: unit=gram ile rates.XAU, euro başına gram altın miktarıdır. Bilinmesi gereken birkaç kural:

• g, kg, lb ve tonne gibi kısa biçimler kabul edilir. oz avoirdupois ons anlamına gelir; bu nedenle onu asla troy ons kısaltması olarak kullanmayın.
• Bilinmeyen bir birim 209 (invalid_unit) hatası döndürür.
• unit yalnızca değerli ve endüstriyel metallere uygulanır. Enerji varil, MMBtu veya galon başına kalır; para birimleri ve kripto etkilenmez. Bu nedenle tek bir istekte farklı türde sembolleri karıştırmak güvenlidir.
• Endüstriyel metaller de varsayılan olarak troy ons başına kote edilir; böylece tüm metaller doğrudan karşılaştırılabilir. Bu piyasaların işlem gördüğü birimleri almak için bakırda unit=pound, alüminyum ve çinkoda unit=metric_ton, çelikte ise unit=short_ton gönderin.

/convert da unit kabul eder; bu sayede bir ağırlığı tek adımda paraya çevirebilirsiniz. Bu istek 250 gram altının ABD doları cinsinden değerini hesaplar:

curl "https://metalapi.com/api/v1/convert?from=XAU&to=USD&amount=250&unit=gram" \
  -H "X-API-Key: $METALAPI_KEY"

info.rate bir gramın ABD doları cinsinden fiyatı, result ise toplam miktarın değeridir. Örnek altın fiyatıyla yanıt şöyle görünür:

{
  "success": true,
  "query": { "from": "XAU", "to": "USD", "amount": 250, "unit": "gram" },
  "info": { "timestamp": 1792834892, "rate": 128.5351482, "quote": 128.5351482 },
  "date": "2026-10-24",
  "result": 32133.78705
}

Yuvarlama ve gösterim

Kurlar en fazla 10 anlamlı basamağa sahip JSON sayıları olarak gelir. Bu hassasiyet, türetilen değerlerin doğru kalması için vardır; bu yüzden onu mümkün olan en son ana kadar koruyun:

• Önce dönüştürün, en son yuvarlayın. Gram fiyatını kuruşa yuvarlayıp sonra bir kilogramlık külçe için 1.000 ile çarpmak, yarım kuruşluk bir yuvarlama hatasını beş para birimine kadar çıkan bir hataya dönüştürür.
• Para birimine göre yuvarlayın. Çoğu para birimi iki ondalık basamak kullanır; Japon yeni hiç kullanmaz, Kuveyt dinarı ise üç basamak kullanır. Sabit olarak iki basamak yazmak yerine varsayılanları Intl.NumberFormat veya kullandığınız yerelleştirme kütüphanesi belirlesin.
• Küçük fiyatlar için ek basamaklara izin verin. Troy ons başına 53,94 USD'lik örnek fiyatla gümüşün gramı yaklaşık 1,73 USD'dir ve iki ondalık basamak, gümüşün günlük hareketinin çoğunu gizler.
• Para için ondalık türler kullanın. Faturalanan veya kayda geçen her şey için Python'da Decimal, Java'da BigDecimal ya da veritabanınızda tam sayı alt birimler (kuruş gibi) kullanın. Grafikler için ikili kayan noktalı sayılar yeterlidir.
• Birimi etiketleyin. Her fiyatın yanına troy ons, gram veya kg başına olduğunu yazın. Yalnızca “ons başına” demek birçok okur için belirsizdir.

Para biriminin standart ondalık basamak sayısını Intl üzerinden alan ve isteğe bağlı olarak birkaç basamak ekleyen küçük bir yardımcı:

function formatPrice(value, currency, locale = "en-US", extraDigits = 0) {
  const { maximumFractionDigits } = new Intl.NumberFormat(locale, { style: "currency", currency }).resolvedOptions();
  const digits = maximumFractionDigits + extraDigits;
  return new Intl.NumberFormat(locale, {
    style: "currency",
    currency,
    minimumFractionDigits: digits,
    maximumFractionDigits: digits,
  }).format(value);
}

formatPrice(128.53514819925212, "USD"); // "$128.54"   gram başına altın
formatPrice(1.7342112699117933, "USD", "en-US", 2); // "$1.7342"   gram başına gümüş
formatPrice(110.4064149, "EUR", "de-DE"); // "110,41 €"

Bir bakışta dönüşüm tablosu

Tablo, MetalAPI dokümantasyonunda kullanılan örnek fiyatları dönüştürür: altın için troy ons başına 3.997,89 USD, gümüş için troy ons başına 53,94 USD. Bu değerler hesaplamayı göstermek içindir, güncel piyasa fiyatları değildir:

Son satıra bakın. Bir sayfa avoirdupois değerini ons fiyatı olarak etiketlerse külçe fiyatını %9'a yakın düşük gösterir. Tersi hata, yani gram fiyatı bulmak için troy ons fiyatını 28,35'e bölmek ise fiyatı yaklaşık %9,7 yüksek gösterir: gram altın için 128,54 yerine 141,02.

Yaygın dönüşüm hataları ve nasıl test edilir

Birim hatalarının çoğu birkaç kalıba uyar:

• 28,35'e bölmek. Troy ons fiyatı için avoirdupois katsayısını kullanmak. 31,1034768 kullanın.
• `oz` değerini troy sanmak. Çoğu birim kütüphanesinde olduğu gibi MetalAPI'de de oz avoirdupois onstur. Külçe fiyatları için troy_oz gerekir ya da hiç unit gönderilmez.
• Ters anahtarı dönüştürmek. rates.XAU bir fiyat değil, para birimi başına ons miktarıdır. Onu grama çevirmek 31,1034768 ile çarpmak anlamına gelir; bu da bölmeye alışkın herkese yanlış görünür.
• İki kez dönüştürmek. unit=gram isteyip ardından bir de 31,1034768'e bölmek, yaklaşık 31 kat küçük bir fiyat verir. Dönüşümün API'de mi yoksa kodunuzda mı yapılacağına karar verin; asla ikisinde birden yapmayın.
• Çok erken yuvarlamak. Yalnızca bir kez, gösterim anında yuvarlayın.
• Birimler arasında önbellek paylaşmak. Önbellek anahtarınız sorgu dizesini yok sayıyorsa ons fiyatı beklenen bir yerde gram yanıtı sunulabilir. unit ve base değerlerini anahtara dahil edin.
• Ağırlık birimlerini enerjiye uygulamak. unit petrol veya gaz üzerinde hiçbir etkiye sahip değildir ve bir varil fiyatını 31,1'e bölmenin bir anlamı yoktur. Dönüşümleri kategoriye göre koruma altına alın; /symbols?details=1 her sembolün kategorisini döndürür.

Birkaç özellik testi bu hataların çoğunu canlıya çıkmadan yakalar. Testler Node'un yerleşik test çalıştırıcısını ve yukarıdaki convertPrice fonksiyonunu kullanır; node --test ile çalıştırın:

import { test } from "node:test";
import assert from "node:assert/strict";
import { convertPrice } from "./units.mjs";

const PER_OZ = 3997.89; // örnek fiyat, troy ons başına USD

test("a kilogram price is 1,000 gram prices", () => {
  const g = convertPrice(PER_OZ, "troy_oz", "gram");
  const kg = convertPrice(PER_OZ, "troy_oz", "kilogram");
  assert.ok(Math.abs(kg - g * 1000) < 1e-6);
});

test("converting there and back returns the original price", () => {
  const g = convertPrice(PER_OZ, "troy_oz", "gram");
  assert.ok(Math.abs(convertPrice(g, "gram", "troy_oz") - PER_OZ) < 1e-9);
});

test("an avoirdupois ounce costs less than a troy ounce", () => {
  assert.ok(convertPrice(PER_OZ, "troy_oz", "ounce") < PER_OZ);
});

test("a kilogram holds about 32.15 troy ounces", () => {
  const kg = convertPrice(PER_OZ, "troy_oz", "kilogram");
  assert.ok(Math.abs(kg / PER_OZ - 32.1507466) < 1e-6);
});

Kuyum ürünleri fiyatlandırıyorsanız bir sonraki adım saflıktır: ayara göre altın fiyatları yazısı 22 ve 18 ayar fiyatlarını bu dönüşümlerin üzerine inşa ediyor. Veri formatları rehberi ve API dokümantasyonunun birimler bölümü tüm birim değerlerini belgeler; semboller sayfası ise her piyasanın işlem gördüğü birimi gösterir.