altinapi

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 18, 2026 License: MIT Imports: 12 Imported by: 0

README

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

Go Reference Go Report Card Go version

altinapi için resmi Go 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 — Struct'lar ve tip-güvenli handler'lar
  • 🦫 Go 1.21+ — Modern Go, generics ile uyumlu
  • 🌐 REST + WebSocket — Tek pakette
  • 🪶 context.Context — Tüm REST çağrıları cancellation destekler
  • 🔄 Otomatik reconnect — Exponential backoff dahil

📥 Kurulum

go get github.com/altinapi/altinapi-go

⚡ Hızlı Başlangıç

REST API — Anlık Fiyat Sorgusu
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/altinapi/altinapi-go"
)

func main() {
    client, err := altinapi.NewClient("hapi_API_KEYINIZ")
    if err != nil {
        log.Fatal(err)
    }
    ctx := context.Background()

    // Tüm fiyatlar (Harem Altın ile aynı veri)
    tumu, err := client.GetAllPrices(ctx)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Toplam sembol: %d\n", len(tumu.Data))

    // Kategori bazlı — sadece döviz
    doviz, _ := client.GetPricesByCategory(ctx, altinapi.CategoryDoviz)
    for _, f := range doviz.Data {
        fmt.Printf("%s: %v / %v\n", f.Symbol, f.Bid, f.Ask)
    }

    // Tek sembol — gram altın
    altin, _ := client.GetPrice(ctx, "ALTIN")
    fmt.Printf("Altın: %v – %v TL/gram\n", altin.Bid, altin.Ask)

    // Sarrafiye — çeyrek altın
    ceyrek, _ := client.GetPrice(ctx, "CEYREK_YENI")
    fmt.Printf("Çeyrek altın: %v – %v TL\n", ceyrek.Bid, ceyrek.Ask)
}
WebSocket — Gerçek Zamanlı Akış
package main

import (
    "fmt"
    "os"
    "os/signal"
    "syscall"

    "github.com/altinapi/altinapi-go"
)

func main() {
    client, _ := altinapi.NewClient("hapi_API_KEYINIZ")

    client.OnConnect(func() {
        fmt.Println("✅ Bağlandı")
        client.Subscribe([]string{"USDTRY", "ALTIN", "CEYREK_YENI"})
    })

    client.OnPrices(altinapi.EventPricesSnapshot, func(fiyatlar []altinapi.Price) {
        fmt.Printf("İlk snapshot: %d sembol\n", len(fiyatlar))
    })

    client.OnPrices(altinapi.EventPricesUpdate, func(guncellemeler []altinapi.Price) {
        for _, f := range guncellemeler {
            // Harem Altın değişir değişmez sen de bilirsin
            fmt.Printf("%s: %v / %v\n", f.Symbol, f.Bid, f.Ask)
        }
    })

    client.OnDataStale(func() { fmt.Println("⚠️  Kaynak bağlantısı koptu") })
    client.OnDataLive(func() { fmt.Println("✅ Kaynak bağlantısı geri geldi") })

    client.Connect()

    sigs := make(chan os.Signal, 1)
    signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)
    <-sigs
    client.Disconnect()
}

🏷️ Sembol Kategorileri

Kategori (sabit) Değer Örnekler
CategoryDoviz DOVIZ USDTRY, EURTRY, GBPTRY, CHFTRY
CategoryMaden MADEN ALTIN, XAUUSD, GUMUSD, PLATIN, PALADYUM
CategoryGramAltin GRAM ALTIN 5 GR GRAM ALTIN, 10 GR GRAM ALTIN, ...
CategorySarrafiye SARRAFIYE CEYREK_YENI, YARIM_YENI, TEK_YENI, ATA_YENI, AYAR22
CategoryParite PARITE EURUSD, GBPUSD, USDJPY

Tüm sembol listesi →

📚 Kullanım Senaryoları

altinapi şu senaryolarda kullanılır:

  • Mikroservis backend'leri — gRPC veya HTTP servisinde anlık altın/döviz endpoint'i
  • Trading bot'ları — Goroutine'lerde paralel arbitraj/fiyat takibi
  • CLI araçları — Cobra/Viper ile altın/döviz CLI komutları
  • Web scraper alternatifi — Daha güvenilir ve stabil veri kaynağı
  • Background worker'lar — k6, cron job'lar ile periyodik fiyat raporu
  • Kubernetes operator'leri — Anlık fiyat metric'lerini ConfigMap/Secret'a yazma
  • gRPC gateway — Mobil/web istemciler için stream endpoint

📖 API Referansı

