API Belgeleri

Hal fiyatlarını kendi uygulamanızda kullanın. API ücretsizdir, anahtar gerektirmez ve kayıt istemez. Sayfaları kazımak yerine bu uç noktaları kullanın.

Uç noktalar

“Önceki sistem” işaretli yollar önceki HalDeFiyat API’sinin adresleridir; anahtar sırası ve değer tipleri korunur, yeni alanlar yalnızca sona eklenir.

Yol	Ne döner	Parametre	Önbellek	Hatalar
GET /api/v1/prices Önceki sistem	Hal bazında fiyat satırları; her satır kaynağı, belge adresi ve tazelik durumuyla	`product` — Ürün çeşidi ya da ürün kısa adı, örn. domates `market` — Hal kısa adı, örn. izmir-hal `city` — İl adı, örn. İzmir `category` — Kategori, örn. sebze, meyve `date` — Tek bir veri günü, YYYY-AA-GG `range` — <gün>d biçiminde dönem, örn. 30d. Geçersiz değer 7 gün sayılır (eski sözleşme). En çok 3650d. `page`, `limit` — sayfalama	15 dk	400, 429, 500
GET /api/v1/prices/latest Önceki sistem	Ürün başına en güncel ulusal gösterge; her satır kendi gününü taşır	`product` — Ürün çeşidi ya da ürün kısa adı, örn. domates `category` — Kategori, örn. sebze, meyve	15 dk	429, 500
GET /api/v1/prices/history/{slug} Önceki sistem	Bir ürün çeşidinin hal bazında fiyat geçmişi (eski sözleşme: fiyatlar ondalık metin)	`slug` (zorunlu) — Ürün çeşidi kısa adı `range` — <gün>d biçiminde dönem, örn. 30d. Geçersiz değer 7 gün sayılır (eski sözleşme). En çok 3650d. `market` — Hal kısa adı, örn. izmir-hal `bucket` — daily \| weekly \| monthly \| auto; geçersizse daily `page`, `limit` — sayfalama	1 saat	429, 500
GET /api/v1/prices/markets Önceki sistem	Fiyat yayımlayan haller, kaynaklarıyla (eski adres; /api/v1/markets ile aynı yanıt)	—	1 saat	429, 500
GET /api/v1/prices/export Önceki sistem	Fiyat satırları CSV olarak (BOM, virgül ayraç, nokta ondalık; locale=tr ile virgül ondalık) (CSV)	`format` — Yalnızca csv `product` — Ürün çeşidi ya da ürün kısa adı, örn. domates `market` — Hal kısa adı, örn. izmir-hal `city` — İl adı, örn. İzmir `category` — Kategori, örn. sebze, meyve `date` — Tek bir veri günü, YYYY-AA-GG `range` — <gün>d biçiminde dönem, örn. 30d. Geçersiz değer 7 gün sayılır (eski sözleşme). En çok 3650d. `latest` — 1 ise her ürün çeşidinin son bülteni `locale` — tr ise Türkçe Excel için virgül ondalık	önbelleğe alınmaz	400, 429, 500
GET /api/v1/products	Yayımdaki her ürün çeşidi ve en son göstergesi	`category` — Kategori, örn. sebze, meyve `page`, `limit` — sayfalama	1 saat	429, 500
GET /api/v1/products/search Önceki sistem	Ürün araması: ad ve kaynakların kullandığı adlar (alias) üzerinden, Türkçe katlamayla	`q` (zorunlu) — Aranan metin, en az iki harf `limit` — En çok kaç sonuç (1–50, varsayılan 20)	5 dk	400, 429, 500
GET /api/v1/products/{slug}/aliases Önceki sistem	Bir ürün çeşidine bağlanmış kaynak adları: hangi hal hangi adı basıyor	`slug` (zorunlu) — Ürün çeşidi (domates-pembe) ya da ürün ailesi (domates) kısa adı	1 saat	404, 429, 500
GET /api/v1/markets	Yayımdaki her hal, kaynağı ve tazeliğiyle	—	1 saat	429, 500
GET /api/v1/search	Ürün ve hal araması, Türkçe katlamayla	`q` (zorunlu) — Aranan metin	5 dk	400, 429, 500
GET /api/v1/sources/status Önceki sistem	Her veri kaynağının durumu: son veri günü, son başarılı çekim, tazelik ve uyarılar	—	1 dk	429, 500
GET /api/v1/index/latest Önceki sistem	HalDeFiyat Endeksi: en son kapanmış hafta ve önceki haftaya göre değişim	—	1 saat	429, 500
GET /api/v1/index/history Önceki sistem	HalDeFiyat Endeksi haftalık serisi	`range` — Son <gün>d içindeki haftalar, örn. 90d; verilmezse tüm seri `from` — Başlangıç günü, YYYY-AA-GG `to` — Bitiş günü, YYYY-AA-GG	1 saat	400, 429, 500
GET /api/v1/index/{slug}	Belediye verisinden hesaplanan, yayımlanmış bir endeks serisi; yayımlanmamışsa 409	`slug` (zorunlu) — Endeks kısa adı	1 saat	404, 409, 429, 500
GET /api/v1/observations/{id}	Bir fiyatın kanıtı: belge adresi, çekim anı, sha256, ayrıştırıcı sürümü, basıldığı satır	`id` (zorunlu) — Gözlem kimliği (fiyat satırındaki id)	1 saat	400, 404, 429, 500
GET /api/v1/health	Kurulum durumu; bir kaynak takviminin gerisindeyse ya da uydurma veri modunda 503	—	önbelleğe alınmaz	429, 503
GET /api/v1/search-index	Sitedeki hızlı aramanın dizini: ürün, hal, şehir ve firma adları	—	5 dk	429, 500
GET /api/v1/openapi.json	Bu OpenAPI 3.1 belgesi; yanıt şemalarından üretilir	—	5 dk	429

