JSON yanıtında hangi alanlar var?
Yanıtın kökünde source (kaynak), count (kalem sayısı), data (kalem listesi), lastUpdate (verinin yazıldığı an), dataAgeMs (verinin yaşı, ms) ve stale (bayatlık) alanları bulunur. data listesindeki her kalemde `title` (sembol adı), `buy` (alış) ve `sell` (satış) alanları döner; birim ve para birimi için isteğe birim=1 ekleyebilirsiniz.
Alış ve satış ayrı gelir çünkü kuyumculuk pratiğinde ikisi farklı kullanılır: müşteriden alırken alış, satarken satış fiyatı esas alınır. Tek bir 'fiyat' alanı bu ayrımı kaybettirir.
Zaman damgası kalem bazında değil, yanıt bazında gelir: lastUpdate ISO 8601 biçiminde UTC zamandır ve dataAgeMs verinin kaç milisaniye önce tazelendiğini gösterir. Verinin tazeliğini ölçmek için bu alanları kullanın; stale alanı true ise veri 15 dakikadan eskidir.
Sembol adları ve takma adlar
Sembol adlandırması kaynaktan kaynağa değişebilir. Bir kaynak 'GRAM ALTIN' derken diğeri 'GRAMALTIN' veya 'HAS ALTIN' diyebilir. API tarafında takma ad çözümlemesi yapılır, böylece hangi yazımı gönderirseniz gönderin doğru kalemi alırsınız.
Kodunuzda sembolü sabit string olarak gömmek yerine bir eşleme tablosu tutun. Kaynak değiştirdiğinizde tek yerden güncellersiniz.
Ziynet kalemlerinde (çeyrek, yarım, tam) eski ve yeni ayrımı olabilir. Hangi kalemi kullandığınızı ürün kartınızda net tutun.
PHP ile altın fiyatı çekme
PHP tarafında `curl` veya `file_get_contents` yeterlidir. Zaman aşımı süresini mutlaka belirleyin; varsayılan davranış isteğinizi dakikalarca bekletebilir.
Yanıtı `json_decode` ile diziye çevirdikten sonra beklediğiniz alanların varlığını kontrol edin. Kaynak tarafında bir değişiklik olursa kodunuz uyarı üretmeli, sessizce sıfır fiyat yazmamalı.
Laravel kullanıyorsanız `Http::timeout(10)->get(...)` kalıbı hem okunaklı hem güvenlidir; yanıtı `Cache::remember` ile 5-10 saniye saklayın.
Python ve JavaScript örnekleri
Python'da `requests` kütüphanesi en pratik yoldur. `timeout` parametresini vermeyi unutmayın ve `raise_for_status()` ile HTTP hatalarını yakalayın.
Node.js tarafında `fetch` veya `axios` kullanılabilir. Sunucu tarafında çalıştığınızdan emin olun; tarayıcıda anahtar açığa çıkar.
Her iki dilde de yanıtı doğrudan ekrana basmayın; önce şema doğrulaması yapın. Eksik alan gelirse son geçerli kopyayı kullanmak daha güvenlidir.
Sık yapılan ayrıştırma hataları
Ondalık ayırıcı karışıklığı en yaygın hatadır. Hasfiyat API buy ve sell değerlerini 6.421,99 gibi Türkçe biçimli metin olarak döndürür: nokta binlik, virgül ondalık ayırıcıdır. Hesaplamadan önce noktaları silip virgülü noktaya çevirerek sayıya dönüştürün; aksi hâlde değer bin kat küçük ya da hatalı okunur.
Sayıyı string olarak saklamak da sık görülen bir hatadır. Karşılaştırma ve toplama işlemleri beklenmedik sonuç verir. Veriyi aldığınız anda sayıya çevirin.
Zaman damgasını yerel saate çevirirken zaman dilimini atlamayın. Sunucunuz UTC çalışıyorsa ve siz +03:00 bekliyorsanız üç saatlik hayali bir gecikme görürsünüz.
Üretimde JSON API kullanırken
Yanıt boyutu küçüktür ama istek sayısı yüksek olabilir. Tek sembol gerekiyorsa tüm listeyi çekmek yerine sembol bazlı ucu kullanın.
Gzip sıkıştırmasını açık tutun; bant genişliğinden tasarruf sağlar.
Uçların tam referansı ve güncel örnekler için [dokümantasyon](/docs) sayfasına bakabilirsiniz.
Sık sorulan sorular
JSON yanıtındaki 'lastUpdate' alanı hangi biçimde geliyor?
ISO 8601 biçiminde, UTC zamanı olarak gelir (ör. 2026-10-25T20:26:17.553Z). Aynı bilgi X-Data-Last-Update yanıt başlığında da bulunur; dataAgeMs alanı ise verinin kaç milisaniye önce tazelendiğini doğrudan verir. Kendi eşiğinizi aşan yanıtları bayat olarak işaretleyebilirsiniz.
Alış ve satış fiyatı neden ayrı?
Kuyumculukta müşteriden alım ve müşteriye satış farklı fiyatlarla yapılır. Tek bir fiyat alanı bu ayrımı kaybettirir ve yanlış hesaplamaya yol açar.
Sembol adını yanlış yazarsam ne olur?
API takma ad çözümlemesi yapar; yaygın yazım farklılıkları otomatik eşlenir. Liste ucunda (/api/prices?symbols=...) tanınmayan sembol yanıta eklenmez, tek sembol ucunda (/api/prices/{sembol}) ise 404 ve "Symbol not found" mesajı döner. Geçerli sembollerin tam listesini dokümantasyondaki sembol tablosundan görebilirsiniz.
Yanıtı doğrudan veritabanına yazabilir miyim?
Yazabilirsiniz ancak şema doğrulaması yapmadan yazmayın. Kaynakta bir değişiklik olduğunda eksik veya hatalı kayıt oluşmasını engellersiniz. Beklenen alanların varlığını ve sayısal alanların türünü kontrol eden basit bir doğrulama katmanı yeterlidir.
Fiyatları ne kadar önbellekte tutmalıyım?
Vitrin ekranı gibi kritik yerlerde 3-5 saniye, ürün fiyatı güncelleme gibi işlerde 30-60 saniye çoğu senaryo için yeterlidir. Kotanızı ciddi biçimde korur.
Canlı altın & döviz verisine hemen bağlanın
Dakikalar içinde REST veya WebSocket ile gerçek zamanlı fiyat akışına başlayın.