API ile Geçmiş Altın ve Gümüş Fiyatları: 25 Yıllık Günlük Veri

Hangi geçmiş veriler mevcut

MetalAPI her sembol ve her gün için açılış, en yüksek, en düşük ve kapanış değerlerini içeren bir günlük çubuk saklar. Altın ve gümüş için bu, 25 yılı aşkın günlük veri demektir: uzun vadeli trendleri grafiğe dökmek, bir fiyatlandırma kuralını geçmişe karşı test etmek ya da eski faturaları o günün fiyatıyla yeniden değerlemek için yeterlidir.

Tüm planlar geçmiş verinin tamamını sorgulayabilir. Planlar yalnızca tek bir aralık isteğinin kaç günü kapsayabileceği konusunda farklılık gösterir. Tarihler UTC'ye göre YYYY-MM-DD formatındadır ve her günün değerleri o günün kapanış fiyatlarıdır. Bir sembolün geçmiş verisinin başladığı tarihten önceki bir tarih 300 (no_results) hatası döndürür.

Geçmiş verilerle çalışmak için dört endpoint vardır: tek bir gün için /historical, bir aralık için /timeframe, iki gün arasındaki hareket için /change ve bir günün mumu için /ohlc. Aşağıdaki bölümler bunları sırayla ele alıyor, ardından üzerine bir grafik eklenmiş küçük bir yerel arşiv oluşturuyor.

Tek bir gün: /historical

Tek bir günün kapanış fiyatlarını almak için tarihi yola yazın. /historical?date=YYYY-MM-DD aynı işi yapar; /yesterday ise bir önceki UTC gününün kısayoludur:

curl "https://metalapi.com/api/v1/2024-01-15?currencies=XAU,XAG" \
  -H "X-API-Key: $METALAPI_KEY"

Yanıt, /latest ile aynı yapıdadır ve ek olarak historical: true içerir. Aşağıdakiler API referansındaki örnek değerlerdir:

{
  "success": true,
  "timestamp": 1705276800,
  "historical": true,
  "date": "2024-01-15",
  "base": "USD",
  "rates": {
    "XAU": 0.0004874244,
    "USDXAU": 2051.6,
    "XAG": 0.0431741646,
    "USDXAG": 23.162
  }
}

USDXAU, bir troy ons altının baz para birimi cinsinden fiyatıdır; XAU ise bunun tersidir. base ve unit her zamanki gibi çalışır; bu nedenle base=EUR&unit=gram, o gün için gram başına euro fiyatını döndürür.

Hafta sonları ve tatiller isteği bozmaz: işlem yapılmayan bir gün için en son işlem gününün kapanış fiyatı döner. Yanıttaki date yine istediğiniz gündür; bu nedenle piyasaların açık olup olmadığını bilmeniz gerekiyorsa kendi tarafınızda bir işlem takvimi tutun. Gelecekteki bir tarih 205 (invalid_date) hatası döndürür.

Tarih aralıkları: /timeframe

Bir seri için /timeframe, her ikisi de dahil olmak üzere start_date ile end_date arasındaki her gün için tarihe göre anahtarlanmış bir kayıt döndürür. /timeseries, yanıtı timeframe: true yerine timeseries: true ile işaretleyen bir takma addır.

curl "https://metalapi.com/api/v1/timeframe?start_date=2026-10-19&end_date=2026-10-23&currencies=XAU" \
  -H "X-API-Key: $METALAPI_KEY"

{
  "success": true,
  "timeframe": true,
  "start_date": "2026-10-19",
  "end_date": "2026-10-23",
  "base": "USD",
  "rates": {
    "2026-10-19": { "XAU": 0.0002403788, "USDXAU": 4160.1 },
    "2026-10-20": { "XAU": 0.0002413943, "USDXAU": 4142.6 },
    "2026-10-21": { "XAU": 0.0002409639, "USDXAU": 4150 },
    "2026-10-22": { "XAU": 0.0002462812, "USDXAU": 4060.4 },
    "2026-10-23": { "XAU": 0.0002495072, "USDXAU": 4007.9 }
  }
}

