quran-foundation-api

Official Python SDK for Quran Foundation APIs.

pip install quran-foundation-api

from quran_foundation import QuranClient

client = QuranClient(client_id="YOUR_CLIENT_ID", access_token="ACCESS_TOKEN")
chapters = client.list_chapters()
print(chapters)

Content and search

from quran_foundation import QuranClient

client = QuranClient(client_id="YOUR_CLIENT_ID", access_token="ACCESS_TOKEN")

chapter = client.get_chapter(1)
verses = client.get_verses_by_range("1:1", "1:7", translations="131")
translations = client.list_translations()
results = client.search("mercy", mode="advanced", params={"size": 10})

Content resource sync

Mushafs and word-by-word translations can be included in content sync and fetched as resource snapshots:

changes = client.sync_resources(
    params={
        "bootstrap": True,
        "resources": "mushafs:1;word_by_word_translations:85",
    }
)
snapshot = client.get_word_by_word_translation_snapshot(85)
mushaf_snapshot = client.get_mushaf_snapshot(1)

Mushaf snapshots contain the layout metadata, pages, publicly distributable font assets, and words needed for offline use. The API also exposes approved, shareable word-translation resources; transliteration resources are excluded.

For endpoints that do not yet have a dedicated helper, use the service request helpers:

client.content_request("/verses/by_page/1", params={"translations": "131"})
client.search_request("/api/v1/search", params={"query": "mercy", "mode": "quick"})
client.user_request("/bookmarks", params={"page": 1})

User APIs

Use signed-in User API helpers with a user access token. Keep the token server-side.

profile = client.get_profile()
bookmarks = client.list_bookmarks()
client.create_bookmark({"verse_key": "2:255", "mushaf_id": 1})
client.update_preference({"key": "theme", "value": "dark"})

OAuth2 helpers

Use OAuth helpers on the server side. Never expose client_secret, access tokens, or refresh tokens to browser code.

from quran_foundation.oauth import build_authorization_url, create_pkce_pair, exchange_code

verifier, challenge = create_pkce_pair()
authorize_url = build_authorization_url(
    client_id="YOUR_CLIENT_ID",
    redirect_uri="https://your-app.com/callback",
    scope="openid offline_access user bookmark",
    state="random-state",
    code_challenge=challenge,
)

tokens = exchange_code(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    code="CODE_FROM_CALLBACK",
    code_verifier=verifier,
    redirect_uri="https://your-app.com/callback",
)

Development

python -m pip install -e ".[dev]"
ruff check .
pytest
python -m build
twine check dist/*

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

quran_foundation_api-0.1.2.tar.gz (9.9 kB view details)

Uploaded Aug 24, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

quran_foundation_api-0.1.2-py3-none-any.whl (8.6 kB view details)

Uploaded Aug 24, 2026 Python 3

File details

Details for the file quran_foundation_api-0.1.2.tar.gz.

File metadata

Download URL: quran_foundation_api-0.1.2.tar.gz
Upload date: Aug 24, 2026
Size: 9.9 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for quran_foundation_api-0.1.2.tar.gz
Algorithm	Hash digest
SHA256	`c5f34c1ec3628894938d6bdc416253d239ef3e7df30974d8764053f05ca53112`
MD5	`fb2c0a3427fa68c559cb0602121e4870`
BLAKE2b-256	`cb7310ddcfed659e226ad044dbe146d589ea379bdb9f54d965f82ade730cdad8`

See more details on using hashes here.

Provenance

The following attestation bundles were made for quran_foundation_api-0.1.2.tar.gz:

Publisher: publish.yml on quran/api-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: quran_foundation_api-0.1.2.tar.gz
- Subject digest: c5f34c1ec3628894938d6bdc416253d239ef3e7df30974d8764053f05ca53112
- Sigstore transparency entry: 2580789115
- Sigstore integration time: Aug 24, 2026
Source repository:
- Permalink: quran/api-python@0b287b4adace6d96b51ed8fc622da7c944accc7b
- Branch / Tag: refs/heads/main
- Owner: https://github.com/quran
- Access: private
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@0b287b4adace6d96b51ed8fc622da7c944accc7b
- Trigger Event: workflow_dispatch