Geliştirici

API Dokümantasyonu

HaldeFiyat API'si REST tabanlıdır, JSON döndürür ve kimlik doğrulama gerektirmeyen endpoint'ler için API anahtarı gerekmez.

Base URL

https://haldefiyat.com/api/v1

Format

JSON (UTF-8)

Rate Limit

600/dk · anahtarsız

Ticari & Yüksek Hacim

Yoğun kullanım için API anahtarı alın

Anahtarsız erişim, IP başına 600/dk ile ücretsizdir. Ticari kullanım, yüksek hacimli entegrasyon veya garantili kota için X-API-Key ile daha yüksek günlük limit sunuyoruz. Ücretsiz anahtar hesap içinden oluşturulur; Pro tier manuel onaylanır.

API Anahtarı Oluştur →Pro / Premium

Fiyat Verileri

Hal fiyatlarını sorgulama, filtreleme ve dışa aktarma.

GET/pricesCache: 5 dakika

Fiyat listesini döndürür. Şehir, kategori, tarih ve ürün bazında filtrelenebilir.

Parametreler

İsim	Tür	Zorunlu	Açıklama
city	string	hayır	Şehir adı veya kodu (örn. istanbul)
product	string	hayır	Ürün slug'ı (örn. domates)
category	string	hayır	Kategori slug'ı (örn. sebze)
range	string	hayır	Geçmiş penceresi, ör. 7d / 30d / 365d
latestOnly	boolean	hayır	Her ürün/hal için yalnız son kaydı getirir
page	number	hayır	Sayfa no (varsayılan: 1)
limit	number	hayır	Sayfa boyutu (maks. 100)

Örnek İstek

curl "https://haldefiyat.com/api/v1/prices?city=istanbul&product=domates&limit=5"

Örnek Yanıt

{
  "items": [
    {
      "id": "...",
      "marketName": "İstanbul Büyükçekmece Hali",
      "productName": "Domates",
      "minPrice": "8.50",
      "maxPrice": "12.00",
      "avgPrice": "10.25",
      "unit": "kg",
      "recordedDate": "2026-04-21",
      "sourceName": "Resmi kaynak",
      "isStale": false,
      "qualityFlags": []
    }
  ],
  "meta": {
    "total": 142,
    "page": 1,
    "limit": 5,
    "latestRecordedDate": "2026-04-21"
  }
}

GET/prices/trendingCache: 10 dakika

Son 7 günde en çok işlem gören ürünlerin fiyat özeti.

Parametreler

İsim	Tür	Zorunlu	Açıklama
limit	number	hayır	Sonuç sayısı (varsayılan: 20)

Örnek İstek

curl "https://haldefiyat.com/api/v1/prices/trending?limit=10"

Örnek Yanıt

[
  {
    "productSlug": "domates",
    "productName": "Domates",
    "avgPrice": "10.25",
    "minPrice": "8.50",
    "maxPrice": "14.00",
    "recordCount": 284
  }
]

GET/prices/weekly-summary

Haftalık fiyat özeti — her ürün için min/max/ort ve hafta bazlı gruplandırma.

Parametreler

İsim	Tür	Zorunlu	Açıklama
week	string	hayır	ISO hafta, ör. 2026-29; varsayılan son tamamlanmış hafta

Örnek İstek

curl "https://haldefiyat.com/api/v1/prices/weekly-summary?week=2026-29"

Örnek Yanıt

{
  "week": "2026-29",
  "weekStart": "2026-07-13",
  "weekEnd": "2026-07-19",
  "topRisers": [],
  "topFallers": []
}

GET/prices/history/:productSlug

Belirli bir ürünün günlük fiyat geçmişi (5+ yıla kadar).

Parametreler

İsim	Tür	Zorunlu	Açıklama
productSlug	string	evet	URL'de ürün slug'ı
range	string	hayır	Geçmiş penceresi, ör. 30d / 365d / 1825d (varsayılan: 7d)
market	string	hayır	Belirli hal/borsa slug'ı (opsiyonel)