NewClient(apiKey string, opts ...Option) (*Client, error)
Opsiyon Açıklama Varsayılan
WithBaseURL(string) REST base URL override https://altinapi.com/api/v1
WithSocketURL(string) WebSocket URL override https://altinapi.com
WithTimeout(time.Duration) REST request timeout 10 * time.Second
WithHTTPClient(*http.Client) Özel HTTP client (testler için) —
REST Metotları
Metot Dönüş Açıklama
GetAllPrices(ctx) *PricesResponse, error Tüm sembolleri getirir
GetPricesByCategory(ctx, category) *PricesResponse, error Kategori bazlı filtre
GetPrice(ctx, symbol) *Price, error Tek sembol fiyatı
WebSocket Metotları
Metot Açıklama
Connect() error Socket.io bağlantısı açar
Disconnect() Bağlantıyı kapatır
Subscribe([]string) error Belirli sembollere abone olur
Unsubscribe([]string) error Aboneliği iptal eder
OnConnect(func()) Bağlantı kurulduğunda
OnDisconnect(func()) Bağlantı koptuğunda
OnConnectError(func(error)) Bağlantı hatasında
OnPrices(event, func([]Price)) snapshot/update için tip-güvenli handler
OnDataStale(func()) Kaynak bağlantısı koptu
OnDataLive(func()) Kaynak yeniden bağlandı
IsConnected() bool Bağlantı durumu
WebSocket Eventleri (sabitler)
Sabit Veri Ne zaman
EventConnect — Bağlantı kuruldu
EventDisconnect — Bağlantı kapandı
EventPricesSnapshot []Price Bağlantı anında — tüm güncel fiyatlar
EventPricesUpdate []Price Fiyat değişiminde
EventDataStale — Kaynak bağlantısı koptu
EventDataLive — Kaynak yeniden bağlandı
EventConnectError error Bağlantı hatası

⚠️ Hata Yönetimi

import "errors"

