altinapi — Türkiye Altın & Döviz Fiyat API'si (Python SDK)

altinapi için resmi Python SDK

Gerçek zamanlı altın fiyatları, döviz kurları, gümüş, platin, paladyum ve sarrafiye verisi — REST API ve WebSocket ile.

🎯 Harem Altın ile Birebir Aynı Fiyat Verisi

altinapi, Harem Altın ile aynı veri sağlayıcısından beslenir. Bu sayede uygulamanızda gösterdiğiniz fiyatlar, Harem Altın'da görünen fiyatlarla %100 örtüşür.

⚖️ Yasal not: altinapi bağımsız bir servistir. Harem Altın ile ortaklığı, iştiraki veya organik bir bağı yoktur. "Harem Altın" tescilli bir markadır; burada yalnızca veri kaynağının aynılığını belirtmek amacıyla karşılaştırma yapılmaktadır.

🔑 Ücretsiz API key al →

🚀 Niye altinapi?

	altinapi	Diğer altın fiyat API'leri
Veri kaynağı	Harem Altın ile aynı feed	Genelde LBMA / international ons
Sarrafiye desteği	✅ Çeyrek, yarım, tam, ata, gremese	❌ Yok
22/14 ayar	✅ Var	❌ Yok
Gram altın (5/10/20/50/100 gr)	✅ Var	❌ Yok
Türk lirası pariteleri	✅ 15+ döviz	⚠️ Sınırlı
Gecikme	<1 saniye	5-60 saniye (REST polling)
WebSocket	✅ Socket.io	⚠️ Genellikle yok
Fiyatlandırma	$0 - $99/ay	$50 - $500/ay

📦 Özellikler

🥇 250+ sembol — Altın (gram & ons), gümüş, platin, paladyum, sarrafiye, döviz, parite
⚡ <1 saniye gecikme — Socket.io WebSocket ile anlık güncellemeler
🔒 Tam tip desteği — TypedDict ile mypy / Pyright uyumlu
🐍 Python 3.8+ — CPython, PyPy desteği
🌐 REST + WebSocket — Tek pakette
🪶 Hafif — Sadece requests + python-socketio bağımlılığı

📥 Kurulum

pip install altinapi

⚡ Hızlı Başlangıç

REST API — Anlık Fiyat Sorgusu

from altinapi import AltinapiClient

client = AltinapiClient(api_key="hapi_API_KEYINIZ")

# Tüm fiyatlar (Harem Altın ile aynı veri)
tumu = client.get_all_prices()
print(f"Toplam sembol: {len(tumu['data'])}")

# Kategori bazlı — sadece döviz
doviz = client.get_prices_by_category("DOVIZ")
for f in doviz["data"]:
    print(f"{f['symbol']}: {f['bid']} / {f['ask']}")

# Tek sembol — gram altın
altin = client.get_price("ALTIN")
print(f"Altın: {altin['bid']} – {altin['ask']} TL/gram")

# Sarrafiye — çeyrek altın
ceyrek = client.get_price("CEYREK_YENI")
print(f"Çeyrek altın: {ceyrek['bid']} – {ceyrek['ask']} TL")

WebSocket — Gerçek Zamanlı Akış

from altinapi import AltinapiClient

client = AltinapiClient(api_key="hapi_API_KEYINIZ")

@client.on("connect")
def on_connect():
    print("✅ Bağlandı")
    client.subscribe(["USDTRY", "ALTIN", "CEYREK_YENI"])

@client.on("prices:snapshot")
def on_snapshot(fiyatlar):
    print(f"İlk snapshot: {len(fiyatlar)} sembol")

@client.on("prices:update")
def on_update(guncellemeler):
    for f in guncellemeler:
        # Harem Altın değişir değişmez sen de bilirsin
        print(f"{f['symbol']}: {f['bid']} / {f['ask']}")

@client.on("data:stale")
def on_stale():
    print("⚠️  Kaynak bağlantısı koptu")

@client.on("data:live")
def on_live():
    print("✅ Kaynak bağlantısı geri geldi")

client.connect()
client.wait()  # Ctrl+C ile çık

🏷️ Sembol Kategorileri

Kategori	Açıklama	Örnekler
`DOVIZ`	Döviz kurları	`USDTRY`, `EURTRY`, `GBPTRY`, `CHFTRY`
`MADEN`	Değerli metaller	`ALTIN`, `XAUUSD`, `GUMUSD`, `PLATIN`, `PALADYUM`
`GRAM ALTIN`	Ağırlığa göre altın	`5 GR GRAM ALTIN`, `10 GR GRAM ALTIN`, ...
`SARRAFIYE`	Türk sarrafiye altınları	`CEYREK_YENI`, `YARIM_YENI`, `TEK_YENI`, `ATA_YENI`, `AYAR22`
`PARITE`	Uluslararası pariteler	`EURUSD`, `GBPUSD`, `USDJPY`