Tek günlük endpoint'in aksine /timeframe boşlukları doldurmaz. Spot metaller New York saatiyle cuma 17:00'den pazar 17:00'ye kadar işlem görmez; bu nedenle hafta sonları ve piyasa tatilleri sonuçta yer almayabilir. Her takvim günü için bir kayıt olacağını varsaymayın. Altın ve bitcoin gibi farklı işlem takvimlerine sahip sembolleri birlikte kullanıyorsanız bir anahtarı okumadan önce var olup olmadığını kontrol edin.

Tek bir isteğin kapsayabileceği en uzun aralık plana bağlıdır:

Limit iki tarih arasındaki mesafedir; bu nedenle 2025-01-01 ile 2025-01-31 arası Free limitine, 2024-01-01 ile 2024-12-31 arası ise artık yıl olmasına rağmen ücretli plan limitine sığar. Daha uzun bir aralık, bir upgrade_url ile birlikte 207 (timeframe_too_long) hatası döndürür. Her /timeframe çağrısı, kaç gün döndürdüğünden bağımsız olarak bir istek sayılır.

İki tarihi karşılaştırmak: /change

Bir gösterge panelindeki yılbaşından bugüne performans gibi yalnızca iki gün arasındaki harekete ihtiyacınız olduğunda /change, aradaki günleri indirmeden başlangıç kurunu, bitiş kurunu, mutlak değişimi ve yüzde değişimi döndürür:

curl "https://metalapi.com/api/v1/change?start_date=2026-01-02&end_date=2026-10-23&currencies=XAU,XAG" \
  -H "X-API-Key: $METALAPI_KEY"

{
  "success": true,
  "change": true,
  "start_date": "2026-01-02",
  "end_date": "2026-10-23",
  "base": "USD",
  "rates": {
    "XAU": { "start_rate": 0.0002309682, "end_rate": 0.0002495072, "change": 0.000018539, "change_pct": 8.02665 },
    "USDXAU": { "start_rate": 4329.6, "end_rate": 4007.9, "change": -321.7, "change_pct": -7.43025 }
  }
}

Ön ekli anahtarı, yani USDXAU değerini okuyun. Ters anahtar XAU diğer yönde hareket eder; bu nedenle change_pct değerinin işareti ters, büyüklüğü de farklıdır: bu örnekte altın fiyatı %7,43 düşerken ters değer %8,03 yükseldi. Ters değerin yüzdesini fiyat değişimi olarak göstermek, canlıya kolayca kaçabilecek bir hatadır.

/change, /timeframe ile aynı aralık limitlerine sahiptir. /historical gibi, bir tarih hafta sonuna veya tatile denk geldiğinde en son kapanış fiyatını kullanır.

Günlük mumlar: /ohlc

/ohlc, bir günün açılış, en yüksek, en düşük ve kapanış değerlerini her iki yönde döndürür: ons başına dolar cinsinden USDXAU ve ters değer olarak XAU. date gönderilmezse veya date=latest verilirse bugünün o ana kadarki çubuğunu döndürür.

curl "https://metalapi.com/api/v1/ohlc?date=2026-10-23&currencies=XAU" \
  -H "X-API-Key: $METALAPI_KEY"

{
  "success": true,
  "ohlc": true,
  "date": "2026-10-23",
  "base": "USD",
  "rates": {
    "USDXAU": { "open": 4042.2, "high": 4050.2, "low": 3989.1, "close": 4007.9 },
    "XAU": { "open": 0.000247390, "high": 0.000250683, "low": 0.000246901, "close": 0.000249507 }
  }
}