Örnek İstek

curl "https://haldefiyat.com/api/v1/prices/history/domates?range=365d"

Örnek Yanıt

[
  { "priceDate": "2026-04-21", "avgPrice": "10.25", "minPrice": "8.50", "maxPrice": "14.00" }
]

GET/prices/export

Fiyat verilerini CSV olarak indirir. Tüm filtreler geçerlidir.

Parametreler

İsim	Tür	Zorunlu	Açıklama
city	string	hayır	Şehir filtresi
product	string	hayır	Ürün filtresi
range	string	hayır	Geçmiş penceresi, ör. 7d / 30d / 365d

Örnek İstek

curl -o fiyatlar.csv "https://haldefiyat.com/api/v1/prices/export?city=istanbul&range=30d"

Örnek Yanıt

market_name,product_name,min_price,max_price,avg_price,unit,price_date
İstanbul Büyükçekmece Hali,Domates,8.50,14.00,10.25,kg,2026-04-21

GET/prices/forecast/:productSlug

Yürüyen backtest, MAE/MAPE, naif baz çizgi ve drift kapısını geçen seriler için 7 günlük deneysel fiyat tahmini; eşik geçilmezse 422 döner.

Parametreler

İsim	Tür	Zorunlu	Açıklama
productSlug	string	evet	URL'de ürün slug'ı

Örnek İstek

curl "https://haldefiyat.com/api/v1/prices/forecast/domates"

Örnek Yanıt

{
  "productSlug": "domates",
  "predictions": [
    { "date": "2026-04-22", "predicted": 10.8 }
  ],
  "validation": { "modelMape": 8.4, "baselineMape": 11.2, "publishable": true }
}

HaldeFiyat Endeksi

15 temel tarım ürününden oluşan haftalık fiyat endeksi.

GET/index/latestCache: 5 dakika

En güncel endeks değerini döndürür.

Örnek İstek

curl "https://haldefiyat.com/api/v1/index/latest"

Örnek Yanıt

{
  "indexWeek": "2026-16",
  "indexValue": "98.81",
  "baseWeek": "2026-14",
  "basketAvg": "12.34",
  "productsCount": 13,
  "weekStart": "2026-04-14",
  "weekEnd": "2026-04-20"
}

GET/index/historyCache: 5 dakika

Endeks geçmişi — varsayılan 26 hafta.

Parametreler

İsim	Tür	Zorunlu	Açıklama
weeks	number	hayır	Kaç haftalık geçmiş (maks. 104)

Örnek İstek

curl "https://haldefiyat.com/api/v1/index/history?weeks=8"

Örnek Yanıt

[
  { "indexWeek": "2026-14", "indexValue": "100.00", "basketAvg": "12.48", "productsCount": 13 },
  { "indexWeek": "2026-15", "indexValue": "98.81",  "basketAvg": "12.34", "productsCount": 13 }
]

GET/index/basket

Endeks sepetindeki ürün listesi.

Örnek İstek

curl "https://haldefiyat.com/api/v1/index/basket"

Örnek Yanıt

{
  "basket": [
    { "slug": "domates", "label": "Domates" },
    { "slug": "biber",   "label": "Biber" }
  ]
}

Hal Listesi

Türkiye genelindeki aktif hal ve pazar bilgileri.

GET/markets

Tüm aktif hallerin listesi.

Parametreler

İsim	Tür	Zorunlu	Açıklama
city	string	hayır	Şehir filtresi

Örnek İstek

curl "https://haldefiyat.com/api/v1/markets"

Örnek Yanıt

[
  {
    "id": "...",
    "name": "İstanbul Büyükçekmece Hali",
    "slug": "istanbul-buyukcekmece-hali",
    "city": "İstanbul",
    "isActive": true
  }
]

Yıllık Üretim

TÜİK kaynaklı yıllık tarımsal üretim verileri.

GET/production

Ürün bazlı yıllık üretim miktarları.

Parametreler

