{"openapi":"3.1.0","info":{"title":"gaste Public API","version":"v1","description":"Haber siteleri için ortak veri servisleri.\n\n### Sözleşme güvencesi\n`/v1` altındaki alanlar **silinmez ve yeniden adlandırılmaz.**\nYalnız ekleme yapılır. Kırıcı bir değişiklik gerekirse `/v2` açılır ve\n`/v1` ilan edilen süre boyunca yaşamaya devam eder.\n\n### Tazelik ve boş veri\nHer yanıt `meta.age` ile verinin yaşını bildirir. Veri kendi toleransını\n(`meta.staleAfterSec`) aştığında `data` **null** döner — eski veriyle\ndoldurulmaz. Bu durum hâlâ `200`’dür: sistem çalışıyor, gösterilebilir\ntaze veri yok. Bölümü boş bırakın; eski değeri göstermeyin.\n\n### Veri nasıl üretilir\nVeriler arka planda periyodik olarak çekilir ve saklanır; isteğiniz\nupstream’e (open-meteo, TCMB) gitmez. Bu yüzden yanıt süresi\nupstream’in durumundan bağımsızdır."},"servers":[{"url":"https://api.gaste.org"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer gsk_live_…`"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Tarayıcıdan çalışan widget’lar için alternatif."}}},"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"paths":{"/v1/ping":{"get":{"summary":"Entegrasyon doğrulama","description":"Anahtar çalışıyor mu, kota ne durumda, sunucu saati ne?","responses":{"200":{"description":"Anahtar geçerli.","content":{"application/json":{"schema":{"type":"object","required":["ok","tenant","environment","time"],"properties":{"ok":{"type":"boolean"},"tenant":{"type":"string"},"environment":{"type":"string","enum":["live","test"]},"time":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Geçersiz parametre (bilinmeyen il, bozuk saat dilimi…).","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem ayrıntısı.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}},"401":{"description":"Anahtar eksik, geçersiz ya da iptal edilmiş.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem ayrıntısı.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}},"429":{"description":"İki ayrı durum, iki ayrı `type`: `rate-limit` (ani yük — birkaç saniye bekleyin) ve `quota-exceeded` (aylık tavan — ay başında sıfırlanır). Gereken davranış tamamen farklı olduğu için ayırt edin; `Retry-After` her ikisinde de kaç saniye bekleneceğini söyler.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem ayrıntısı.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}}}}},"/v1/openapi.json":{"get":{"summary":"Bu belge","description":"Makine okunur sözleşme. İstemci üreteçleri (openapi-generator vb.) doğrudan bu adresi kullanabilir.","security":[],"responses":{"200":{"description":"OpenAPI 3.1 belgesi.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/weather":{"get":{"summary":"İl bazlı hava durumu","parameters":[{"name":"city","in":"query","required":false,"schema":{"type":"string","enum":["adana","adiyaman","afyonkarahisar","agri","amasya","ankara","antalya","artvin","aydin","balikesir","bilecik","bingol","bitlis","bolu","burdur","bursa","canakkale","cankiri","corum","denizli","diyarbakir","edirne","elazig","erzincan","erzurum","eskisehir","gaziantep","giresun","gumushane","hakkari","hatay","isparta","mersin","istanbul","izmir","kars","kastamonu","kayseri","kirklareli","kirsehir","kocaeli","konya","kutahya","malatya","manisa","kahramanmaras","mardin","mugla","mus","nevsehir","nigde","ordu","rize","sakarya","samsun","siirt","sinop","sivas","tekirdag","tokat","trabzon","tunceli","sanliurfa","usak","van","yozgat","zonguldak","aksaray","bayburt","karaman","kirikkale","batman","sirnak","bartin","ardahan","igdir","yalova","karabuk","kilis","osmaniye","duzce"]},"description":"İl slug’ı. Verilmezse `istanbul`. Bilinmeyen slug 400 döndürür — sessizce varsayılana düşmez."},{"name":"lat","in":"query","required":false,"schema":{"type":"number","minimum":-90,"maximum":90},"description":"`lon` ile birlikte. Koordinat, beslenen illerin EN YAKININA yuvarlanır; yuvarlama `data.resolvedFrom` ile bildirilir. `city` verildiyse yok sayılır."},{"name":"lon","in":"query","required":false,"schema":{"type":"number","minimum":-180,"maximum":180},"description":"`lat` ile birlikte."}],"responses":{"200":{"description":"Hava durumu zarfı.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"oneOf":[{"type":"object","required":["city","citySlug","plate","lat","lon","temp","feelsLike","condition","conditionLabel","humidity","wind","windDirection","pressure","isDay","hourly","daily","resolvedFrom"],"properties":{"city":{"type":"string","example":"İstanbul"},"citySlug":{"type":"string","example":"istanbul"},"plate":{"type":"integer","example":34},"lat":{"type":"number","example":41.0053},"lon":{"type":"number","example":28.977},"temp":{"type":"integer","description":"°C","example":22},"feelsLike":{"type":"integer","description":"°C","example":21},"condition":{"type":"string","enum":["clear-day","clear-night","partly-cloudy-day","partly-cloudy-night","overcast","fog","drizzle","showers","rain","sleet","heavy-sleet","snow","heavy-snow","thunderstorm","thunderstorm-snow"],"example":"partly-cloudy-day","description":"Kararlı makine kodu. İkon eşlemesi için bunu kullanın, `conditionLabel`i değil."},"conditionLabel":{"type":"string","example":"Parçalı bulutlu"},"humidity":{"type":"integer","description":"%","example":63},"wind":{"type":"integer","description":"km/sa","example":14},"windDirection":{"type":"string","example":"KD"},"pressure":{"type":"integer","description":"hPa","example":1011},"isDay":{"type":"boolean","example":true},"hourly":{"type":"array","description":"Şu andan itibaren 24 saat.","items":{"type":"object","required":["time","temp","condition","conditionLabel","precipitation"],"properties":{"time":{"type":"string","format":"date-time","description":"UTC."},"temp":{"type":"integer","example":21},"condition":{"type":"string","enum":["clear-day","clear-night","partly-cloudy-day","partly-cloudy-night","overcast","fog","drizzle","showers","rain","sleet","heavy-sleet","snow","heavy-snow","thunderstorm","thunderstorm-snow"],"example":"partly-cloudy-day","description":"Kararlı makine kodu. İkon eşlemesi için bunu kullanın, `conditionLabel`i değil."},"conditionLabel":{"type":"string","example":"Parçalı bulutlu"},"precipitation":{"type":"integer","description":"Yağış olasılığı, %","example":10}}}},"daily":{"type":"array","description":"7 günlük. `date` ilin YEREL takvim günüdür.","items":{"type":"object","required":["date","high","low","condition","conditionLabel","precipitation","windMax","sunrise","sunset","uvMax"],"properties":{"date":{"type":"string","example":"2026-09-11"},"high":{"type":"integer","example":26},"low":{"type":"integer","example":18},"condition":{"type":"string","enum":["clear-day","clear-night","partly-cloudy-day","partly-cloudy-night","overcast","fog","drizzle","showers","rain","sleet","heavy-sleet","snow","heavy-snow","thunderstorm","thunderstorm-snow"],"example":"partly-cloudy-day","description":"Kararlı makine kodu. İkon eşlemesi için bunu kullanın, `conditionLabel`i değil."},"conditionLabel":{"type":"string","example":"Az bulutlu"},"precipitation":{"type":"integer","example":10},"windMax":{"type":"integer","example":22},"sunrise":{"type":["string","null"],"format":"date-time","description":"UTC."},"sunset":{"type":["string","null"],"format":"date-time","description":"UTC."},"uvMax":{"type":"integer","example":6}}}},"resolvedFrom":{"oneOf":[{"type":"object","required":["lat","lon","distanceKm"],"properties":{"lat":{"type":"number","example":41.07},"lon":{"type":"number","example":28.25},"distanceKm":{"type":"number","example":61.4}}},{"type":"null"}],"description":"`lat`/`lon` ile istendiyse hangi noktadan ne kadar uzağa yuvarlandığı. `city` ile istendiyse null."}}},{"type":"null"}],"description":"Tolerans aşıldıysa **null**. Eski veriyle doldurulmaz: yanlış bilgi, yokluğundan kötüdür. `meta.reason` nedeni söyler."},"meta":{"type":"object","required":["service","fetchedAt","age","staleAfterSec","stale"],"properties":{"service":{"type":"string","example":"weather"},"fetchedAt":{"type":["string","null"],"format":"date-time","description":"Verinin upstream’den çekildiği an (UTC)."},"age":{"type":["integer","null"],"example":365,"description":"Verinin yaşı (saniye). Veri boş dönse bile doldurulur — arıza teşhisi için."},"staleAfterSec":{"type":"integer","example":10800,"description":"Bu yaş aşılırsa veri bayat sayılır ve `data` boşalır."},"stale":{"type":"boolean","example":false},"reason":{"type":"string","enum":["stale","missing"],"description":"`data` neden boş. Yalnız `data: null` iken bulunur."}}}}}}}},"400":{"description":"Geçersiz parametre (bilinmeyen il, bozuk saat dilimi…).","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem ayrıntısı.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}},"401":{"description":"Anahtar eksik, geçersiz ya da iptal edilmiş.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem ayrıntısı.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}},"429":{"description":"İki ayrı durum, iki ayrı `type`: `rate-limit` (ani yük — birkaç saniye bekleyin) ve `quota-exceeded` (aylık tavan — ay başında sıfırlanır). Gereken davranış tamamen farklı olduğu için ayırt edin; `Retry-After` her ikisinde de kaç saniye bekleneceğini söyler.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem ayrıntısı.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}}}}},"/v1/weather/cities":{"get":{"summary":"Kabul edilen iller","description":"Geçerli `city` slug kümesi. Slug’lar kalıcıdır.","responses":{"200":{"description":"İl listesi.","content":{"application/json":{"schema":{"type":"object","required":["cities"],"properties":{"cities":{"type":"array","items":{"type":"object","required":["plate","name","slug","center","lat","lon","population"],"properties":{"plate":{"type":"integer","example":34},"name":{"type":"string","example":"İstanbul"},"slug":{"type":"string","example":"istanbul"},"center":{"type":"string","example":"İstanbul"},"lat":{"type":"number","example":41.0053},"lon":{"type":"number","example":28.977},"population":{"type":"integer","example":11078281}}}}}}}}},"400":{"description":"Geçersiz parametre (bilinmeyen il, bozuk saat dilimi…).","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem ayrıntısı.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}},"401":{"description":"Anahtar eksik, geçersiz ya da iptal edilmiş.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem ayrıntısı.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}},"429":{"description":"İki ayrı durum, iki ayrı `type`: `rate-limit` (ani yük — birkaç saniye bekleyin) ve `quota-exceeded` (aylık tavan — ay başında sıfırlanır). Gereken davranış tamamen farklı olduğu için ayırt edin; `Retry-After` her ikisinde de kaç saniye bekleneceğini söyler.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem ayrıntısı.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}}}}},"/v1/rates":{"get":{"summary":"TCMB döviz kurları","description":"Resmî TCMB efektif satış kuru. Günde bir yayımlanır; hafta sonu ve tatilde son iş gününün bülteni geçerlidir (`data.date` bunu söyler).","parameters":[{"name":"currencies","in":"query","required":false,"schema":{"type":"string","example":"USD,EUR,GBP"},"description":"Virgülle ayrılmış ISO 4217 kodları (en çok 25). Varsayılan `USD,EUR,GBP`. TCMB’de bulunmayan kodlar (ALTIN/XAU dâhil) sessizce elenir."}],"responses":{"200":{"description":"Kur zarfı.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"oneOf":[{"type":"object","required":["date","rates"],"properties":{"date":{"type":"string","example":"2026-09-11","description":"TCMB bülten tarihi. Hafta sonu/tatilde son iş gününe ait olur."},"rates":{"type":"array","items":{"type":"object","required":["code","symbol","raw","value","direction","changePercent","history"],"properties":{"code":{"type":"string","example":"USD"},"symbol":{"type":"string","example":"DOLAR"},"raw":{"type":"number","description":"1 birimin TL karşılığı. Otorite alan budur.","example":48.5912},"value":{"type":"string","example":"42,17","description":"tr-TR biçimli kolaylık alanı."},"direction":{"type":"string","enum":["up","down","flat"]},"changePercent":{"type":"number","description":"İşaretli yüzde, bir önceki bültene göre.","example":0.34},"history":{"type":"array","items":{"type":"number","example":48.41},"description":"Son ~12 iş günü, ESKİDEN YENİYE."}}}}}},{"type":"null"}],"description":"Tolerans aşıldıysa **null**. Eski veriyle doldurulmaz: yanlış bilgi, yokluğundan kötüdür. `meta.reason` nedeni söyler."},"meta":{"type":"object","required":["service","fetchedAt","age","staleAfterSec","stale"],"properties":{"service":{"type":"string","example":"weather"},"fetchedAt":{"type":["string","null"],"format":"date-time","description":"Verinin upstream’den çekildiği an (UTC)."},"age":{"type":["integer","null"],"example":365,"description":"Verinin yaşı (saniye). Veri boş dönse bile doldurulur — arıza teşhisi için."},"staleAfterSec":{"type":"integer","example":10800,"description":"Bu yaş aşılırsa veri bayat sayılır ve `data` boşalır."},"stale":{"type":"boolean","example":false},"reason":{"type":"string","enum":["stale","missing"],"description":"`data` neden boş. Yalnız `data: null` iken bulunur."}}}}}}}},"400":{"description":"Geçersiz parametre (bilinmeyen il, bozuk saat dilimi…).","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem ayrıntısı.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}},"401":{"description":"Anahtar eksik, geçersiz ya da iptal edilmiş.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem ayrıntısı.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}},"429":{"description":"İki ayrı durum, iki ayrı `type`: `rate-limit` (ani yük — birkaç saniye bekleyin) ve `quota-exceeded` (aylık tavan — ay başında sıfırlanır). Gereken davranış tamamen farklı olduğu için ayırt edin; `Retry-After` her ikisinde de kaç saniye bekleneceğini söyler.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem ayrıntısı.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}}}}},"/v1/prayer":{"get":{"summary":"Namaz vakitleri","description":"Diyanet İşleri Başkanlığı’nın yayımladığı vakitler. **Hesaplanmıyor**, resmî tablo taşınıyor ve `data.source` ile beyan ediliyor.\n\nYayımlanmış bir günün vakti değişmez; bu yüzden veri uzun ömürlüdür ve upstream’e nadiren gidilir. `data.next` sıradaki vakti ve ona kalan süreyi verir — üst bantların aradığı alan budur.","parameters":[{"name":"city","in":"query","required":false,"schema":{"type":"string","enum":["adana","adiyaman","afyonkarahisar","agri","amasya","ankara","antalya","artvin","aydin","balikesir","bilecik","bingol","bitlis","bolu","burdur","bursa","canakkale","cankiri","corum","denizli","diyarbakir","edirne","elazig","erzincan","erzurum","eskisehir","gaziantep","giresun","gumushane","hakkari","hatay","isparta","mersin","istanbul","izmir","kars","kastamonu","kayseri","kirklareli","kirsehir","kocaeli","konya","kutahya","malatya","manisa","kahramanmaras","mardin","mugla","mus","nevsehir","nigde","ordu","rize","sakarya","samsun","siirt","sinop","sivas","tekirdag","tokat","trabzon","tunceli","sanliurfa","usak","van","yozgat","zonguldak","aksaray","bayburt","karaman","kirikkale","batman","sirnak","bartin","ardahan","igdir","yalova","karabuk","kilis","osmaniye","duzce"]},"description":"İl slug’ı. Verilmezse `istanbul`. Bilinmeyen slug 400 döndürür — sessizce varsayılana düşmez."},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":7,"default":3,"example":3},"description":"Kaç günlük pencere döndürülsün (bugün dahil). En çok 7."}],"responses":{"200":{"description":"Namaz vakti zarfı.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"oneOf":[{"type":"object","required":["city","citySlug","plate","timezone","source","today","next","days"],"properties":{"city":{"type":"string","example":"İstanbul"},"citySlug":{"type":"string","example":"istanbul"},"plate":{"type":"integer","example":34},"timezone":{"type":"string","example":"Europe/Istanbul"},"source":{"type":"string","example":"Diyanet İşleri Başkanlığı","description":"Vakitlerin kaynağı. Yayımlarken belirtmeniz beklenir."},"today":{"type":"object","required":["date","hijri","times"],"properties":{"date":{"type":"string","example":"2026-09-12","description":"Yerel takvim günü."},"hijri":{"type":"string","example":"1 Rebiulahir 1448"},"times":{"type":"array","items":{"type":"object","required":["key","label","time","at"],"properties":{"key":{"type":"string","enum":["imsak","gunes","ogle","ikindi","aksam","yatsi"],"example":"ogle","description":"Kararlı makine kodu. Etiket yerine bunu kullanın."},"label":{"type":"string","example":"Öğle"},"time":{"type":"string","example":"13:06","description":"YEREL duvar saati (`data.timezone`). Yayıncının basacağı metin."},"at":{"type":"string","format":"date-time","description":"Aynı anın UTC damgası — geri sayım ve karşılaştırma için."}}},"description":"Günün altı vakti, sırayla."}}},"next":{"description":"Sıradaki vakit ve ona kalan süre. Yatsıdan sonra YARININ imsakını gösterir ve `tomorrow: true` der. Elimizde yarın yoksa `null`.","oneOf":[{"type":"object","required":["key","label","time","at","inSec","tomorrow"],"properties":{"key":{"type":"string","enum":["imsak","gunes","ogle","ikindi","aksam","yatsi"],"example":"ogle","description":"Kararlı makine kodu. Etiket yerine bunu kullanın."},"label":{"type":"string","example":"Öğle"},"time":{"type":"string","example":"13:06","description":"YEREL duvar saati (`data.timezone`). Yayıncının basacağı metin."},"at":{"type":"string","format":"date-time","description":"Aynı anın UTC damgası — geri sayım ve karşılaştırma için."},"inSec":{"type":"integer","example":2720,"description":"Vakte kalan saniye."},"tomorrow":{"type":"boolean","example":false}}},{"type":"null"}]},"days":{"type":"array","items":{"type":"object","required":["date","hijri","times"],"properties":{"date":{"type":"string","example":"2026-09-12","description":"Yerel takvim günü."},"hijri":{"type":"string","example":"1 Rebiulahir 1448"},"times":{"type":"array","items":{"type":"object","required":["key","label","time","at"],"properties":{"key":{"type":"string","enum":["imsak","gunes","ogle","ikindi","aksam","yatsi"],"example":"ogle","description":"Kararlı makine kodu. Etiket yerine bunu kullanın."},"label":{"type":"string","example":"Öğle"},"time":{"type":"string","example":"13:06","description":"YEREL duvar saati (`data.timezone`). Yayıncının basacağı metin."},"at":{"type":"string","format":"date-time","description":"Aynı anın UTC damgası — geri sayım ve karşılaştırma için."}}},"description":"Günün altı vakti, sırayla."}}},"description":"Bugünden başlayan pencere."}}},{"type":"null"}],"description":"Tolerans aşıldıysa **null**. Eski veriyle doldurulmaz: yanlış bilgi, yokluğundan kötüdür. `meta.reason` nedeni söyler."},"meta":{"type":"object","required":["service","fetchedAt","age","staleAfterSec","stale"],"properties":{"service":{"type":"string","example":"weather"},"fetchedAt":{"type":["string","null"],"format":"date-time","description":"Verinin upstream’den çekildiği an (UTC)."},"age":{"type":["integer","null"],"example":365,"description":"Verinin yaşı (saniye). Veri boş dönse bile doldurulur — arıza teşhisi için."},"staleAfterSec":{"type":"integer","example":10800,"description":"Bu yaş aşılırsa veri bayat sayılır ve `data` boşalır."},"stale":{"type":"boolean","example":false},"reason":{"type":"string","enum":["stale","missing"],"description":"`data` neden boş. Yalnız `data: null` iken bulunur."}}}}}}}},"400":{"description":"Geçersiz parametre (bilinmeyen il, bozuk saat dilimi…).","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem ayrıntısı.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}},"401":{"description":"Anahtar eksik, geçersiz ya da iptal edilmiş.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem ayrıntısı.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}},"429":{"description":"İki ayrı durum, iki ayrı `type`: `rate-limit` (ani yük — birkaç saniye bekleyin) ve `quota-exceeded` (aylık tavan — ay başında sıfırlanır). Gereken davranış tamamen farklı olduğu için ayırt edin; `Retry-After` her ikisinde de kaç saniye bekleneceğini söyler.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem ayrıntısı.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}}}}},"/v1/markets":{"get":{"summary":"Piyasa: borsa, altın, kripto, makro","description":"Dört bölüm, **dört ayrı zarf**: her bölümün kendi tazelik toleransı var (kripto dakikalarla, makro gösterge aylarla ölçülür). Biri bayatladığında yalnız o bölüm boşalır, diğerleri canlı kalır.\n\n⚠️ **Döviz burada yok** — resmî kur `/v1/rates`in işidir. Aynı soruya iki farklı cevap veren bir API olmamak için serbest piyasa kuru yayımlanmıyor.\n\nBİST değerleri **kapanış**tır, gün içi canlı endeks değildir; hangi güne ait olduğu `asOf` alanında yazar.","responses":{"200":{"description":"Bölüm başına zarf.","content":{"application/json":{"schema":{"type":"object","required":["borsa","altin","kripto","makro"],"properties":{"borsa":{"type":"object","required":["data","meta"],"properties":{"data":{"oneOf":[{"type":"object","required":["quotes"],"properties":{"quotes":{"type":"array","items":{"type":"object","required":["id","label","group","source","value","change","changePercent","buy","sell","unit","precision","asOf","period","note"],"properties":{"id":{"type":"string","example":"gram-altin","description":"Kalıcı kimlik."},"label":{"type":"string","example":"Gram Altın"},"group":{"type":"string","enum":["borsa","altin","kripto","makro"],"example":"kripto"},"source":{"type":"string","enum":["BIST","SERBEST","COINGECKO","TCMB"],"example":"COINGECKO","description":"Verinin kaynağı. Aynı listede durmaları kalemleri aynı güvenilirlikte yapmaz: `BIST` resmî kapanış, `SERBEST` kuyumcu/kapalıçarşı fiyatı, `COINGECKO` borsa ortalaması, `TCMB` resmî yayım."},"value":{"type":"number","example":6907.88,"description":"Otorite alan: ham sayı."},"change":{"type":["number","null"],"example":42.1,"description":"Bir önceki gözleme göre mutlak değişim."},"changePercent":{"type":["number","null"],"example":0.61,"description":"İşaretli yüzde."},"buy":{"type":["number","null"],"description":"Altında serbest piyasa alışı; kriptoda TL karşılığı."},"sell":{"type":["number","null"],"description":"Serbest piyasa satışı (yalnız altın/gümüş)."},"unit":{"type":"string","example":"₺","description":"`₺`, `$`, `%`, `milyar $` ya da boş (endeks)."},"precision":{"type":"integer","example":2,"description":"Önerilen ondalık basamak."},"asOf":{"type":"string","example":"2026-09-11","description":"Değerin ait olduğu an/gün. **Bizim çekim zamanımız değil** — BİST kapanışında o günün tarihi, makro göstergede ayın ilk günü olur."},"period":{"type":["string","null"],"example":"Temmuz 2026","description":"Aylık göstergelerde dönem etiketi."},"note":{"type":["string","null"],"description":"Türetilmiş/dikkat gerektiren kalemlerde açıklama."}}}}}},{"type":"null"}],"description":"Tolerans aşıldıysa **null**. Eski veriyle doldurulmaz: yanlış bilgi, yokluğundan kötüdür. `meta.reason` nedeni söyler."},"meta":{"type":"object","required":["service","fetchedAt","age","staleAfterSec","stale"],"properties":{"service":{"type":"string","example":"weather"},"fetchedAt":{"type":["string","null"],"format":"date-time","description":"Verinin upstream’den çekildiği an (UTC)."},"age":{"type":["integer","null"],"example":365,"description":"Verinin yaşı (saniye). Veri boş dönse bile doldurulur — arıza teşhisi için."},"staleAfterSec":{"type":"integer","example":10800,"description":"Bu yaş aşılırsa veri bayat sayılır ve `data` boşalır."},"stale":{"type":"boolean","example":false},"reason":{"type":"string","enum":["stale","missing"],"description":"`data` neden boş. Yalnız `data: null` iken bulunur."}}}}},"altin":{"type":"object","required":["data","meta"],"properties":{"data":{"oneOf":[{"type":"object","required":["quotes"],"properties":{"quotes":{"type":"array","items":{"type":"object","required":["id","label","group","source","value","change","changePercent","buy","sell","unit","precision","asOf","period","note"],"properties":{"id":{"type":"string","example":"gram-altin","description":"Kalıcı kimlik."},"label":{"type":"string","example":"Gram Altın"},"group":{"type":"string","enum":["borsa","altin","kripto","makro"],"example":"kripto"},"source":{"type":"string","enum":["BIST","SERBEST","COINGECKO","TCMB"],"example":"COINGECKO","description":"Verinin kaynağı. Aynı listede durmaları kalemleri aynı güvenilirlikte yapmaz: `BIST` resmî kapanış, `SERBEST` kuyumcu/kapalıçarşı fiyatı, `COINGECKO` borsa ortalaması, `TCMB` resmî yayım."},"value":{"type":"number","example":6907.88,"description":"Otorite alan: ham sayı."},"change":{"type":["number","null"],"example":42.1,"description":"Bir önceki gözleme göre mutlak değişim."},"changePercent":{"type":["number","null"],"example":0.61,"description":"İşaretli yüzde."},"buy":{"type":["number","null"],"description":"Altında serbest piyasa alışı; kriptoda TL karşılığı."},"sell":{"type":["number","null"],"description":"Serbest piyasa satışı (yalnız altın/gümüş)."},"unit":{"type":"string","example":"₺","description":"`₺`, `$`, `%`, `milyar $` ya da boş (endeks)."},"precision":{"type":"integer","example":2,"description":"Önerilen ondalık basamak."},"asOf":{"type":"string","example":"2026-09-11","description":"Değerin ait olduğu an/gün. **Bizim çekim zamanımız değil** — BİST kapanışında o günün tarihi, makro göstergede ayın ilk günü olur."},"period":{"type":["string","null"],"example":"Temmuz 2026","description":"Aylık göstergelerde dönem etiketi."},"note":{"type":["string","null"],"description":"Türetilmiş/dikkat gerektiren kalemlerde açıklama."}}}}}},{"type":"null"}],"description":"Tolerans aşıldıysa **null**. Eski veriyle doldurulmaz: yanlış bilgi, yokluğundan kötüdür. `meta.reason` nedeni söyler."},"meta":{"type":"object","required":["service","fetchedAt","age","staleAfterSec","stale"],"properties":{"service":{"type":"string","example":"weather"},"fetchedAt":{"type":["string","null"],"format":"date-time","description":"Verinin upstream’den çekildiği an (UTC)."},"age":{"type":["integer","null"],"example":365,"description":"Verinin yaşı (saniye). Veri boş dönse bile doldurulur — arıza teşhisi için."},"staleAfterSec":{"type":"integer","example":10800,"description":"Bu yaş aşılırsa veri bayat sayılır ve `data` boşalır."},"stale":{"type":"boolean","example":false},"reason":{"type":"string","enum":["stale","missing"],"description":"`data` neden boş. Yalnız `data: null` iken bulunur."}}}}},"kripto":{"type":"object","required":["data","meta"],"properties":{"data":{"oneOf":[{"type":"object","required":["quotes"],"properties":{"quotes":{"type":"array","items":{"type":"object","required":["id","label","group","source","value","change","changePercent","buy","sell","unit","precision","asOf","period","note"],"properties":{"id":{"type":"string","example":"gram-altin","description":"Kalıcı kimlik."},"label":{"type":"string","example":"Gram Altın"},"group":{"type":"string","enum":["borsa","altin","kripto","makro"],"example":"kripto"},"source":{"type":"string","enum":["BIST","SERBEST","COINGECKO","TCMB"],"example":"COINGECKO","description":"Verinin kaynağı. Aynı listede durmaları kalemleri aynı güvenilirlikte yapmaz: `BIST` resmî kapanış, `SERBEST` kuyumcu/kapalıçarşı fiyatı, `COINGECKO` borsa ortalaması, `TCMB` resmî yayım."},"value":{"type":"number","example":6907.88,"description":"Otorite alan: ham sayı."},"change":{"type":["number","null"],"example":42.1,"description":"Bir önceki gözleme göre mutlak değişim."},"changePercent":{"type":["number","null"],"example":0.61,"description":"İşaretli yüzde."},"buy":{"type":["number","null"],"description":"Altında serbest piyasa alışı; kriptoda TL karşılığı."},"sell":{"type":["number","null"],"description":"Serbest piyasa satışı (yalnız altın/gümüş)."},"unit":{"type":"string","example":"₺","description":"`₺`, `$`, `%`, `milyar $` ya da boş (endeks)."},"precision":{"type":"integer","example":2,"description":"Önerilen ondalık basamak."},"asOf":{"type":"string","example":"2026-09-11","description":"Değerin ait olduğu an/gün. **Bizim çekim zamanımız değil** — BİST kapanışında o günün tarihi, makro göstergede ayın ilk günü olur."},"period":{"type":["string","null"],"example":"Temmuz 2026","description":"Aylık göstergelerde dönem etiketi."},"note":{"type":["string","null"],"description":"Türetilmiş/dikkat gerektiren kalemlerde açıklama."}}}}}},{"type":"null"}],"description":"Tolerans aşıldıysa **null**. Eski veriyle doldurulmaz: yanlış bilgi, yokluğundan kötüdür. `meta.reason` nedeni söyler."},"meta":{"type":"object","required":["service","fetchedAt","age","staleAfterSec","stale"],"properties":{"service":{"type":"string","example":"weather"},"fetchedAt":{"type":["string","null"],"format":"date-time","description":"Verinin upstream’den çekildiği an (UTC)."},"age":{"type":["integer","null"],"example":365,"description":"Verinin yaşı (saniye). Veri boş dönse bile doldurulur — arıza teşhisi için."},"staleAfterSec":{"type":"integer","example":10800,"description":"Bu yaş aşılırsa veri bayat sayılır ve `data` boşalır."},"stale":{"type":"boolean","example":false},"reason":{"type":"string","enum":["stale","missing"],"description":"`data` neden boş. Yalnız `data: null` iken bulunur."}}}}},"makro":{"type":"object","required":["data","meta"],"properties":{"data":{"oneOf":[{"type":"object","required":["quotes"],"properties":{"quotes":{"type":"array","items":{"type":"object","required":["id","label","group","source","value","change","changePercent","buy","sell","unit","precision","asOf","period","note"],"properties":{"id":{"type":"string","example":"gram-altin","description":"Kalıcı kimlik."},"label":{"type":"string","example":"Gram Altın"},"group":{"type":"string","enum":["borsa","altin","kripto","makro"],"example":"kripto"},"source":{"type":"string","enum":["BIST","SERBEST","COINGECKO","TCMB"],"example":"COINGECKO","description":"Verinin kaynağı. Aynı listede durmaları kalemleri aynı güvenilirlikte yapmaz: `BIST` resmî kapanış, `SERBEST` kuyumcu/kapalıçarşı fiyatı, `COINGECKO` borsa ortalaması, `TCMB` resmî yayım."},"value":{"type":"number","example":6907.88,"description":"Otorite alan: ham sayı."},"change":{"type":["number","null"],"example":42.1,"description":"Bir önceki gözleme göre mutlak değişim."},"changePercent":{"type":["number","null"],"example":0.61,"description":"İşaretli yüzde."},"buy":{"type":["number","null"],"description":"Altında serbest piyasa alışı; kriptoda TL karşılığı."},"sell":{"type":["number","null"],"description":"Serbest piyasa satışı (yalnız altın/gümüş)."},"unit":{"type":"string","example":"₺","description":"`₺`, `$`, `%`, `milyar $` ya da boş (endeks)."},"precision":{"type":"integer","example":2,"description":"Önerilen ondalık basamak."},"asOf":{"type":"string","example":"2026-09-11","description":"Değerin ait olduğu an/gün. **Bizim çekim zamanımız değil** — BİST kapanışında o günün tarihi, makro göstergede ayın ilk günü olur."},"period":{"type":["string","null"],"example":"Temmuz 2026","description":"Aylık göstergelerde dönem etiketi."},"note":{"type":["string","null"],"description":"Türetilmiş/dikkat gerektiren kalemlerde açıklama."}}}}}},{"type":"null"}],"description":"Tolerans aşıldıysa **null**. Eski veriyle doldurulmaz: yanlış bilgi, yokluğundan kötüdür. `meta.reason` nedeni söyler."},"meta":{"type":"object","required":["service","fetchedAt","age","staleAfterSec","stale"],"properties":{"service":{"type":"string","example":"weather"},"fetchedAt":{"type":["string","null"],"format":"date-time","description":"Verinin upstream’den çekildiği an (UTC)."},"age":{"type":["integer","null"],"example":365,"description":"Verinin yaşı (saniye). Veri boş dönse bile doldurulur — arıza teşhisi için."},"staleAfterSec":{"type":"integer","example":10800,"description":"Bu yaş aşılırsa veri bayat sayılır ve `data` boşalır."},"stale":{"type":"boolean","example":false},"reason":{"type":"string","enum":["stale","missing"],"description":"`data` neden boş. Yalnız `data: null` iken bulunur."}}}}}}}}}},"400":{"description":"Geçersiz parametre (bilinmeyen il, bozuk saat dilimi…).","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem ayrıntısı.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}},"401":{"description":"Anahtar eksik, geçersiz ya da iptal edilmiş.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem ayrıntısı.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}},"429":{"description":"İki ayrı durum, iki ayrı `type`: `rate-limit` (ani yük — birkaç saniye bekleyin) ve `quota-exceeded` (aylık tavan — ay başında sıfırlanır). Gereken davranış tamamen farklı olduğu için ayırt edin; `Retry-After` her ikisinde de kaç saniye bekleneceğini söyler.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem ayrıntısı.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}}}}},"/v1/markets/instruments":{"get":{"summary":"Piyasa kimlik kataloğu","description":"Hangi enstrümanlar var ve hangilerinin grafiği çizilebilir. Kimlikleri kodunuza gömmek yerine buradan okursanız, sonradan eklenen kalemleri kendiliğinden görürsünüz.","responses":{"200":{"description":"Katalog.","content":{"application/json":{"schema":{"type":"object","required":["instruments"],"properties":{"instruments":{"type":"array","items":{"type":"object","required":["id","label","group","source","unit","precision","hasSeries"],"properties":{"id":{"type":"string","example":"bitcoin"},"label":{"type":"string","example":"Bitcoin"},"group":{"type":"string","enum":["borsa","altin","kripto","makro"],"example":"kripto"},"source":{"type":"string","enum":["BIST","SERBEST","COINGECKO","TCMB"],"example":"COINGECKO","description":"Verinin kaynağı. Aynı listede durmaları kalemleri aynı güvenilirlikte yapmaz: `BIST` resmî kapanış, `SERBEST` kuyumcu/kapalıçarşı fiyatı, `COINGECKO` borsa ortalaması, `TCMB` resmî yayım."},"unit":{"type":"string","example":"$"},"precision":{"type":"integer","example":0},"hasSeries":{"type":"boolean","description":"`/v1/markets/series` bu kimlik için veri döndürür mü."}}}}}}}}},"400":{"description":"Geçersiz parametre (bilinmeyen il, bozuk saat dilimi…).","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem ayrıntısı.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}},"401":{"description":"Anahtar eksik, geçersiz ya da iptal edilmiş.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem ayrıntısı.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}},"429":{"description":"İki ayrı durum, iki ayrı `type`: `rate-limit` (ani yük — birkaç saniye bekleyin) ve `quota-exceeded` (aylık tavan — ay başında sıfırlanır). Gereken davranış tamamen farklı olduğu için ayırt edin; `Retry-After` her ikisinde de kaç saniye bekleneceğini söyler.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem ayrıntısı.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}}}}},"/v1/markets/series":{"get":{"summary":"Piyasa grafik serisi","description":"Bir enstrümanın geçmiş serisi. Veri arka planda toplanır ve kalıcı saklanır; isteğiniz upstream’e gitmez.\n\n⚠️ Altın grafiği **türetilmiştir** (ons × dolar kuru ÷ 31,1035) çünkü ücretsiz kaynaklarda günlük altın arşivi yok. `note` bunu söyler ve yayımlarken belirtilmesi beklenir. Anlık altın fiyatı (`/v1/markets`) her zaman gerçek serbest piyasa fiyatıdır — ikisi karıştırılmamalı.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","example":"XU100"},"description":"Enstrüman kimliği. Geçerli kümeyi `/v1/markets/instruments` verir."},{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["1a","3a","6a","1y","5y"],"default":"1y"},"description":"Aralık. Varsayılan `1y`."}],"responses":{"200":{"description":"Seri zarfı.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"oneOf":[{"type":"object","required":["id","label","group","source","unit","precision","range","points","changePercent","note"],"properties":{"id":{"type":"string","example":"XU100"},"label":{"type":"string","example":"BİST 100"},"group":{"type":"string","enum":["borsa","altin","kripto","makro"],"example":"kripto"},"source":{"type":"string","enum":["BIST","SERBEST","COINGECKO","TCMB"],"example":"COINGECKO","description":"Verinin kaynağı. Aynı listede durmaları kalemleri aynı güvenilirlikte yapmaz: `BIST` resmî kapanış, `SERBEST` kuyumcu/kapalıçarşı fiyatı, `COINGECKO` borsa ortalaması, `TCMB` resmî yayım."},"unit":{"type":"string","example":""},"precision":{"type":"integer","example":2},"range":{"type":"string","enum":["1a","3a","6a","1y","5y"],"example":"1y"},"points":{"type":"array","description":"ESKİDEN YENİYE. Aylık serilerde `time` ayın ilk günüdür.","items":{"type":"object","required":["time","value"],"properties":{"time":{"type":"string","example":"2026-09-11"},"value":{"type":"number","example":14393.85}}}},"changePercent":{"type":["number","null"],"example":12.4,"description":"Aralığın başından sonuna yüzde değişim. **Yüzde birimli serilerde (enflasyon, faiz) null** — iki yüzde arasındaki fark PUAN cinsindendir, oranı anlamsızdır (%19,9 → %31,5 \"%58 artış\" değil, 11,6 puandır)."},"note":{"type":["string","null"],"description":"Serinin nasıl üretildiği. **Türetilmiş serilerde doludur** (altın grafiği ons × kurdan hesaplanır) — yayımlarken belirtmeniz beklenir."}}},{"type":"null"}],"description":"Tolerans aşıldıysa **null**. Eski veriyle doldurulmaz: yanlış bilgi, yokluğundan kötüdür. `meta.reason` nedeni söyler."},"meta":{"type":"object","required":["service","fetchedAt","age","staleAfterSec","stale"],"properties":{"service":{"type":"string","example":"weather"},"fetchedAt":{"type":["string","null"],"format":"date-time","description":"Verinin upstream’den çekildiği an (UTC)."},"age":{"type":["integer","null"],"example":365,"description":"Verinin yaşı (saniye). Veri boş dönse bile doldurulur — arıza teşhisi için."},"staleAfterSec":{"type":"integer","example":10800,"description":"Bu yaş aşılırsa veri bayat sayılır ve `data` boşalır."},"stale":{"type":"boolean","example":false},"reason":{"type":"string","enum":["stale","missing"],"description":"`data` neden boş. Yalnız `data: null` iken bulunur."}}}}}}}},"400":{"description":"Geçersiz parametre (bilinmeyen il, bozuk saat dilimi…).","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem ayrıntısı.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}},"401":{"description":"Anahtar eksik, geçersiz ya da iptal edilmiş.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem ayrıntısı.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}},"404":{"description":"Bilinmeyen kimlik ya da grafiği olmayan kalem. Boş seri DÖNMEZ: `points: []` alan istemci \"veri henüz gelmemiş\" sanıp beklemeye geçerdi, oysa o kalem için grafik hiçbir zaman gelmeyecek.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem ayrıntısı.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}},"429":{"description":"İki ayrı durum, iki ayrı `type`: `rate-limit` (ani yük — birkaç saniye bekleyin) ve `quota-exceeded` (aylık tavan — ay başında sıfırlanır). Gereken davranış tamamen farklı olduğu için ayırt edin; `Retry-After` her ikisinde de kaç saniye bekleneceğini söyler.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem ayrıntısı.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}}}}},"/v1/chrome":{"get":{"summary":"Üst bar için birleşik uç (tarih + hava + kur)","description":"Tek çağrıda tarih, hava ve kur. **Tek kota hakkı** tüketir — ayrı ayrı çağırmak yerine bunu kullanmak hem daha hızlı hem daha ucuz.\n\nHava ve kur bölümleri AYRI `meta` taşır: biri bayatladığında diğeri canlı kalır.","parameters":[{"name":"city","in":"query","required":false,"schema":{"type":"string","enum":["adana","adiyaman","afyonkarahisar","agri","amasya","ankara","antalya","artvin","aydin","balikesir","bilecik","bingol","bitlis","bolu","burdur","bursa","canakkale","cankiri","corum","denizli","diyarbakir","edirne","elazig","erzincan","erzurum","eskisehir","gaziantep","giresun","gumushane","hakkari","hatay","isparta","mersin","istanbul","izmir","kars","kastamonu","kayseri","kirklareli","kirsehir","kocaeli","konya","kutahya","malatya","manisa","kahramanmaras","mardin","mugla","mus","nevsehir","nigde","ordu","rize","sakarya","samsun","siirt","sinop","sivas","tekirdag","tokat","trabzon","tunceli","sanliurfa","usak","van","yozgat","zonguldak","aksaray","bayburt","karaman","kirikkale","batman","sirnak","bartin","ardahan","igdir","yalova","karabuk","kilis","osmaniye","duzce"]},"description":"İl slug’ı. Verilmezse `istanbul`. Bilinmeyen slug 400 döndürür — sessizce varsayılana düşmez."},{"name":"lat","in":"query","required":false,"schema":{"type":"number","minimum":-90,"maximum":90},"description":"`lon` ile birlikte. Koordinat, beslenen illerin EN YAKININA yuvarlanır; yuvarlama `data.resolvedFrom` ile bildirilir. `city` verildiyse yok sayılır."},{"name":"lon","in":"query","required":false,"schema":{"type":"number","minimum":-180,"maximum":180},"description":"`lat` ile birlikte."},{"name":"currencies","in":"query","required":false,"schema":{"type":"string","example":"USD,EUR,GBP"},"description":"Virgülle ayrılmış ISO 4217 kodları (en çok 25). Varsayılan `USD,EUR,GBP`. TCMB’de bulunmayan kodlar (ALTIN/XAU dâhil) sessizce elenir."},{"name":"tz","in":"query","required":false,"schema":{"type":"string","example":"Europe/Istanbul"},"description":"IANA saat dilimi; `date` alanı bununla biçimlenir. Varsayılan `Europe/Istanbul`. **Verilmesi önerilir:** sunucu UTC+2’de, yanlış dilim gece yarısı civarı bir GÜN kaymasına yol açar. Geçersiz dilim 400 döndürür."},{"name":"locale","in":"query","required":false,"schema":{"type":"string","example":"tr-TR"},"description":"BCP 47 yerel ayarı; `date` metninin dili. Varsayılan `tr-TR`."}],"responses":{"200":{"description":"Üst bar verisi.","content":{"application/json":{"schema":{"type":"object","required":["date","timezone","now","weather","rates","prayer"],"properties":{"date":{"type":"string","example":"11 Eylül 2026 Cuma"},"timezone":{"type":"string","example":"Europe/Istanbul"},"now":{"type":"string","format":"date-time","description":"UTC."},"weather":{"type":"object","required":["data","meta"],"properties":{"data":{"oneOf":[{"type":"object","required":["city","citySlug","plate","lat","lon","temp","feelsLike","condition","conditionLabel","humidity","wind","windDirection","pressure","isDay","hourly","daily","resolvedFrom"],"properties":{"city":{"type":"string","example":"İstanbul"},"citySlug":{"type":"string","example":"istanbul"},"plate":{"type":"integer","example":34},"lat":{"type":"number","example":41.0053},"lon":{"type":"number","example":28.977},"temp":{"type":"integer","description":"°C","example":22},"feelsLike":{"type":"integer","description":"°C","example":21},"condition":{"type":"string","enum":["clear-day","clear-night","partly-cloudy-day","partly-cloudy-night","overcast","fog","drizzle","showers","rain","sleet","heavy-sleet","snow","heavy-snow","thunderstorm","thunderstorm-snow"],"example":"partly-cloudy-day","description":"Kararlı makine kodu. İkon eşlemesi için bunu kullanın, `conditionLabel`i değil."},"conditionLabel":{"type":"string","example":"Parçalı bulutlu"},"humidity":{"type":"integer","description":"%","example":63},"wind":{"type":"integer","description":"km/sa","example":14},"windDirection":{"type":"string","example":"KD"},"pressure":{"type":"integer","description":"hPa","example":1011},"isDay":{"type":"boolean","example":true},"hourly":{"type":"array","description":"Şu andan itibaren 24 saat.","items":{"type":"object","required":["time","temp","condition","conditionLabel","precipitation"],"properties":{"time":{"type":"string","format":"date-time","description":"UTC."},"temp":{"type":"integer","example":21},"condition":{"type":"string","enum":["clear-day","clear-night","partly-cloudy-day","partly-cloudy-night","overcast","fog","drizzle","showers","rain","sleet","heavy-sleet","snow","heavy-snow","thunderstorm","thunderstorm-snow"],"example":"partly-cloudy-day","description":"Kararlı makine kodu. İkon eşlemesi için bunu kullanın, `conditionLabel`i değil."},"conditionLabel":{"type":"string","example":"Parçalı bulutlu"},"precipitation":{"type":"integer","description":"Yağış olasılığı, %","example":10}}}},"daily":{"type":"array","description":"7 günlük. `date` ilin YEREL takvim günüdür.","items":{"type":"object","required":["date","high","low","condition","conditionLabel","precipitation","windMax","sunrise","sunset","uvMax"],"properties":{"date":{"type":"string","example":"2026-09-11"},"high":{"type":"integer","example":26},"low":{"type":"integer","example":18},"condition":{"type":"string","enum":["clear-day","clear-night","partly-cloudy-day","partly-cloudy-night","overcast","fog","drizzle","showers","rain","sleet","heavy-sleet","snow","heavy-snow","thunderstorm","thunderstorm-snow"],"example":"partly-cloudy-day","description":"Kararlı makine kodu. İkon eşlemesi için bunu kullanın, `conditionLabel`i değil."},"conditionLabel":{"type":"string","example":"Az bulutlu"},"precipitation":{"type":"integer","example":10},"windMax":{"type":"integer","example":22},"sunrise":{"type":["string","null"],"format":"date-time","description":"UTC."},"sunset":{"type":["string","null"],"format":"date-time","description":"UTC."},"uvMax":{"type":"integer","example":6}}}},"resolvedFrom":{"oneOf":[{"type":"object","required":["lat","lon","distanceKm"],"properties":{"lat":{"type":"number","example":41.07},"lon":{"type":"number","example":28.25},"distanceKm":{"type":"number","example":61.4}}},{"type":"null"}],"description":"`lat`/`lon` ile istendiyse hangi noktadan ne kadar uzağa yuvarlandığı. `city` ile istendiyse null."}}},{"type":"null"}],"description":"Tolerans aşıldıysa **null**. Eski veriyle doldurulmaz: yanlış bilgi, yokluğundan kötüdür. `meta.reason` nedeni söyler."},"meta":{"type":"object","required":["service","fetchedAt","age","staleAfterSec","stale"],"properties":{"service":{"type":"string","example":"weather"},"fetchedAt":{"type":["string","null"],"format":"date-time","description":"Verinin upstream’den çekildiği an (UTC)."},"age":{"type":["integer","null"],"example":365,"description":"Verinin yaşı (saniye). Veri boş dönse bile doldurulur — arıza teşhisi için."},"staleAfterSec":{"type":"integer","example":10800,"description":"Bu yaş aşılırsa veri bayat sayılır ve `data` boşalır."},"stale":{"type":"boolean","example":false},"reason":{"type":"string","enum":["stale","missing"],"description":"`data` neden boş. Yalnız `data: null` iken bulunur."}}}}},"rates":{"type":"object","required":["data","meta"],"properties":{"data":{"oneOf":[{"type":"object","required":["date","rates"],"properties":{"date":{"type":"string","example":"2026-09-11","description":"TCMB bülten tarihi. Hafta sonu/tatilde son iş gününe ait olur."},"rates":{"type":"array","items":{"type":"object","required":["code","symbol","raw","value","direction","changePercent","history"],"properties":{"code":{"type":"string","example":"USD"},"symbol":{"type":"string","example":"DOLAR"},"raw":{"type":"number","description":"1 birimin TL karşılığı. Otorite alan budur.","example":48.5912},"value":{"type":"string","example":"42,17","description":"tr-TR biçimli kolaylık alanı."},"direction":{"type":"string","enum":["up","down","flat"]},"changePercent":{"type":"number","description":"İşaretli yüzde, bir önceki bültene göre.","example":0.34},"history":{"type":"array","items":{"type":"number","example":48.41},"description":"Son ~12 iş günü, ESKİDEN YENİYE."}}}}}},{"type":"null"}],"description":"Tolerans aşıldıysa **null**. Eski veriyle doldurulmaz: yanlış bilgi, yokluğundan kötüdür. `meta.reason` nedeni söyler."},"meta":{"type":"object","required":["service","fetchedAt","age","staleAfterSec","stale"],"properties":{"service":{"type":"string","example":"weather"},"fetchedAt":{"type":["string","null"],"format":"date-time","description":"Verinin upstream’den çekildiği an (UTC)."},"age":{"type":["integer","null"],"example":365,"description":"Verinin yaşı (saniye). Veri boş dönse bile doldurulur — arıza teşhisi için."},"staleAfterSec":{"type":"integer","example":10800,"description":"Bu yaş aşılırsa veri bayat sayılır ve `data` boşalır."},"stale":{"type":"boolean","example":false},"reason":{"type":"string","enum":["stale","missing"],"description":"`data` neden boş. Yalnız `data: null` iken bulunur."}}}}},"prayer":{"type":"object","required":["data","meta"],"properties":{"data":{"oneOf":[{"type":"object","required":["city","citySlug","plate","timezone","source","today","next","days"],"properties":{"city":{"type":"string","example":"İstanbul"},"citySlug":{"type":"string","example":"istanbul"},"plate":{"type":"integer","example":34},"timezone":{"type":"string","example":"Europe/Istanbul"},"source":{"type":"string","example":"Diyanet İşleri Başkanlığı","description":"Vakitlerin kaynağı. Yayımlarken belirtmeniz beklenir."},"today":{"type":"object","required":["date","hijri","times"],"properties":{"date":{"type":"string","example":"2026-09-12","description":"Yerel takvim günü."},"hijri":{"type":"string","example":"1 Rebiulahir 1448"},"times":{"type":"array","items":{"type":"object","required":["key","label","time","at"],"properties":{"key":{"type":"string","enum":["imsak","gunes","ogle","ikindi","aksam","yatsi"],"example":"ogle","description":"Kararlı makine kodu. Etiket yerine bunu kullanın."},"label":{"type":"string","example":"Öğle"},"time":{"type":"string","example":"13:06","description":"YEREL duvar saati (`data.timezone`). Yayıncının basacağı metin."},"at":{"type":"string","format":"date-time","description":"Aynı anın UTC damgası — geri sayım ve karşılaştırma için."}}},"description":"Günün altı vakti, sırayla."}}},"next":{"description":"Sıradaki vakit ve ona kalan süre. Yatsıdan sonra YARININ imsakını gösterir ve `tomorrow: true` der. Elimizde yarın yoksa `null`.","oneOf":[{"type":"object","required":["key","label","time","at","inSec","tomorrow"],"properties":{"key":{"type":"string","enum":["imsak","gunes","ogle","ikindi","aksam","yatsi"],"example":"ogle","description":"Kararlı makine kodu. Etiket yerine bunu kullanın."},"label":{"type":"string","example":"Öğle"},"time":{"type":"string","example":"13:06","description":"YEREL duvar saati (`data.timezone`). Yayıncının basacağı metin."},"at":{"type":"string","format":"date-time","description":"Aynı anın UTC damgası — geri sayım ve karşılaştırma için."},"inSec":{"type":"integer","example":2720,"description":"Vakte kalan saniye."},"tomorrow":{"type":"boolean","example":false}}},{"type":"null"}]},"days":{"type":"array","items":{"type":"object","required":["date","hijri","times"],"properties":{"date":{"type":"string","example":"2026-09-12","description":"Yerel takvim günü."},"hijri":{"type":"string","example":"1 Rebiulahir 1448"},"times":{"type":"array","items":{"type":"object","required":["key","label","time","at"],"properties":{"key":{"type":"string","enum":["imsak","gunes","ogle","ikindi","aksam","yatsi"],"example":"ogle","description":"Kararlı makine kodu. Etiket yerine bunu kullanın."},"label":{"type":"string","example":"Öğle"},"time":{"type":"string","example":"13:06","description":"YEREL duvar saati (`data.timezone`). Yayıncının basacağı metin."},"at":{"type":"string","format":"date-time","description":"Aynı anın UTC damgası — geri sayım ve karşılaştırma için."}}},"description":"Günün altı vakti, sırayla."}}},"description":"Bugünden başlayan pencere."}}},{"type":"null"}],"description":"Tolerans aşıldıysa **null**. Eski veriyle doldurulmaz: yanlış bilgi, yokluğundan kötüdür. `meta.reason` nedeni söyler."},"meta":{"type":"object","required":["service","fetchedAt","age","staleAfterSec","stale"],"properties":{"service":{"type":"string","example":"weather"},"fetchedAt":{"type":["string","null"],"format":"date-time","description":"Verinin upstream’den çekildiği an (UTC)."},"age":{"type":["integer","null"],"example":365,"description":"Verinin yaşı (saniye). Veri boş dönse bile doldurulur — arıza teşhisi için."},"staleAfterSec":{"type":"integer","example":10800,"description":"Bu yaş aşılırsa veri bayat sayılır ve `data` boşalır."},"stale":{"type":"boolean","example":false},"reason":{"type":"string","enum":["stale","missing"],"description":"`data` neden boş. Yalnız `data: null` iken bulunur."}}}}}}}}}},"400":{"description":"Geçersiz parametre (bilinmeyen il, bozuk saat dilimi…).","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem ayrıntısı.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}},"401":{"description":"Anahtar eksik, geçersiz ya da iptal edilmiş.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem ayrıntısı.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}},"429":{"description":"İki ayrı durum, iki ayrı `type`: `rate-limit` (ani yük — birkaç saniye bekleyin) ve `quota-exceeded` (aylık tavan — ay başında sıfırlanır). Gereken davranış tamamen farklı olduğu için ayırt edin; `Retry-After` her ikisinde de kaç saniye bekleneceğini söyler.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem ayrıntısı.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}}}}}}}