Tüm sembol listesi →

📚 Kullanım Senaryoları

altinapi şu senaryolarda kullanılır:

Fintech uygulamaları — Anlık altın ve döviz fiyatlarını kullanıcıya göstermek
Kuyumcu yazılımları — Stok yönetiminde gerçek zamanlı altın fiyatı kullanmak
Django / Flask backend'leri — Web uygulamalarına canlı fiyat entegrasyonu
Otomatik ticaret botları — Algorithmic trading için anlık fiyat akışı
Veri analizi / Jupyter — pandas ile altın & döviz veri çalışmaları
Dashboard'lar — Streamlit, Dash, Plotly ile canlı veri panoları
WhatsApp / Telegram botları — Kullanıcılara güncel altın/döviz fiyatı bildirimi
Raporlama scriptleri — Cron job ile günlük altın fiyat raporu

📖 API Referansı

`AltinapiClient(api_key, base_url=..., socket_url=..., timeout=...)`

Parametre	Tip	Varsayılan	Zorunlu
`api_key`	`str`	—	✅
`base_url`	`str`	`https://altinapi.com/api/v1`
`socket_url`	`str`	`https://altinapi.com`
`timeout`	`float` (sn)	`10.0`

REST Metotları

Metot	Dönüş	Açıklama
`get_all_prices()`	`PricesResponse`	Tüm sembolleri getirir
`get_prices_by_category(category)`	`PricesResponse`	Kategori bazlı filtre
`get_price(symbol)`	`Price`	Tek sembol fiyatı

WebSocket Metotları

Metot	Açıklama
`connect()`	Socket.io bağlantısı açar
`disconnect()`	Bağlantıyı kapatır
`subscribe(symbols)`	Belirli sembollere abone olur
`unsubscribe(symbols)`	Aboneliği iptal eder
`on(event, handler)`	Sunucu eventlerini dinler (decorator olarak da kullanılır)
`off(event)`	Dinleyiciyi kaldırır
`is_connected()`	Bağlantı durumunu döner
`wait()`	Bloklayıcı dinleme (Ctrl+C ile çıkış)

WebSocket Eventleri

Event	Veri	Ne zaman
`connect`	—	Bağlantı kuruldu
`disconnect`	—	Bağlantı kapandı
`prices:snapshot`	`List[Price]`	Bağlantı anında — tüm güncel fiyatlar
`prices:update`	`List[Price]`	Fiyat değişiminde
`data:stale`	—	Kaynak bağlantısı koptu (veri eski)
`data:live`	—	Kaynak yeniden bağlandı
`connect_error`	`Error`	Bağlantı hatası

⚠️ Hata Yönetimi

from altinapi import AltinapiClient, AltinapiError

client = AltinapiClient(api_key="hapi_xxx")
try:
    client.get_price("GECERSIZ_SEMBOL")
except AltinapiError as err:
    print(f"[{err.status_code}] {err.message}")

Kod	Anlamı
`401`	API key eksik veya geçersiz
`403`	Abonelik aktif değil
`404`	Sembol veya kategori bulunamadı
`429`	Rate limit aşıldı
`503`	Kaynak bağlantısı kesildi (eski veri)

💰 Plan Limitleri

Plan	REST	WebSocket bağlantı
Ücretsiz Deneme	30 / ay	—
Starter	30 / dakika	—
Pro	60 / dakika	3
Enterprise	Özel	10

Fiyatlandırma →

🔧 Tip Desteği

from altinapi import AltinapiClient
from altinapi.types import Price, PricesResponse, Category

def fiyat_isle(f: Price) -> None:
    # f["symbol"], f["category"], f["bid"], f["ask"], f["timestamp"]
    ...

kategori: Category = "DOVIZ"  # Literal — yanlış yazarsa mypy uyarır

📂 Örnekler

Çalıştırılabilir örnekler /examples klasöründe:

rest.py — REST API kullanımı
websocket.py — gerçek zamanlı akış

ALTINAPI_KEY=hapi_xxx python examples/rest.py
ALTINAPI_KEY=hapi_xxx python examples/websocket.py

🧪 Test

pip install -e ".[dev]"
pytest

❓ Sık Sorulan Sorular

Bu Harem Altın'ın resmi API'si mi?

Hayır. altinapi bağımsız bir servistir. Harem Altın ile ortaklığı, iştiraki veya organik bir bağı yoktur. Fiyatlar birebir örtüşür çünkü aynı veri sağlayıcısından beslenir — bu teknik bir tesadüf değil, kullandığımız upstream data feed'in Harem Altın'ın kullandığı feed ile aynı kaynaktan gelmesi sebebiyledir.

