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 dakikalık limitle (600/dk) ücretsizdir. Ticari kullanım, yüksek hacimli entegrasyon veya garantili kota için X-API-Key ile daha yüksek günlük limit ve öncelikli erişim sunuyoruz. Anahtarlar başvuru üzerine tanımlanır.

API Anahtarı Talep Et →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)
dateFrom	string	hayır	Başlangıç tarihi YYYY-MM-DD
dateTo	string	hayır	Bitiş tarihi YYYY-MM-DD
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

{
  "data": [
    {
      "id": "...",
      "marketName": "İstanbul Büyükçekmece Hali",
      "productName": "Domates",
      "minPrice": "8.50",
      "maxPrice": "12.00",
      "avgPrice": "10.25",
      "unit": "kg",
      "priceDate": "2026-04-21"
    }
  ],
  "total": 142,
  "page": 1,
  "limit": 5
}

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
product	string	hayır	Ürün slug'ı
weeks	number	hayır	Kaç haftalık geçmiş (varsayılan: 8)

Örnek İstek

curl "https://haldefiyat.com/api/v1/prices/weekly-summary?product=domates&weeks=4"

Örnek Yanıt

[
  {
    "isoWeek": "2026-16",
    "weekStart": "2026-04-14",
    "avgPrice": "10.25",
    "minPrice": "8.00",
    "maxPrice": "14.50",
    "recordCount": 68
  }
]

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
dateFrom	string	hayır	Başlangıç tarihi
dateTo	string	hayır	Bitiş tarihi

Örnek İstek

curl -o fiyatlar.csv "https://haldefiyat.com/api/v1/prices/export?city=istanbul&dateFrom=2026-04-01"

Ö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

Yapay zeka destekli 7 günlük fiyat tahmini.

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",
  "forecast": [
    { "date": "2026-04-22", "predictedAvg": 10.8, "confidence": 0.74 }
  ]
}

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 }

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.

İ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)

dateFrom

string

hayır

Başlangıç tarihi YYYY-MM-DD

dateTo

string

hayır

Bitiş tarihi YYYY-MM-DD

page

number

hayır

Sayfa no (varsayılan: 1)

limit

number

hayır

Sayfa boyutu (maks. 100)

{ "data": [ { "id": "...", "marketName": "İstanbul Büyükçekmece Hali", "productName": "Domates", "minPrice": "8.50", "maxPrice": "12.00", "avgPrice": "10.25", "unit": "kg", "priceDate": "2026-04-21" } ], "total": 142, "page": 1, "limit": 5 }

İsim

Tür

Zorunlu

Açıklama

limit

number

hayır

Sonuç sayısı (varsayılan: 20)

İsim

Tür

Zorunlu

Açıklama

product

string

hayır

Ürün slug'ı

weeks

number

hayır

Kaç haftalık geçmiş (varsayılan: 8)

İ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)

İsim

Tür

Zorunlu

Açıklama

city

string

hayır

Şehir filtresi

product

string

hayır

Ürün filtresi

dateFrom

string

hayır

Başlangıç tarihi

dateTo

string

hayır

Bitiş tarihi

İsim

Tür

Zorunlu

Açıklama

productSlug

string

evet

URL'de ürün slug'ı

İsim

Tür

Zorunlu

Açıklama

weeks

number

hayır

Kaç haftalık geçmiş (maks. 104)

İsim

Tür

Zorunlu

Açıklama

city

string

hayır

Şehir filtresi

İsim

Tür

Zorunlu

Açıklama

product

string

hayır

Ürün adı

year

number

hayır

Yıl filtresi

İsim

Tür

Zorunlu

Açıklama

string

evet

Uyarı kaydedilmiş e-posta

İsim

Tür

Zorunlu

Açıklama

string

evet

URL'de uyarı ID

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.