Makine tarafından okunabilir tanım: /api/v1/openapi.json (OpenAPI 3.1). Bu belge elle yazılmaz; yanıt şemalarından üretilir ve sözleşme testi gerçek yanıtları aynı şemalardan geçirir, böylece belge ile davranış birbirinden ayrı düşemez.

Örnek

curl "https://haldefiyat.com/api/v1/prices/latest?product=domates"
curl "https://haldefiyat.com/api/v1/prices?product=domates&range=30d&limit=100&page=2"
curl "https://haldefiyat.com/api/v1/prices/history/domates-pembe?range=30d"
curl "https://haldefiyat.com/api/v1/products/search?q=kapya%20biber"
curl "https://haldefiyat.com/api/v1/sources/status"
curl -H "x-request-id: benim-istegim-0001" "https://haldefiyat.com/api/v1/index/latest"

Tazelik: bu fiyat güncel mi?

Her fiyat satırı sona eklenmiş şu alanları taşır: dataDate (fiyatın ait olduğu gün, kaynağın kendi tarihi), fetchedAt (belgenin kaynaktan çekildiği an), isStale, freshness ve warnings. Fiyat satırlarında ayrıca documentUrl (okunan belge) ve observationUrl (kanıt uç noktası) bulunur. Durum, sitedeki kuralla aynı hesaplanır: kaynağın yayın takvimi ve onaylı tatiller üzerinden kaçırılan yayın günü sayılır.

freshness	Anlamı	isStale
fresh	Veri günü bugün ya da kaynak o günden beri yayın günü geçirmedi (hafta sonu, tatil).	false
delayed	Bir veya iki yayın günü kaçırıldı. Sitedeki tolerans içinde; sayfa henüz “gecikti” demez.	false
stale	İkiden fazla yayın günü kaçırıldı, kaynak aynı listeyi tekrarlıyor ya da kayıt durağan bir arşivden.	true
failed	Kaynak engellendi, erişilemiyor ya da biçimi bozuldu; veya son çekim başarısız ve veri güncel değil.	true
unavailable	Kayıtlı veri günü yok.	true

