İçeriğe geç

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.

https://api.acikkuran.com/v1Anahtar al

Üç adımda ilk istek

  1. 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.
  2. 2Her isteğe anahtarını Authorization: Bearer <anahtar> başlığıyla ekle.
  3. 3İlk isteğini gönder:
  4. 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."
  }
}
DurumKodAçıklama
400query_too_shortArama en az 3 karakter olmalı.
400query_is_referenceArama bir ayet ya da sure numarasına benziyor. Ayet endpoint'ini kullan.
400invalid_pagepage pozitif bir sayı olmalı.
400invalid_languagelang yalnızca tr ya da en olabilir.
401missing_api_keyİstekte Authorization başlığı yok.
401invalid_api_keyAnahtar yanlış ya da iptal edilmiş.
404surah_not_foundSure numarası 1 ile 114 arasında olmalı.
404verse_not_foundSurede bu numarada bir ayet yok.
404author_not_foundBu mütercimin bu ayet için meali yok. Geçerli değerler /v1/authors içinde.
404page_not_foundMushaf sayfaları 1 ile 604 arasında.
404root_not_foundBu Latin yazımıyla bir kök yok.
404not_foundBöyle bir endpoint yok.
429rate_limitedLimit aşıldı. Retry-After kadar bekle.
500internal_errorBizim 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

GET/v1/surahs

114 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_..."
GET/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/authors içinde.
curl "https://api.acikkuran.com/v1/surahs/36?author=105" \
  -H "Authorization: Bearer ak_..."
GET/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/authors içinde.
curl "https://api.acikkuran.com/v1/surahs/2/verses/255" \
  -H "Authorization: Bearer ak_..."
GET/v1/surahs/{id}/verses/{verse}/translations

Ayetin 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_..."
GET/v1/surahs/{id}/verses/{verse}/words

Ayet 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_..."
GET/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/authors içinde.
curl "https://api.acikkuran.com/v1/pages/50" \
  -H "Authorization: Bearer ak_..."

Kökler

GET/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_..."
GET/v1/roots/{latin}/verses

Kö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/authors içinde.
  • pagesorguda · isteğe bağlıSayfa numarası. Verilmezse 1.
  • limitsorguda · isteğe bağlıSayfa başına ayet sayısı, en fazla 100. Verilmezse 20.
curl "https://api.acikkuran.com/v1/roots/ktb/verses?page=2" \
  -H "Authorization: Bearer ak_..."

Mealler ve arama

GET/v1/authors

Mealler ve mütercimleri. Buradaki id değerleri author parametresinde kullanılır.

curl "https://api.acikkuran.com/v1/authors" \
  -H "Authorization: Bearer ak_..."
GET/v1/search

Meallerde, 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ıtr ya da en. Verilmezse tr.
  • 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.