DEV Community

SunnahSource
SunnahSource

Posted on

Build a Quran Topics Explorer in Python (stdlib only) with a Free JSON API

Many Quran apps need a "topics" screen: pick a theme like Patience or Prayer and see the verses about it. In this post we build that as a small Python command-line tool using only the standard library (urllib + json).

The data comes from the free sample of the Quran Topics API on QuraniAPI:

https://quranicapi.online/api/serve.php?slug=quran-topics
Enter fullscreen mode Exit fullscreen mode

What the JSON looks like

Each item has a slug, an icon and a translations object keyed by language code (en, ur, fr, de, tr, ms, ru, zh-CN, ja). Each language has a title, a short description and a list of verse references in surah:ayah form:

{
  "id": 1,
  "slug": "patience",
  "icon": "⏳",
  "translations": {
    "en": {
      "title": "Patience (Sabr)",
      "description": "Allah loves the patient. Patience is mentioned over 90 times in the Quran.",
      "verses": ["2:153", "2:155", "3:200", "39:10"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

The public sample has four topics (Patience, Prayer, Mercy of Allah, Paradise). Note that the verse list can differ per language, so always read verses from the language block you display.

The script

#!/usr/bin/env python3
"""quran_topics.py - list Quran topics with verse references from a JSON API (stdlib only)."""
import json
import sys
import urllib.request

API = "https://quranicapi.online/api/serve.php?slug=quran-topics"


def fetch_topics(url=API):
    req = urllib.request.Request(url, headers={"User-Agent": "quran-topics-demo/1.0"})
    with urllib.request.urlopen(req, timeout=15) as resp:
        return json.load(resp)


def topic_in(item, lang):
    """Return the topic block for a language, falling back to English."""
    tr = item.get("translations", {})
    return tr.get(lang) or tr.get("en") or {}


def verse_link(ref):
    surah, ayah = ref.split(":")
    return f"https://quran.com/{surah}/{ayah}"


def main():
    lang = sys.argv[1] if len(sys.argv) > 1 else "en"
    data = fetch_topics()
    print(data["title"], "-", data["description"])
    for item in data["items"]:
        t = topic_in(item, lang)
        print()
        print(item.get("icon", ""), t.get("title", item["slug"]))
        print("  ", t.get("description", ""))
        for ref in t.get("verses", []):
            print("   -", ref, verse_link(ref))


if __name__ == "__main__":
    main()
Enter fullscreen mode Exit fullscreen mode

Two small details:

  • topic_in() falls back to English if a language is missing, so the UI never shows an empty card.
  • verse_link() turns 2:153 into a link you can open in any Quran reader. Swap it for your own reader screen in an app.

Run it

python3 quran_topics.py en   # English
python3 quran_topics.py ur   # Urdu
Enter fullscreen mode Exit fullscreen mode

Output (English):

Topics in Quran - Major themes and topics found throughout the Quran with references

⏳ Patience (Sabr)
   Allah loves the patient. Patience is mentioned over 90 times in the Quran.
   - 2:153 https://quran.com/2/153
   - 2:155 https://quran.com/2/155
   - 3:200 https://quran.com/3/200
   - 39:10 https://quran.com/39/10

🕌 Prayer (Salah)
   Establish prayer and give zakah. Prayer is the pillar of Islam.
   - 2:43 https://quran.com/2/43
Enter fullscreen mode Exit fullscreen mode

Where to go next

More examples are in our GitHub repo. Questions or ideas? Leave a comment.

Top comments (0)