DEV Community

SunnahSource
SunnahSource

Posted on

Show a Quran translation with word-by-word breakdown in a web page using JSON

If you are building a Quran learning page, you usually need two things: the verse with its translation, and a word-by-word breakdown so learners can see what each Arabic word means. In this tutorial we render both in a plain HTML page using fetch and vanilla JavaScript. No framework, no build step.

We will use the JSON shown publicly on the Quran Translation API page and the Word by Word Quran API page of QuraniAPI.

1. Get an API key

A free API key is requested from the QuraniAPI home page via the Get API Key button. Endpoint details and how to send the key are in the docs, so I will not guess at them here. Keep the key out of public repos.

Note: on the API pages, the translation API is marked FREE, while the word-by-word API is marked PREMIUM. Check the site for current access details before relying on it in production.

2. The translation endpoint

The Quran Translation API page lists this endpoint (Surah Al-Fatiha, 9 languages):

https://quranicapi.online/api/serve.php?slug=quran-translations&lang=all
Enter fullscreen mode Exit fullscreen mode

A shortened sample of the JSON shown on that page:

{
  "title": "Quran Translations",
  "is_free": true,
  "surah": { "number": 1, "name_arabic": "الفاتحة", "name_english": "Al-Fatiha", "ayah_count": 7 },
  "ayahs": [
    {
      "number": 1,
      "arabic": "بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ",
      "transliteration": "Bismillahir Rahmanir Raheem",
      "translations": {
        "en": "In the name of Allah, the Entirely Merciful, the Especially Merciful.",
        "ur": "شروع اللہ کے نام سے جو بڑا مہربان نہایت رحم والا ہے۔"
      }
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Each ayah has Arabic text, a transliteration, and a translations object keyed by language code.

3. Render the translation

<div id="ayahs" dir="auto"></div>
<script>
const URL_T = "https://quranicapi.online/api/serve.php?slug=quran-translations&lang=all";

async function loadTranslations(lang = "en") {
  const res = await fetch(URL_T /*, add your API key as described in the docs */);
  if (!res.ok) throw new Error("HTTP " + res.status);
  const data = await res.json();

  document.getElementById("ayahs").innerHTML = data.ayahs.map(a => `
    <section>
      <p lang="ar" dir="rtl" style="font-size:1.6rem">${a.arabic}</p>
      <small>${a.transliteration}</small>
      <p>${a.translations[lang] ?? ""}</p>
    </section>`).join("");
}
loadTranslations("en").catch(console.error);
</script>
Enter fullscreen mode Exit fullscreen mode

Pass another code such as "ur" or "fr" to switch language. Since the response contains all languages, a language dropdown can re-render without another request.

4. The word-by-word endpoint

https://quranicapi.online/api/serve.php?slug=word-by-word-quran&lang=all
Enter fullscreen mode Exit fullscreen mode

Sample from the public page (Surah 1, Ayah 1):

{
  "title": "Word by Word Quran",
  "surah": 1,
  "ayah": 1,
  "arabic_full": "بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ",
  "words": [
    {
      "position": 1,
      "arabic": "بِسْمِ",
      "transliteration": "Bismi",
      "root": "س م و",
      "grammar": "Preposition + Noun",
      "translations": { "en": "In the name of", "ur": "نام سے" }
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Every word carries its position, transliteration, root letters, grammar label and per-language meanings.

5. Render the breakdown as word cards

const URL_W = "https://quranicapi.online/api/serve.php?slug=word-by-word-quran&lang=all";

async function loadWords(lang = "en") {
  const res = await fetch(URL_W);
  const data = await res.json();

  const cards = data.words.map(w => `
    <div class="word">
      <div lang="ar" dir="rtl">${w.arabic}</div>
      <div>${w.transliteration}</div>
      <strong>${w.translations[lang] ?? ""}</strong>
      <small>root: ${w.root} · ${w.grammar}</small>
    </div>`).join("");

  document.getElementById("ayahs").insertAdjacentHTML(
    "beforeend", `<div class="words" style="display:flex;gap:12px;flex-wrap:wrap">${cards}</div>`);
}
loadWords("en").catch(console.error);
Enter fullscreen mode Exit fullscreen mode

Add a little CSS (.word { border:1px solid #ddd; padding:8px; border-radius:8px; text-align:center }) and you have a learning-friendly layout.

Tips

  • Always render Arabic with dir="rtl" and a font that supports tashkeel (diacritics).
  • Use ?? fallbacks, since not every language is present on every word.
  • Cache responses in localStorage or a service worker to save requests.
  • Escape or sanitize any text if you later mix in user input.

Wrap-up

That is the whole pattern: fetch JSON, map to HTML, switch language by key. For more endpoints, read the docs. The wider project, including the Islamic API source, is on GitHub. Feedback and pull requests are welcome.

Top comments (0)