Quran API Documentation

Public API for the Holy Quran with Somali translation

Overview

The Tafsiir Quran API serves the complete Quran (114 surahs) with Arabic text and Somali translation (tarjumaad). All endpoints are GET and return JSON. No authentication required.

Base URL

/api/quran

1. API Info

Get API name, version, and list of available endpoints.

GET /api/quran

No query parameters

{
  "name": "Tafsiir Quran API",
  "version": "1.0",
  "description": "Public API for the Holy Quran with Somali translation",
  "endpoints": [...],
  "usage": { "listSurahs": "...", "getSurah": "...", "getAyah": "..." }
}

2. List all surahs

Returns metadata for all 114 surahs (number, Arabic name, transliteration, ayah count, Makki/Madani).

GET /api/quran/surahs

{
  "total": 114,
  "surahs": [
    {
      "number": 1,
      "name": "الفاتحة",
      "nameTransliteration": "Al-Faatixa",
      "ayahCount": 7,
      "type": "Makki"
    },
    ...
  ]
}

3. Get a surah (all verses)

Returns all verses of a surah. Use surah number 1–114.

GET /api/quran?surah=1orGET /api/quran/surahs/1

{
  "surah": 1,
  "verses": [
    {
      "id": "1",
      "sura": "1",
      "aya": "1",
      "arabic_text": "بِسۡمِ ٱللَّهِ ٱلرَّحۡمَٰنِ ٱلرَّحِيمِ",
      "translation": "1. Waxaan Ku billaabi Magaca Alle...",
      "footnotes": ""
    },
    ...
  ]
}

Alternative path response includes surahName, surahNameArabic, ayahCount, type.

4. Get a single ayah (verse)

Returns one verse by surah and ayah number.

GET /api/quran?surah=1&ayah=2orGET /api/quran/surahs/1?ayah=2

{
  "surah": 1,
  "ayah": 2,
  "verse": {
    "id": "2",
    "sura": "1",
    "aya": "2",
    "arabic_text": "ٱلۡحَمۡدُ لِلَّهِ رَبِّ ٱلۡعَٰلَمِينَ",
    "translation": "2. Ammaan idilkeed iyo mahad waxaa leh Allaah...",
    "footnotes": ""
  }
}

Error responses

All errors return JSON with an error message.

400 — Bad request (e.g. surah not 1–114, missing required param)
404 — Surah or ayah not found
500 — Internal server error

Quick reference

Endpoint	Description
GET /api/quran	API info
GET /api/quran?surah=N	All verses of surah N (1–114)
GET /api/quran?surah=N&ayah=A	Single verse: surah N, ayah A
GET /api/quran/surahs	List 114 surahs metadata
GET /api/quran/surahs/N	All verses of surah N
GET /api/quran/surahs/N?ayah=A	Single verse: surah N, ayah A