Açık Kuran API
Kur'an'ın Arapçasını, okunuşlarını, meallerini, dipnotlarını, kelime kelime dilbilgisini ve kökleri kendi uygulamanda kullan. Ücretsiz; bir Açık Kuran hesabı ve bir anahtar yeterli.
Üç adımda ilk istek
- 1Açık Kuran hesabınla giriş yap ve aşağıdan bir anahtar oluştur. Anahtar yalnızca bir kez gösterilir, güvenli bir yere kaydet.
- 2Her isteğe anahtarını
Authorization: Bearer <anahtar>başlığıyla ekle. - 3İlk isteğini gönder:
curl "https://api.acikkuran.com/v1/surahs/112/verses/1?author=105" \ -H "Authorization: Bearer ak_..."
Anahtarların
Her proje için ayrı bir anahtar oluşturabilirsin. Bir anahtarın sızdığını düşünüyorsan iptal edip yenisini oluştur.
Anahtarını sunucuda tut
Anahtar, isteğin senden geldiğini gösterir ve limitler ona göre sayılır. Tarayıcıda ya da mobil uygulamanın içinde açıkta duran bir anahtarı herkes kopyalayabilir; istekleri kendi sunucundan gönder. API tarayıcıdan doğrudan çağrılmaya açık değildir.
Authorization: Bearer ak_...
Her anahtarın kendi limiti var
Limitler anahtar başına sayılır. Aşıldığında API 429 döner ve Retry-After başlığı kaç saniye beklemen gerektiğini söyler. Cevapları önbelleğe almak limitleri rahat kullanmanın en kolay yolu: metin nadiren değişir.
Dakikada 60 istek
Arama dışındaki bütün endpoint'ler için.
Dakikada 20 arama
/v1/search daha ağır olduğu için ayrıca sayılır.
Günde 10.000 istek
Gün, UTC'ye göre gece yarısı sıfırlanır.
- X-RateLimit-Limitİçinde bulunduğun dakikalık limit.
- X-RateLimit-RemainingBu dakika içinde kalan istek sayısı.
- X-RateLimit-ResetDakikalık sayacın sıfırlanmasına kalan saniye.
Hata cevapları
Başarılı cevaplar 200 ile { data } döner; sayfalı listelerde yanında meta gelir. Hatalarda HTTP durum kodu ve { error: { code, message } } döner.
{
"error": {
"code": "surah_not_found",
"message": "No such surah. Surah numbers run from 1 to 114."
}
}| Durum | Kod | Açıklama |
|---|---|---|
| 400 | query_too_short | Arama en az 3 karakter olmalı. |
| 400 | query_is_reference | Arama bir ayet ya da sure numarasına benziyor. Ayet endpoint'ini kullan. |
| 400 | invalid_page | page pozitif bir sayı olmalı. |
| 400 | invalid_language | lang yalnızca tr ya da en olabilir. |
| 401 | missing_api_key | İstekte Authorization başlığı yok. |
| 401 | invalid_api_key | Anahtar yanlış ya da iptal edilmiş. |
| 404 | surah_not_found | Sure numarası 1 ile 114 arasında olmalı. |
| 404 | verse_not_found | Surede bu numarada bir ayet yok. |
| 404 | author_not_found | Bu mütercimin bu ayet için meali yok. Geçerli değerler /v1/authors içinde. |
| 404 | page_not_found | Mushaf sayfaları 1 ile 604 arasında. |
| 404 | root_not_found | Bu Latin yazımıyla bir kök yok. |
| 404 | not_found | Böyle bir endpoint yok. |
| 429 | rate_limited | Limit aşıldı. Retry-After kadar bekle. |
| 500 | internal_error | Bizim tarafımızda bir sorun oluştu. |
Endpoint listesi
Bütün endpoint'ler GET ile çalışır ve https://api.acikkuran.com/v1 adresinin altındadır. Süslü parantez içindeki değerler ({id} gibi) adrese yazılır, diğerleri ?author=105 gibi sorgu parametresi olarak eklenir.
Sureler ve ayetler
/v1/surahs114 surenin listesi: adları, ayet sayıları, başladıkları sayfa ve tilavet kayıtları.
curl "https://api.acikkuran.com/v1/surahs" \ -H "Authorization: Bearer ak_..."
/v1/surahs/{id}Surenin bütün ayetleri, seçilen meal ve dipnotlarıyla.
Parametreler
- idadreste · zorunluSure numarası, 1 ile 114 arası.
- authorsorguda · isteğe bağlıMeal numarası. Verilmezse
105(Erhan Aktaş). Değerler/v1/authorsiçinde.
curl "https://api.acikkuran.com/v1/surahs/36?author=105" \ -H "Authorization: Bearer ak_..."
/v1/surahs/{id}/verses/{verse}Tek ayet: Arapçası, okunuşu, meali ve dipnotları.
Parametreler
- idadreste · zorunluSure numarası, 1 ile 114 arası.
- verseadreste · zorunluAyet numarası.
- authorsorguda · isteğe bağlıMeal numarası. Verilmezse
105(Erhan Aktaş). Değerler/v1/authorsiçinde.
curl "https://api.acikkuran.com/v1/surahs/2/verses/255" \ -H "Authorization: Bearer ak_..."
/v1/surahs/{id}/verses/{verse}/translationsAyetin bütün mealleri, dipnotlarıyla.
Parametreler
- idadreste · zorunluSure numarası, 1 ile 114 arası.
- verseadreste · zorunluAyet numarası.
curl "https://api.acikkuran.com/v1/surahs/2/verses/255/translations" \ -H "Authorization: Bearer ak_..."
/v1/surahs/{id}/verses/{verse}/wordsAyet kelime kelime: Arapçası, okunuşu, anlamı, kökü ve dilbilgisi.
Parametreler
- idadreste · zorunluSure numarası, 1 ile 114 arası.
- verseadreste · zorunluAyet numarası.
curl "https://api.acikkuran.com/v1/surahs/1/verses/2/words" \ -H "Authorization: Bearer ak_..."
/v1/pages/{page}Mushafın bir sayfasındaki ayetler.
Parametreler
- pageadreste · zorunluMushaf sayfası, 1 ile 604 arası.
- authorsorguda · isteğe bağlıMeal numarası. Verilmezse
105(Erhan Aktaş). Değerler/v1/authorsiçinde.
curl "https://api.acikkuran.com/v1/pages/50" \ -H "Authorization: Bearer ak_..."
Kökler
/v1/roots/{latin}Bir kökün Arapçası, anlamı ve Kur'an'daki biçimleri.
Parametreler
- latinadreste · zorunluKökün Latin harflerle yazımı, örneğin
ktb.
curl "https://api.acikkuran.com/v1/roots/ktb" \ -H "Authorization: Bearer ak_..."
/v1/roots/{latin}/versesKökün geçtiği ayetler, sayfa sayfa. Cevaptaki meta toplam sayıyı ve sayfa sayısını verir.
Parametreler
- latinadreste · zorunluKökün Latin harflerle yazımı, örneğin
ktb. - authorsorguda · isteğe bağlıMeal numarası. Verilmezse
105(Erhan Aktaş). Değerler/v1/authorsiçinde. - pagesorguda · isteğe bağlıSayfa numarası. Verilmezse
1. - limitsorguda · isteğe bağlıSayfa başına ayet sayısı, en fazla
100. Verilmezse20.
curl "https://api.acikkuran.com/v1/roots/ktb/verses?page=2" \ -H "Authorization: Bearer ak_..."
Mealler ve arama
/v1/authorsMealler ve mütercimleri. Buradaki id değerleri author parametresinde kullanılır.
curl "https://api.acikkuran.com/v1/authors" \ -H "Authorization: Bearer ak_..."
/v1/searchMeallerde, Arapçada ve okunuşta tam metin arama. En iyi eşleşme önce gelir, sayfa başına 30 sonuç.
Parametreler
- qsorguda · zorunluAranacak metin, en az 3 karakter.
- langsorguda · isteğe bağlı
trya daen. Verilmezsetr. - pagesorguda · isteğe bağlıSayfa numarası. Verilmezse
1.
curl "https://api.acikkuran.com/v1/search?q=sabır" \ -H "Authorization: Bearer ak_..."
Örnek cevap (kısaltılmış)
curl "https://api.acikkuran.com/v1/surahs/112/verses/1?author=105" \ -H "Authorization: Bearer ak_..."
{
"data": {
"id": 6222,
"surah": {
"id": 112,
"name": "İhlas",
"name_en": "Al-Ikhlas",
"slug": "ihlas",
"verse_count": 4,
"page_number": 604,
"name_original": "سورة الإخلاص"
},
"verse_number": 1,
"verse": "قُلْ هُوَ اللّٰهُ اَحَدٌۚ",
"page": 604,
"juz_number": 30,
"transcription": "Kul huvallahu ehad.",
"transcription_en": "Qul huwa Allahu ahad",
"translation": {
"id": 327506,
"author": {
"id": 105,
"name": "Erhan Aktaş",
"language": "tr"
},
"text": "De ki: \"O Allah[1] Ehad'dır.[2]\"",
"footnotes": [
{
"id": 42077,
"number": 2,
"text": "Bölünmesi ve artması mümkün olmayan, bir tek, yegâne varlık…"
}
]
}
}
}Sık sorulanlar
Hayır. API ücretsiz; tek şart bir Açık Kuran hesabı.
Eski API artık sürdürülmüyor. Aynı veri, daha düzenli bir biçimde /v1 altında. Endpoint'lerin yeni adları bu sayfada.
Projeni ve yaklaşık ihtiyacını selam@acikkuran.com adresine yaz, anahtarının limitini birlikte belirleyelim.
MCP sunucusu yapay zekâ asistanları içindir ve senin adına notlarına da erişebilir. API ise kendi uygulamanı yazarken kullanacağın, yalnızca Kur'an verisini okuyan bir arayüz.