İsim	Tür	Zorunlu	Açıklama
product	string	hayır	Ürün adı
year	number	hayır	Yıl filtresi

Örnek İstek

curl "https://haldefiyat.com/api/v1/production?product=domates&year=2024"

Örnek Yanıt

[
  { "year": 2024, "productName": "Domates", "quantityTons": 13200000, "source": "TÜİK" }
]

Fiyat Uyarıları

Hedef fiyat belirle, ürün o fiyata ulaştığında bildirim al.

GET/alerts

Kayıtlı e-posta'ya ait uyarı listesi.

Parametreler

İsim	Tür	Zorunlu	Açıklama
email	string	evet	Uyarı kaydedilmiş e-posta

Örnek İstek

curl "https://haldefiyat.com/api/v1/alerts?email=ornek@mail.com"

Örnek Yanıt

[
  {
    "id": "...",
    "productName": "Domates",
    "targetPrice": "9.00",
    "direction": "below",
    "isActive": true
  }
]

POST/alerts

Yeni fiyat uyarısı oluşturur.

Örnek İstek

curl -X POST "https://haldefiyat.com/api/v1/alerts" \
  -H "Content-Type: application/json" \
  -d '{"email":"ornek@mail.com","productSlug":"domates","targetPrice":9,"direction":"below"}'

Örnek Yanıt

{ "id": "...", "created": true }

DELETE/alerts/:id

Uyarıyı siler.

Parametreler

İsim	Tür	Zorunlu	Açıklama
id	string	evet	URL'de uyarı ID

Örnek İstek

curl -X DELETE "https://haldefiyat.com/api/v1/alerts/abc-123"

Örnek Yanıt

{ "deleted": true }

Sürüm ve değişiklik kaydı

API v1

Geriye uyumlu alan eklemeleri v1 içinde yayınlanır. Alan kaldırma, anlam değiştirme veya zorunlu parametre ekleme yeni ana sürüm ve geçiş duyurusu gerektirir.

2026-08-14: Plan/kota sözleşmesi backend ayar kaynağına bağlandı; anahtarlı ve anonim rate-limit header rolleri ayrıldı.
2026-08-14: Fiyat cevaplarında public kaynak, veri tarihi ve kalite alanları; CSV'de filtre metadatası belgelendi.

Lisans, cache ve yeniden dağıtım koşulları için API Kullanım Politikası; destek için İletişim.

Embed Widget'lar

Güncel fiyat listesi ve HaldeFiyat Endeksi'ni kendi sitenize iframe olarak ekleyebilirsiniz. Koyu/açık tema, kategori, ürün slug listesi ve limit parametreleri desteklenir.

Güncel fiyat widget

<iframe src="https://haldefiyat.com/fiyatlar/widget?limit=6" width="420" height="430" style="border:none;border-radius:16px;max-width:100%;" title="HaldeFiyat Güncel Hal Fiyatları"></iframe>

Özel ürün listesi

<iframe src="https://haldefiyat.com/fiyatlar/widget?slugs=domates,biber,salatalik&theme=light&limit=3" width="420" height="260" style="border:none;border-radius:16px;max-width:100%;" title="HaldeFiyat Özel Fiyat Widget"></iframe>

Koyu tema

<iframe src="https://haldefiyat.com/endeks/widget" width="320" height="168" style="border:none;border-radius:14px;" title="HaldeFiyat Endeksi"></iframe>

Açık tema

<iframe src="https://haldefiyat.com/endeks/widget?theme=light" width="320" height="168" style="border:none;border-radius:14px;" title="HaldeFiyat Endeksi"></iframe>

Tüm embed örnekleri için /embed sayfasını kullanın.

Notlar

Tüm yanıtlar UTF-8 kodlamasında JSON'dır.
Tarih formatı YYYY-MM-DD, hafta formatı YYYY-WW (ISO 8601).
Cache başlıkları içeren endpoint'ler CDN veya servis worker ile önbelleklenebilir.
Yüksek hacimli entegrasyonlar için iletişime geçin.