Ters değer bloğunda en yüksek değerin en düşük fiyattan, en düşük değerin ise en yüksek fiyattan geldiğine dikkat edin; çünkü tersini almak sıralamayı da tersine çevirir. Grafikte USDXAU bloğunu kullanın.

Her çağrı tek bir günü kapsar; bu nedenle tam bir yılın mum grafiği, işlem günü başına bir istek gerektirir. Uzun grafikler için /timeframe ile alınan kapanış fiyatları çok daha ucuzdur. /ohlc endpoint'ini son mumlar için ya da güncel fiyatın yanında günün işlem aralığını göstermek için kullanın.

Uzun yıllara yayılan haftalık veya aylık mumlar için çubukları saklanan günlük kapanışlardan da oluşturabilirsiniz: açılış dönemin ilk kapanışı, kapanış son kapanışı, en yüksek ve en düşük ise kapanışların uç değerleridir. Bu çubuklar gün içi en yüksek ve en düşük değerleri yakalamaz; bu yüzden onları kapanışa dayalı olarak etiketleyin. Yine de uzun dönemli grafikler için yeterlidirler.

25 yılı geriye dönük doldurmak: istek başına bir yıl

İstek başına 365 günlük limitle, 2000'den bu yana altın ve gümüşün tüm geçmişi takvim yılı başına bir /timeframe çağrısı gerektirir: 2000'den 2026'ya kadar 27 istek. Bu, her ücretli planın aylık kotasına rahatlıkla sığar. Free planda 30 günlük pencerelerle 300'ü aşkın istek gerekir; bu da planın 100 isteklik aylık kotasının yaklaşık üç katıdır. Bu nedenle Free planda tüm geçmişi doldurmak pratik değildir, ancak birkaç aylık geçmiş için uygundur.

Bu Python betiği yıllara göre sayfalama yapar, dakika başına limiti bekleyerek aşar ve her iki metalin fiyat anahtarlarını SQLite'a yazar. backfill.py olarak kaydedin:

import os
import sqlite3
import time
from datetime import datetime, timezone

import requests

API = "https://metalapi.com/api/v1"
session = requests.Session()
session.headers["X-API-Key"] = os.environ["METALAPI_KEY"]

db = sqlite3.connect("metals.db")
db.execute(
    """create table if not exists daily_close (
         day    text not null,
         symbol text not null,
         base   text not null,
         price  real not null,
         primary key (day, symbol, base)
       )"""
)


def fetch_timeframe(start, end, symbols, base="USD"):
    """start ile end arasındaki (dahil) günlük kapanışlar, tarihe göre anahtarlanmış."""
    while True:
        r = session.get(
            f"{API}/timeframe",
            params={"start_date": start, "end_date": end, "currencies": ",".join(symbols), "base": base},
            timeout=30,
        )
        data = r.json()
        if data.get("success"):
            return data["rates"]
        err = data["error"]
        if err["code"] == 104:  # dakika başına limit: bekle, sonra yeniden dene (ücretlendirilmez)
            time.sleep(int(r.headers.get("Retry-After", "60")))
            continue
        if err["code"] == 300:  # bu pencerede veri yok
            return {}
        raise RuntimeError(f"{err['code']} {err['type']}: {err['info']}")


def store(rates, symbols, base="USD"):
    rows = [
        (day, s, base, values[f"{base}{s}"])
        for day, values in rates.items()
        for s in symbols
        if f"{base}{s}" in values
    ]
    db.executemany("insert or replace into daily_close values (?, ?, ?, ?)", rows)
    db.commit()
    return len(rows)


def backfill(first_year, symbols=("XAU", "XAG"), base="USD"):
    today = datetime.now(timezone.utc).date()
    for year in range(first_year, today.year + 1):
        start = f"{year}-01-01"
        end = min(f"{year}-12-31", today.isoformat())
        n = store(fetch_timeframe(start, end, symbols, base), symbols, base)
        print(f"{year}: {n} rows")


