{"openapi":"3.0.0","info":{"title":"Ezan Vakti API - İmsakiyem","version":"1.1.0","description":"T.C. Diyanet İşleri Başkanlığı tarafından yayınlanan, dünya genelindeki ülkelerin ezan vakitlerini haftalık, aylık ve yıllık olarak sunan API hizmetidir. v1 uç noktaları (`/api/...`) değişmeden çalışır; yeni uç noktalar `/api/v2/...` altındadır. Kaynak kodlarına GitHub üzerinden ulaşabilirsiniz: [GitHub Repository](https://github.com/karademirmustafa/ezanvakti-imsakiyem-api)"},"servers":[{"url":"https://ezanvakti.imsakiyem.com","description":"Production server"},{"url":"http://localhost:3000","description":"Development server"}],"paths":{"/api/prayer-times/{districtId}/{period}":{"get":{"summary":"Belirli bir bölge için namaz vakitlerini alır.","description":"Verilen ilçe ID'sine göre belirtilen periyottaki namaz vakitlerini döndürür. Opsiyonel olarak sayfalama ve tarih aralığı desteği sağlar.","tags":["Namaz Vakitleri"],"parameters":[{"in":"path","name":"districtId","required":true,"description":"İlçe ID'si.","schema":{"type":"string"}},{"in":"path","name":"period","required":false,"description":"Namaz vakitleri periyodu (daily, weekly, monthly, yearly).","schema":{"type":"string","enum":["daily","weekly","monthly","yearly"],"default":"daily"}},{"in":"query","name":"startDate","required":false,"description":"Başlangıç tarihi (YYYY-MM-DD formatında, opsiyonel).","schema":{"type":"string","format":"date"}},{"in":"query","name":"endDate","required":false,"description":"Bitiş tarihi (YYYY-MM-DD formatında, opsiyonel).","schema":{"type":"string","format":"date"}},{"in":"query","name":"page","required":false,"description":"Sayfa numarası (opsiyonel, sayfalama için kullanılır).","schema":{"type":"integer"}},{"in":"query","name":"limit","required":false,"description":"Sayfa başına kayıt sayısı (opsiyonel, sayfalama için kullanılır).","schema":{"type":"integer"}}],"responses":{"200":{"description":"Namaz vakitleri başarıyla alındı.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrayerTimeListResponse"}}}},"404":{"description":"Bölge bulunamadı veya veri yok."}}}},"/api/locations/search/{type}":{"get":{"summary":"Konum arama işlemi.","description":"Ülke, eyalet veya ilçe gibi konum tipleri için arama yapar.","tags":["Lokasyonlar"],"parameters":[{"in":"path","name":"type","required":true,"description":"Aranacak konum tipi (countries, states, districts).","schema":{"type":"string","enum":["countries","states","districts"]}},{"in":"query","name":"q","required":true,"description":"Aranacak kelime.","schema":{"type":"string"}}],"responses":{"200":{"description":"Lokasyonlar başarıyla alındı.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/LocationsSearchResponse"}}}}},"404":{"description":"Lokasyon bulunamadı."}}}},"/api/locations/{type}/{id}":{"get":{"summary":"Lokasyon detaylarını alır.","description":"Verilen ID'ye göre ülke, eyalet veya ilçe detaylarını döndürür.","tags":["Lokasyonlar"],"parameters":[{"in":"path","name":"type","required":true,"description":"Lokasyon tipi (countries, states, districts).","schema":{"type":"string","enum":["countries","states","districts"]}},{"in":"path","name":"id","required":true,"description":"Lokasyon ID'si.","schema":{"type":"string"}}],"responses":{"200":{"description":"Lokasyon detayları başarıyla alındı.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationSingleResponse"}}}},"404":{"description":"Lokasyon bulunamadı."}}}},"/api/locations/{type}":{"get":{"summary":"Lokasyonları listeler.","description":"Ülke, eyalet veya ilçe gibi lokasyonları liste halinde döndürür. Eyalet veya ilçe listelemesi için üst ID gereklidir.","tags":["Lokasyonlar"],"parameters":[{"in":"path","name":"type","required":true,"description":"Lokasyon tipi (countries, states, districts).","schema":{"type":"string","enum":["countries","states","districts"]}},{"in":"query","name":"countryId","required":false,"description":"Ülke ID'si (eyalet veya ilçe listelemesi için zorunlu).","schema":{"type":"string"}},{"in":"query","name":"stateId","required":false,"description":"Eyalet ID'si (ilçe listelemesi için zorunlu).","schema":{"type":"string"}}],"responses":{"200":{"description":"Lokasyonlar başarıyla alındı.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationsListResponse"}}}},"404":{"description":"Lokasyon bulunamadı."}}}},"/api/v2/locations/countries":{"get":{"summary":"Ülkeleri listeler","description":"Tüm ülkeler.","tags":["v2 - Konumlar"],"parameters":null,"responses":{"200":{"description":"Başarılı","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2Response"}}}},"400":{"description":"Geçersiz parametre (error.code = VALIDATION_ERROR, INVALID_DATE, RANGE_TOO_LARGE ...)."},"404":{"description":"Kaynak bulunamadı (hata kodu error.code alanındadır)."}}}},"/api/v2/locations/countries/{id}":{"get":{"summary":"Ülke detayı","description":"Ülke, ilçe sayısı ve bölge (`admin_region`) listesi.","tags":["v2 - Konumlar"],"parameters":[{"in":"path","name":"id","required":true,"description":"Ülke ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Başarılı","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2Response"}}}},"400":{"description":"Geçersiz parametre (error.code = VALIDATION_ERROR, INVALID_DATE, RANGE_TOO_LARGE ...)."},"404":{"description":"Kaynak bulunamadı (hata kodu error.code alanındadır)."}}}},"/api/v2/locations/districts":{"get":{"summary":"İlçeleri listeler","description":"Ülke, eyalet, bölge veya ada göre filtrelenebilir, sayfalıdır.","tags":["v2 - Konumlar"],"parameters":[{"in":"query","name":"countryId","required":false,"description":"Ülke ID","schema":{"type":"string"}},{"in":"query","name":"stateId","required":false,"description":"Eyalet/il ID","schema":{"type":"string"}},{"in":"query","name":"region","required":false,"description":"Bölge adı (`admin_region`)","schema":{"type":"string"}},{"in":"query","name":"q","required":false,"description":"Ad filtresi (aksan duyarsız)","schema":{"type":"string"}},{"in":"query","name":"page","required":false,"description":"Sayfa (varsayılan 1)","schema":{"type":"integer"}},{"in":"query","name":"limit","required":false,"description":"Sayfa boyutu (1-500, varsayılan 50)","schema":{"type":"integer"}}],"responses":{"200":{"description":"Başarılı","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2Response"}}}},"400":{"description":"Geçersiz parametre (error.code = VALIDATION_ERROR, INVALID_DATE, RANGE_TOO_LARGE ...)."}}}},"/api/v2/locations/districts/{id}":{"get":{"summary":"İlçe detayı","description":"Koordinat, güven düzeyi, saat dilimi, bölge ve `display_name` ile.","tags":["v2 - Konumlar"],"parameters":[{"in":"path","name":"id","required":true,"description":"İlçe ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Başarılı","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2Response"}}}},"400":{"description":"Geçersiz parametre (error.code = VALIDATION_ERROR, INVALID_DATE, RANGE_TOO_LARGE ...)."},"404":{"description":"Kaynak bulunamadı (hata kodu error.code alanındadır)."}}}},"/api/v2/locations/search":{"get":{"summary":"İlçe arar","description":"Aksan duyarsız arama (`sanliurfa` = ŞANLIURFA). Ada göre başlayanlar önce gelir.","tags":["v2 - Konumlar"],"parameters":[{"in":"query","name":"q","required":true,"description":"Aranan metin (en az 2 karakter)","schema":{"type":"string"}},{"in":"query","name":"country","required":false,"description":"Ülke ID ile sınırla","schema":{"type":"string"}},{"in":"query","name":"limit","required":false,"description":"1-50, varsayılan 10","schema":{"type":"integer"}}],"responses":{"200":{"description":"Başarılı","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2Response"}}}},"400":{"description":"Geçersiz parametre (error.code = VALIDATION_ERROR, INVALID_DATE, RANGE_TOO_LARGE ...)."}}}},"/api/v2/locations/nearest":{"get":{"summary":"Konuma en yakın ilçeler","description":"Verilen koordinata yakınlığa göre sıralar. Yarıçap içinde ilçe yoksa 404 (NO_DISTRICT_NEARBY) döner.","tags":["v2 - Konumlar"],"parameters":[{"in":"query","name":"lat","required":true,"description":"Enlem (-90..90)","schema":{"type":"number"}},{"in":"query","name":"lon","required":true,"description":"Boylam (-180..180)","schema":{"type":"number"}},{"in":"query","name":"radius_km","required":false,"description":"Yarıçap km (1-500, varsayılan 50)","schema":{"type":"number"}},{"in":"query","name":"limit","required":false,"description":"1-20, varsayılan 5","schema":{"type":"integer"}}],"responses":{"200":{"description":"Başarılı","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2Response"}}}},"400":{"description":"Geçersiz parametre (error.code = VALIDATION_ERROR, INVALID_DATE, RANGE_TOO_LARGE ...)."},"404":{"description":"Kaynak bulunamadı (hata kodu error.code alanındadır)."}}}},"/api/v2/times":{"get":{"summary":"Namaz vakitleri","description":"İlçe ID'si (`district`) ya da koordinat (`lat`+`lon`) ile vakitler. Parametresiz tarih = bugün. Yanıttaki `times` her zaman dizidir.","tags":["v2 - Namaz Vakitleri"],"parameters":[{"in":"query","name":"district","description":"İlçe ID. `district` ya da `lat`+`lon` verilir, ikisi birlikte verilemez.","schema":{"type":"string"}},{"in":"query","name":"lat","description":"Enlem (en yakın ilçeyi bulur)","schema":{"type":"number"}},{"in":"query","name":"lon","description":"Boylam","schema":{"type":"number"}},{"in":"query","name":"radius_km","description":"En yakın ilçe arama yarıçapı (varsayılan 50)","schema":{"type":"number"}},{"in":"query","name":"date","description":"Tek gün ya da `period` için başlangıç (YYYY-AA-GG). Verilmezse ilçenin yerel bugünü.","schema":{"type":"string"}},{"in":"query","name":"period","description":"daily (varsayılan), weekly, monthly, yearly","schema":{"type":"string","enum":["daily","weekly","monthly","yearly"]}},{"in":"query","name":"from","description":"Aralık başı (to ile birlikte, en fazla 366 gün)","schema":{"type":"string"}},{"in":"query","name":"to","description":"Aralık sonu","schema":{"type":"string"}}],"responses":{"200":{"description":"Başarılı","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2Response"}}}},"400":{"description":"Geçersiz parametre (error.code = VALIDATION_ERROR, LOCATION_REQUIRED, AMBIGUOUS_LOCATION, INVALID_DATE, RANGE_TOO_LARGE ...)."},"404":{"description":"Bulunamadı (DISTRICT_NOT_FOUND, NO_DISTRICT_NEARBY, NO_TIMES_FOR_RANGE ...)."}}}},"/api/v2/times/next":{"get":{"summary":"Sıradaki vakit","description":"Şu anki ve sıradaki vakit ile kalan saniye (ilçenin saat dilimine göre).","tags":["v2 - Namaz Vakitleri"],"parameters":[{"in":"query","name":"district","description":"İlçe ID. `district` ya da `lat`+`lon` verilir, ikisi birlikte verilemez.","schema":{"type":"string"}},{"in":"query","name":"lat","description":"Enlem (en yakın ilçeyi bulur)","schema":{"type":"number"}},{"in":"query","name":"lon","description":"Boylam","schema":{"type":"number"}},{"in":"query","name":"radius_km","description":"En yakın ilçe arama yarıçapı (varsayılan 50)","schema":{"type":"number"}}],"responses":{"200":{"description":"Başarılı","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2Response"}}}},"400":{"description":"Geçersiz parametre (error.code = VALIDATION_ERROR, LOCATION_REQUIRED, AMBIGUOUS_LOCATION, INVALID_DATE, RANGE_TOO_LARGE ...)."},"404":{"description":"Bulunamadı (DISTRICT_NOT_FOUND, NO_DISTRICT_NEARBY, NO_TIMES_FOR_RANGE ...)."}}}}},"components":{"schemas":{"PrayerTime":{"type":"object","properties":{"_id":{"type":"string"},"districtId":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"name_en":{"type":"string"},"url":{"type":"string"},"state_id":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"name_en":{"type":"string"}}},"country_id":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"name_en":{"type":"string"}}}}},"date":{"type":"string","format":"date"},"hijri_date":{"type":"object","properties":{"day":{"type":"integer"},"month":{"type":"integer"},"month_name":{"type":"string"},"month_name_en":{"type":"string"},"year":{"type":"integer"},"full_date":{"type":"string"}}},"times":{"type":"object","properties":{"imsak":{"type":"string","format":"time"},"gunes":{"type":"string","format":"time"},"ogle":{"type":"string","format":"time"},"ikindi":{"type":"string","format":"time"},"aksam":{"type":"string","format":"time"},"yatsi":{"type":"string","format":"time"}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"PrayerTimeListResponse":{"type":"object","properties":{"success":{"type":"boolean"},"code":{"type":"integer","example":200},"message":{"type":"string","example":"Namaz vakitleri başarıyla alındı."},"requestId":{"type":"string","example":"12345-abcdef"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PrayerTime"}},"pagination":{"type":"object","properties":{"currentPage":{"type":"integer"},"totalPages":{"type":"integer"},"totalItems":{"type":"integer"},"itemsPerPage":{"type":"integer"}}}}},"Country":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"name_en":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"State":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"name_en":{"type":"string"},"country_id":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"District":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"name_en":{"type":"string"},"state_id":{"type":"string"},"country_id":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"LocationsSearchResponse":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string","example":"Arama sonuçları başarıyla alındı."},"data":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/Country"},{"$ref":"#/components/schemas/State"},{"$ref":"#/components/schemas/District"}]}},"requestId":{"type":"string","example":"12345-abcdef"}}},"LocationSingleResponse":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string","example":"Lokasyon detayları başarıyla alındı."},"data":{"oneOf":[{"$ref":"#/components/schemas/Country"},{"$ref":"#/components/schemas/State"},{"$ref":"#/components/schemas/District"}]},"requestId":{"type":"string","example":"12345-abcdef"}}},"LocationsListResponse":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string","example":"Lokasyonlar başarıyla listelendi."},"data":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/Country"},{"$ref":"#/components/schemas/State"},{"$ref":"#/components/schemas/District"}]}},"requestId":{"type":"string","example":"12345-abcdef"}}},"LocationListResponse":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string","example":"Lokasyon detayları başarıyla alındı."},"data":{"oneOf":[{"$ref":"#/components/schemas/Country"},{"$ref":"#/components/schemas/State"},{"$ref":"#/components/schemas/District"}]},"requestId":{"type":"string","example":"12345-abcdef"}}},"V2Response":{"type":"object","description":"v2 yanıt zarfı. Başarıda `data` ve `meta`, hatada `error` ve `meta` döner. İstek kimliği `x-request-id` başlığındadır.","properties":{"success":{"type":"boolean"},"data":{"description":"Uç noktaya göre nesne ya da dizi."},"error":{"type":"object","properties":{"code":{"type":"string","example":"DISTRICT_NOT_FOUND"},"message":{"type":"string"},"details":{"type":"object"}}},"meta":{"type":"object","properties":{"version":{"type":"string","example":"2"}}}}}}},"tags":[],"requestId":"8453eb05-0f31-491c-9991-21227e55a4fa","timestamp":1793259350770}