"Harem Altın API'si" arıyorum, bu uygun mu?

altinapi, "Harem Altın API'si" arayan geliştiriciler için bağımsız bir alternatif olarak konumlandırılır. Harem Altın'ın kendisi geliştiricilere açık resmi bir API sunmadığı için, aynı fiyat verisine ihtiyaç duyan uygulamalar altinapi'yi kullanır.

SDK'yı kullanmak için ödeme yapmam gerek mi?

Hayır. Ücretsiz deneme planı 30 istek/ay sunar — entegrasyonu test etmek için yeterli. WebSocket erişimi Pro+ planlarda mevcut.

Veri ne kadar günceldir?

Fiyat değişikliklerinin sunucumuza ulaşması ile size iletilmesi arasındaki gecikme 1 saniyenin altındadır. WebSocket kullanırsanız yeni fiyat anında push edilir; REST kullanırsanız her sorguda son fiyatı alırsınız.

Async / `asyncio` desteği var mı?

Şu anki sürüm sync API sunar (requests + python-socketio sync client). Async ihtiyacınız varsa asyncio.to_thread() ile sarabilirsiniz; roadmap'te native async client çalışması var.

Django / Flask / FastAPI ile çalışır mı?

Evet — sıradan bir Python paketidir, framework agnostik. WebSocket'i ayrı bir thread veya worker'da çalıştırmanız önerilir.

TCMB resmi kurları da var mı?

Şu an feed'imizde TCMB resmi kurları yer almıyor. İhtiyacınıza göre custom plan talep edebilirsiniz: support@altinapi.com

🏷️ Bu Paketin Aranabilirliği

altinapi paketi şu aramalar için tasarlanmıştır:

altın fiyat API · altın fiyatları API · gram altın API · çeyrek altın API · sarrafiye API · döviz kuru API · döviz fiyat API · USDTRY API · EURTRY API · gerçek zamanlı altın fiyat · canlı altın fiyat API · Türkiye altın API · ons altın API · gümüş fiyat API · platin fiyat API · paladyum fiyat API · kuyumcu yazılımı API · altın takip uygulaması · Harem Altın benzeri API · Harem Altın alternatif API · Harem API · Türkiye finans API · Python altın API · Python gold API · Turkish gold price API · websocket altın akışı

🤝 Katkıda Bulunma

Issue ve pull request'leriniz için: github.com/altinapi/altinapi-python

📄 Lisans

MIT © altinapi

🔗 Bağlantılar

🌐 Web sitesi: altinapi.com
📖 API Dokümantasyonu: altinapi.com/docs
🔑 Dashboard: altinapi.com/dashboard
📊 Durum: altinapi.com/status
💬 Destek: support@altinapi.com

Yasal Bildirim: altinapi bağımsız bir hizmettir. "Harem Altın" tescilli bir markadır ve bu pakette yalnızca veri kaynağının aynılığını belirtmek amacıyla — karşılaştırma ve bilgilendirme amaçlı (nominative fair use) — kullanılmıştır. Marka sahibi ile herhangi bir ortaklık, iştirak veya destekleme ilişkisi yoktur.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
altinapi		altinapi
examples		examples
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

altinapi — Türkiye Altın & Döviz Fiyat API'si (Python SDK)

🎯 Harem Altın ile Birebir Aynı Fiyat Verisi

🚀 Niye altinapi?

📦 Özellikler

📥 Kurulum

⚡ Hızlı Başlangıç

REST API — Anlık Fiyat Sorgusu

WebSocket — Gerçek Zamanlı Akış

🏷️ Sembol Kategorileri

📚 Kullanım Senaryoları

📖 API Referansı

AltinapiClient(api_key, base_url=..., socket_url=..., timeout=...)

REST Metotları

WebSocket Metotları

WebSocket Eventleri

⚠️ Hata Yönetimi

💰 Plan Limitleri

🔧 Tip Desteği

📂 Örnekler

🧪 Test

❓ Sık Sorulan Sorular

Bu Harem Altın'ın resmi API'si mi?

"Harem Altın API'si" arıyorum, bu uygun mu?

SDK'yı kullanmak için ödeme yapmam gerek mi?

Veri ne kadar günceldir?

Async / asyncio desteği var mı?

Django / Flask / FastAPI ile çalışır mı?

TCMB resmi kurları da var mı?

🏷️ Bu Paketin Aranabilirliği

🤝 Katkıda Bulunma

📄 Lisans

🔗 Bağlantılar

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`AltinapiClient(api_key, base_url=..., socket_url=..., timeout=...)`

Async / `asyncio` desteği var mı?

Packages