if __name__ == "__main__":
    backfill(2000)

Betiği yeniden çalıştırmak güvenlidir: insert or replace zaten var olan satırların üzerine yazar; böylece yarıda kalan bir doldurma işlemi yeniden başlatılabilir. Gelecekteki bir end_date değeri 205 döndürdüğü için içinde bulunulan yıl, bugünün UTC tarihinde biter. Dakika başına limitler en küçük planlarda en düşüktür (Free planda dakikada 10, Lite'ta 30 istek); betiğin 104 hatasında başarısız olmak yerine Retry-After değerine uymasının nedeni budur.

Betik ters anahtarları değil, fiyatları, yani USDXAU ve USDXAG değerlerini saklar. Geçmiş veriye başka bir para birimi cinsinden ihtiyacınız varsa base gönderin ya da para birimlerinin dolar fiyatlarını da saklayıp aynı günün satırlarından yerel olarak dönüştürün.

Verileri saklamak ve güncellemek

Geçmiş günlerin kapanış fiyatları değişmez; bu nedenle yerel bir kopya, grafik ve raporları sunmanın en ucuz ve en hızlı yoludur. Birkaç kural verilerin doğru kalmasını sağlar:

• Satırları gün, sembol ve baza göre anahtarlayın. Yukarıdaki tablo birincil anahtar olarak (day, symbol, base) kullanır; böylece bir aralığı iki kez çekmek satırları çoğaltmak yerine üzerlerine yazar.
• Ne istediğinizi kaydedin. base değerini ve kullanıyorsanız unit değerini verilerle birlikte saklayın. Gram başına ve ons başına satırları aynı sütunda karıştırmak, grafikteki ani sıçramaların klasik bir nedenidir.
• Günde bir kez tamamlayın. Geriye dönük doldurmanın ardından günde bir istek tabloyu güncel tutar. Son yedi günü çekin; böylece kaçırılan bir çalıştırma veya geç gelen bir kapanış otomatik olarak doldurulur.
• Bugünü geçici kabul edin. Yalnızca içinde bulunulan günün çubuğu hâlâ değişmektedir. Onu arşivin dışında tutun ya da aşağıdaki betiğin yaptığı gibi bir sonraki çalıştırmada üzerine yazın.

from datetime import datetime, timedelta, timezone

from backfill import fetch_timeframe, store

SYMBOLS = ("XAU", "XAG")
today = datetime.now(timezone.utc).date()
start = (today - timedelta(days=7)).isoformat()
end = (today - timedelta(days=1)).isoformat()
print(store(fetch_timeframe(start, end, SYMBOLS), SYMBOLS), "rows updated")

Günde bir istekle güncelleme ayda yaklaşık 30 isteğe mal olur; bu, Free planda bile yer bırakır. Daha büyük arşivler için aynı yaklaşım PostgreSQL, bir Parquet dosyası veya herhangi bir zaman serisi veritabanıyla da çalışır; yalnızca store fonksiyonu değişir.

Geriye dönük doldurulmuş veriler üzerine bir şey inşa etmeden önce onları kontrol edin. Üç kontrol, sorunların çoğunu yakalar:

• Yıl başına satır sayısı. Tamamlanmış her yılda, her metal için kabaca işlem günü başına bir satır olmalıdır. Çok daha az satıra sahip bir yıl, bir isteğin başarısız olduğu veya veri döndürmediği anlamına gelir.
• Boşluklar. Sıradan bir hafta sonu iki kapanış arasında üç gün, uzun bir tatil hafta sonu ise dört gün bırakır. Daha uzun boşluklar incelenmeyi hak eder; o pencereyi yeniden çekmek tek bir isteğe mal olur.
• Sıçramalar. Bir günden diğerine yaklaşık 31 veya 1.000 katlık bir hareket birimlerin karıştığına, sıfıra yakın bir değer ise araya bir ters anahtarın karıştığına işaret eder.

İlk ikisi SQLite'ta kısa sorgulardır:

-- Yıl başına satır: tamamlanmış bir yılda kabaca işlem günü başına bir satır olur
select substr(day, 1, 4) as year, symbol, count(*) as days from daily_close
 where base = 'USD' group by year, symbol order by year, symbol;

-- Saklanan kapanışlar arasında dört günden uzun boşluklar
select symbol, prev_day, day from (
  select symbol, day, lag(day) over (partition by symbol order by day) as prev_day
    from daily_close where base = 'USD'
) where julianday(day) - julianday(prev_day) > 4;

Verileri grafiğe dökmek

Veriler yerel olarak saklandığında grafikler hiçbir istek harcamaz. Bu matplotlib betiği, dolar cinsinden altın fiyatını, bir ons altınla kaç ons gümüş alınabileceğini gösteren altın/gümüş oranıyla birlikte çizer:

import sqlite3
from datetime import date

import matplotlib.dates as mdates
import matplotlib.pyplot as plt

db = sqlite3.connect("metals.db")
rows = db.execute(
    """select g.day, g.price, s.price
         from daily_close g
         join daily_close s on s.day = g.day and s.base = g.base and s.symbol = 'XAG'
        where g.symbol = 'XAU' and g.base = 'USD'
        order by g.day"""
).fetchall()

days = [date.fromisoformat(day) for day, _, _ in rows]
gold = [g for _, g, _ in rows]
ratio = [g / s for _, g, s in rows]

fig, (top, bottom) = plt.subplots(2, 1, sharex=True, figsize=(10, 6))
top.plot(days, gold, linewidth=1)
top.set_ylabel("Gold, USD per troy oz")
bottom.plot(days, ratio, linewidth=1)
bottom.set_ylabel("Gold/silver ratio")
bottom.xaxis.set_major_locator(mdates.YearLocator(base=5))
fig.tight_layout()
fig.savefig("gold-silver.png", dpi=150)

Bir web sitesinde saklanan seriyi kendi backend'inizden sunun ve tarayıcıda çizin. API anahtarınız sunucuda kalır ve sayfa görüntülemeleri kotanızı harcamaz. Kendi endpoint'inizden { day, price } nesnelerinden oluşan bir JSON dizisi okuyan minimal bir Chart.js sayfası:

<canvas id="gold" height="320"></canvas>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/chart.umd.js"></script>
<script>
  // Kendi endpoint'iniz; [{ "day": "2026-10-23", "price": 4007.9 }, ...] döndürür
  fetch("/api/gold-history")
    .then((res) => res.json())
    .then((points) => {
      new Chart(document.getElementById("gold"), {
        type: "line",
        data: {
          labels: points.map((p) => p.day),
          datasets: [{ label: "Gold, USD per troy oz", data: points.map((p) => p.price), pointRadius: 0, borderWidth: 1 }],
        },
        options: {
          animation: false,
          scales: { x: { ticks: { maxTicksLimit: 10 } } },
        },
      });
    });
</script>

Yirmi beş yıllık işlem günleri, seri başına 6.000'den fazla nokta demektir. Yukarıdaki gibi nokta işaretlerini ve animasyonu kapatmak grafiğin akıcı kalmasını sağlar; küçük ekranlarda haftalık kapanışlara indirgemeyi (downsampling) düşünün.

Geçmiş veriler rehberinde JavaScript ile bir aralık yardımcısı ve bir hareketli ortalama örneği bulunur; API dokümantasyonu ise tüm parametreleri listeler. AI asistanlarıyla çalışıyorsanız MetalAPI MCP sunucusu aynı zaman serisini bir sohbetten çekebilir. Anahtarlar, hatalar ve önbellekleme hakkında genel bilgi için Altın fiyatı API rehberi ile başlayın; aralık limitlerini ve kotaları fiyatlandırma sayfasında karşılaştırın.