Code Examples

Practical Examples

Ready-to-use code examples in Python, JavaScript, and cURL. Copy, paste, and start building with the Mizan API.

Prerequisites

Make sure the Mizan API is running locally before trying these examples:

bash

# Start infrastructure and API
docker-compose up -d
alembic upgrade head
python scripts/ingest_tanzil.py
uvicorn mizan.api.main:app --reload --port 8000

Get a Verse and Analyze It

Fetch a verse by surah and verse number, then run full analysis.

python

import requests

BASE_URL = "http://localhost:8000"

# Get verse text
verse = requests.get(f"{BASE_URL}/api/v1/verses/1/1").json()
print(f"Text: {verse['text_uthmani']}")

# Full analysis (letter count, word count, Abjad)
analysis = requests.get(f"{BASE_URL}/api/v1/analysis/verse/1/1").json()
print(f"Letters: {analysis['letter_count']}")
print(f"Words:   {analysis['word_count']}")
print(f"Abjad:   {analysis['abjad_value']}")

Calculate Abjad Value

Calculate the Abjad numerical value of any Arabic text using Mashriqi or Maghribi system.

python

import requests

BASE_URL = "http://localhost:8000"

# Abjad value of "Allah" (expected: 66)
result = requests.get(
    f"{BASE_URL}/api/v1/analysis/abjad",
    params={"text": "الله", "system": "mashriqi"}
).json()
print(f"Abjad value of 'Allah': {result['abjad_value']}")

# Abjad value of Basmalah (expected: 786)
result = requests.get(
    f"{BASE_URL}/api/v1/analysis/abjad",
    params={"text": "بسم الله الرحمن الرحيم"}
).json()
print(f"Abjad value of Basmalah: {result['abjad_value']}")

Semantic Search

Search across Quran, Tafsir, and Hadith using natural language queries with AI embeddings.

python

import requests

BASE_URL = "http://localhost:8000"

# Semantic search for "mercy and compassion"
results = requests.post(
    f"{BASE_URL}/api/v1/search/semantic",
    json={
        "query": "mercy and compassion",
        "source_types": ["QURAN"],
        "min_similarity": 0.7,
        "limit": 5,
    }
).json()

for r in results["results"]:
    print(f"[{r['similarity']:.0%}] {r['text'][:80]}...")

# Find verses similar to Al-Fatiha verse 1
similar = requests.get(
    f"{BASE_URL}/api/v1/verses/1/1/similar",
    params={"limit": 5, "min_similarity": 0.7}
).json()

for v in similar["similar"]:
    print(f"[{v['similarity']:.0%}] Surah {v['surah_number']}:{v['verse_number']}")

Library Management

Create a library space, add text sources, and trigger indexing for semantic search.

python

import requests

BASE_URL = "http://localhost:8000"

# 1. Create a library space
space = requests.post(
    f"{BASE_URL}/api/v1/library/spaces",
    json={"name": "My Research", "description": "Research texts"}
).json()
space_id = space["id"]
print(f"Created space: {space['name']} ({space_id})")

# 2. Add a text source
source = requests.post(
    f"{BASE_URL}/api/v1/library/spaces/{space_id}/sources",
    json={
        "title": "Ibn Kathir - Al-Fatiha",
        "source_type": "TAFSIR",
        "content": "The tafsir text content goes here...",
        "language": "ar",
    }
).json()
source_id = source["id"]
print(f"Added source: {source['title']}")

# 3. Start indexing (generates embeddings)
requests.post(f"{BASE_URL}/api/v1/library/sources/{source_id}/index")
print("Indexing started!")

# 4. Check indexing status
status = requests.get(f"{BASE_URL}/api/v1/library/sources/{source_id}").json()
print(f"Status: {status['indexing_status']}")

Try in Playground API Reference

import requests BASE_URL = "http://localhost:8000" # Get verse text verse = requests.get(f"{BASE_URL}/api/v1/verses/1/1").json() print(f"Text: {verse['text_uthmani']}") # Full analysis (letter count, word count, Abjad) analysis = requests.get(f"{BASE_URL}/api/v1/analysis/verse/1/1").json() print(f"Letters: {analysis['letter_count']}") print(f"Words: {analysis['word_count']}") print(f"Abjad: {analysis['abjad_value']}")

import requests BASE_URL = "http://localhost:8000" # Abjad value of "Allah" (expected: 66) result = requests.get( f"{BASE_URL}/api/v1/analysis/abjad", params={"text": "الله", "system": "mashriqi"} ).json() print(f"Abjad value of 'Allah': {result['abjad_value']}") # Abjad value of Basmalah (expected: 786) result = requests.get( f"{BASE_URL}/api/v1/analysis/abjad", params={"text": "بسم الله الرحمن الرحيم"} ).json() print(f"Abjad value of Basmalah: {result['abjad_value']}")

import requests BASE_URL = "http://localhost:8000" # Semantic search for "mercy and compassion" results = requests.post( f"{BASE_URL}/api/v1/search/semantic", json={ "query": "mercy and compassion", "source_types": ["QURAN"], "min_similarity": 0.7, "limit": 5, } ).json() for r in results["results"]: print(f"[{r['similarity']:.0%}] {r['text'][:80]}...") # Find verses similar to Al-Fatiha verse 1 similar = requests.get( f"{BASE_URL}/api/v1/verses/1/1/similar", params={"limit": 5, "min_similarity": 0.7} ).json() for v in similar["similar"]: print(f"[{v['similarity']:.0%}] Surah {v['surah_number']}:{v['verse_number']}")

import requests BASE_URL = "http://localhost:8000" # 1. Create a library space space = requests.post( f"{BASE_URL}/api/v1/library/spaces", json={"name": "My Research", "description": "Research texts"} ).json() space_id = space["id"] print(f"Created space: {space['name']} ({space_id})") # 2. Add a text source source = requests.post( f"{BASE_URL}/api/v1/library/spaces/{space_id}/sources", json={ "title": "Ibn Kathir - Al-Fatiha", "source_type": "TAFSIR", "content": "The tafsir text content goes here...", "language": "ar", } ).json() source_id = source["id"] print(f"Added source: {source['title']}") # 3. Start indexing (generates embeddings) requests.post(f"{BASE_URL}/api/v1/library/sources/{source_id}/index") print("Indexing started!") # 4. Check indexing status status = requests.get(f"{BASE_URL}/api/v1/library/sources/{source_id}").json() print(f"Status: {status['indexing_status']}")