altin, err := client.GetPrice(ctx, "GECERSIZ")
if err != nil {
    var apiErr *altinapi.Error
    if errors.As(err, &apiErr) {
        fmt.Printf("[%d] %s\n", apiErr.StatusCode, apiErr.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 →

📂 Örnekler

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

ALTINAPI_KEY=hapi_xxx go run ./examples/rest
ALTINAPI_KEY=hapi_xxx go run ./examples/websocket

🧪 Test

go test ./...

❓ 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.

"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.

Go modülünü gRPC servisinde kullanabilir miyim?

Evet. REST çağrıları context.Context desteği sayesinde gRPC handler içinde doğrudan kullanılabilir; WebSocket akışını ayrı bir goroutine'de tutup channel ile gRPC stream'e push edebilirsiniz.

Concurrent kullanım güvenli mi?

Evet — REST çağrıları goroutine-safe'tir. WebSocket için handler'lar sync.Mutex ile korunur.

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 · Harem Altın benzeri API · Harem Altın alternatif API · Harem API · Türkiye finans API · Go altın API · Go gold API · golang gold price API · Turkish gold price API · websocket altın akışı · go socket.io altın

🤝 Katkıda Bulunma

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

📄 Lisans

MIT © altinapi

🔗 Bağlantılar

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.

Documentation

Index

Constants

View Source 
const (
	// DefaultBaseURL — REST API kök adresi.
	DefaultBaseURL = "https://altinapi.com/api/v1"
	// DefaultSocketURL — Socket.IO kök adresi.
	DefaultSocketURL = "https://altinapi.com"
	// DefaultTimeout — REST istekleri için varsayılan zaman aşımı.
	DefaultTimeout = 10 * time.Second
	// Version — SDK sürümü.
	Version = "0.1.0"
)
View Source 
const (
	// EventConnect — bağlantı kuruldu.
	EventConnect = "connect"
	// EventDisconnect — bağlantı kapandı.
	EventDisconnect = "disconnect"
	// EventConnectError — bağlantı hatası.
	EventConnectError = "connect_error"
	// EventPricesSnapshot — bağlantı anında tüm güncel fiyatlar.
	EventPricesSnapshot = "prices:snapshot"
	// EventPricesUpdate — fiyat değişimi.
	EventPricesUpdate = "prices:update"
	// EventDataStale — kaynak bağlantısı koptu, veri eski olabilir.
	EventDataStale = "data:stale"
	// EventDataLive — kaynak yeniden bağlandı.
	EventDataLive = "data:live"
)

Sunucu tarafından yayınlanan WebSocket olayları.

Variables

This section is empty.

Functions

This section is empty.

Types

type Category 

type Category string

Category — altinapi'nin tanımladığı sembol kategorileri. String tipinde tutulur; sabit değerler aşağıda. 

const (
	// CategoryDoviz — döviz kurları (USDTRY, EURTRY, ...).
	CategoryDoviz Category = "DOVIZ"
	// CategoryMaden — değerli metaller (ALTIN, XAUUSD, GUMUSD, PLATIN, PALADYUM).
	CategoryMaden Category = "MADEN"
	// CategoryParite — uluslararası pariteler (EURUSD, GBPUSD, ...).
	CategoryParite Category = "PARITE"
	// CategoryGramAltin — ağırlığa göre altın (5/10/20/50/100 gr).
	CategoryGramAltin Category = "GRAM ALTIN"
	// CategorySarrafiye — Türk sarrafiye altınları (çeyrek, yarım, tam, ata).
	CategorySarrafiye Category = "SARRAFIYE"
)

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client — altinapi REST + WebSocket istemcisi.

REST çağrıları thread-safe'dir. WebSocket için Connect/On/Subscribe sırası önemli değildir — handler'lar connect'ten önce kaydedilebilir.

func NewClient 

func NewClient(apiKey string, opts ...Option) (*Client, error)

NewClient — yeni bir altinapi istemcisi kurar. 

c := altinapi.NewClient("hapi_xxx")
c := altinapi.NewClient("hapi_xxx", altinapi.WithTimeout(5*time.Second))

func (*Client) Connect 

func (c *Client) Connect() error

Connect — Socket.IO bağlantısını açar. Bloklayıcı değildir; goroutine'de dinler. Birden çok kez çağrılırsa idempotent davranır.

func (*Client) Disconnect 

func (c *Client) Disconnect()

Disconnect — bağlantıyı kapatır.

func (*Client) GetAllPrices 

func (c *Client) GetAllPrices(ctx context.Context) (*PricesResponse, error)

GetAllPrices — tüm sembollerin (250+) güncel fiyatları.

func (*Client) GetPrice 

func (c *Client) GetPrice(ctx context.Context, symbol string) (*Price, error)

GetPrice — tek bir sembolün güncel fiyatı.

func (*Client) GetPricesByCategory 

func (c *Client) GetPricesByCategory(ctx context.Context, category Category) (*PricesResponse, error)

GetPricesByCategory — kategori bazlı fiyat listesi. category: DOVIZ, MADEN, PARITE, GRAM ALTIN, SARRAFIYE.

func (*Client) IsConnected 

func (c *Client) IsConnected() bool

IsConnected — anlık bağlantı durumu.

func (*Client) OnConnect 

func (c *Client) OnConnect(handler func())

OnConnect — bağlantı kurulduğunda çağrılır.

func (*Client) OnConnectError 

func (c *Client) OnConnectError(handler func(error))

OnConnectError — bağlantı hatası olduğunda çağrılır.

func (*Client) OnDataLive 

func (c *Client) OnDataLive(handler func())

OnDataLive — kaynak yeniden bağlandığında çağrılır.

func (*Client) OnDataStale 

func (c *Client) OnDataStale(handler func())

OnDataStale — kaynak bağlantısı koptuğunda çağrılır.

func (*Client) OnDisconnect 

func (c *Client) OnDisconnect(handler func())

OnDisconnect — bağlantı koptuğunda çağrılır.

func (*Client) OnPrices 

func (c *Client) OnPrices(event string, handler func([]Price))

OnPrices — prices:snapshot veya prices:update için tip-güvenli handler kaydı. Payload normalization burada yapılır: server Price veya {data: Price} gönderebilir; her iki durumda da handler'a düz []Price geçer.

func (*Client) Subscribe 

func (c *Client) Subscribe(symbols []string) error

Subscribe — belirli sembollere abone ol. Çağrılmazsa tüm güncellemeler gelir.

func (*Client) Unsubscribe 

func (c *Client) Unsubscribe(symbols []string) error

Unsubscribe — daha önce abone olunan sembollerden ayrıl.

type Error 

type Error struct {
	Message    string
	StatusCode int
	// Cause altta yatan hatayı tutar (errors.Is/As ile kullanılabilir).
	Cause error
}

Error — altinapi SDK tarafından döndürülen hata. StatusCode 0 ise ağ hatası, aksi halde HTTP durum kodu.

func (*Error) Error 

func (e *Error) Error() string

Error — error interface implementasyonu.

func (*Error) Unwrap 

func (e *Error) Unwrap() error

Unwrap — errors.Is / errors.As desteği.

type Option 

type Option func(*Client)

Option — Client kurarken kullanılan fonksiyonel seçenek.

func WithBaseURL 

func WithBaseURL(u string) Option

WithBaseURL — REST baseUrl override.

func WithHTTPClient 

func WithHTTPClient(h *http.Client) Option

WithHTTPClient — özel *http.Client kullan (testlerde yararlı).

func WithSocketURL 

func WithSocketURL(u string) Option

WithSocketURL — WebSocket URL override.

func WithTimeout 

func WithTimeout(d time.Duration) Option

WithTimeout — REST timeout override.

type Price 

type Price struct {
	Symbol      string  `json:"symbol"`
	Category    string  `json:"category"`
	Bid         float64 `json:"bid"`
	Ask         float64 `json:"ask"`
	Timestamp   string  `json:"timestamp"` // ISO 8601
	Description string  `json:"description,omitempty"`
	CreatedAt   string  `json:"created_at,omitempty"`
}

Price — tek bir sembol için fiyat kaydı.

API yanıtının JSON şekli ile birebir eşleşir. omitempty alanları (Description, CreatedAt) server göndermezse boş kalır.

type PricesResponse 

type PricesResponse struct {
	Data      []Price `json:"data"`
	UpdatedAt string  `json:"updatedAt"`
	Stale     bool    `json:"stale"`
}

PricesResponse — /prices ve /prices/category endpoint'lerinin yanıt şekli.

Source Files

View all Source files

Directories

Path Synopsis
examples
rest command
websocket command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.