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
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"]
}
}
}
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()
Two small details:
-
topic_in()falls back to English if a language is missing, so the UI never shows an empty card. -
verse_link()turns2:153into 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
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
Where to go next
- Show the Arabic text and translation of each referenced verse with the Quran Translation API, or a word-by-word view with the Word-by-Word Quran API.
- Add commentary from the Tafseer API.
- Endpoints and language codes are in the docs; the full dataset and API keys are on the pricing page.
More examples are in our GitHub repo. Questions or ideas? Leave a comment.
Top comments (0)