Uyarı kodları

no_data — Bu kaynak için kayıtlı veri günü yok.
data_delayed — Kaynak bir veya iki yayın günüdür yeni liste yayımlamadı.
data_stale — Kaynak ikiden fazla yayın günüdür güncellenmedi; bu güncel fiyat değildir.
source_frozen — Kaynak aynı fiyatları tekrarlıyor; yeni liste olarak sayılmıyor.
source_blocked — Kaynak erişime kapalı; otomatik toplama durduruldu.
source_unreachable — Kaynağa ulaşılamıyor.
source_broken — Kaynağın biçimi değişti; ayrıştırma durduruldu.
last_fetch_failed — Kaynağa yapılan son çekim başarısız oldu.
collection_paused — Bu kaynak şu an otomatik olarak toplanmıyor.
static_archive — Durağan arşiv kaydı; güncellenmez.
computed_midpoint — Ortalama kaynaktan değil, en düşük ve en yüksek fiyatın ortasından hesaplandı.
corrected_value — Bu değer bir yönetici tarafından gerekçesiyle düzeltildi.

Hatalar ve istek kimliği

Hatalar tek biçimde döner. Kodlar büyük harf ve alt çizgiyle yazılır (NOT_FOUND, QUERY_TOO_SHORT, RATE_LIMITED). İç içe error nesnesi önceki sistemle uyumluluk için korunur.

{
  "error": { "code": "NOT_FOUND", "message": "…", "details": null, "requestId": "…" },
  "code": "NOT_FOUND",
  "message": "…",
  "requestId": "3f0c…",
  "timestamp": "2026-09-27T09:15:02.114Z"
}

Her yanıt bir x-request-id başlığı taşır. İsteğinizde kendi kimliğinizi (8–128 karakter, harf, rakam ve ._:-) gönderirseniz aynen geri döner; göndermezseniz sunucu bir UUID üretir. Bir hatayı bildirirken bu kimliği yazın; kayıtlarda bu kimlikle bulunur. Önbellekten gelen bir yanıttaki kimlik, o yanıtı üreten isteğe aittir; hata yanıtları önbelleğe alınmaz.

Sayfalama

/api/v1/prices, /api/v1/products ve /api/v1/prices/history/{slug} page (1’den başlar) ve limit alır. meta.next sonraki sayfanın göreli adresidir, son sayfada null; aynı adres Link: <…>; rel="next" başlığında da bulunur. Geçmiş uç noktası önceki sözleşmeyi korumak için yalnızca page veya limit gönderildiğinde sayfalanır.

Kurallar

Kaynak bildirimi zorunludur. Her yanıt bir attribution alanı, her satır kendi kaynağını ve veri gününü taşır. Bu bir süs değil: İBB ve İzmir açık veri lisansları yeniden yayımı buna bağlar. Veriyi gösterirken bu bildirimi de gösterin.
İstek sınırı IP başına dakikada 60. Sınır tüm sunucularda ortak sayılır ve dağıtımda sıfırlanmaz. Aşıldığında 429, Retry-After: 60 ve X-RateLimit-* başlıkları döner.
Önbelleğe alın. Fiyatlar günde bir kez değişir. Her uç noktanın süresi tabloda ve Cache-Control başlığındadır; ETag ile koşullu istek gönderirseniz değişmemiş veri için 304 alırsınız.
Her satır kendi gününü taşır. Haller farklı günlerde yayımlar; "en güncel" ürün başına hesaplanır. Tek bir "bugün" varsayarsanız eski bir sayıyı taze gibi gösterirsiniz.
Şüpheli ve devralınan kayıtlar hesaplara girmez. Kalite kuralları /kaynaklar sayfasında yazılıdır.
Herkese açık ve iç API ayrıdır. Bu sayfadaki uç noktalar herkese açıktır; /api/internal ve hesap uç noktaları bu API’nin parçası değildir ve yetki ister.

Kullanım koşulları ve adil kullanım: /api-policy. Kaynakların durumu: /data-health.