Shamela APIshamela.ws ↗
Access the Shamela Islamic digital library via API. Browse categories, search books by title or full-text content, read pages, and explore authors in Arabic.
What is the Shamela API?
The Shamela.ws API exposes 9 endpoints covering the full Shamela Islamic digital library — one of the largest collections of Arabic Islamic texts online. You can retrieve the complete category tree, page through books in any category, run full-text content searches, and read individual book pages with their Arabic text. The get_book_details endpoint returns structured table-of-contents entries alongside publication metadata, making it straightforward to navigate a book's internal structure programmatically.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/fea100ca-ae6c-4130-8469-4b1f65d5931e/get_categories' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace shamela-ws-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Shamela Islamic Library SDK — browse, search, and read Islamic texts."""
from parse_apis.shamela_islamic_library_api import Shamela, BookNotFound
client = Shamela()
# Browse categories — each has a name and book count.
for cat in client.categories.list(limit=5):
print(cat.name, cat.book_count)
# Drill into one category's books via constructible Category.
aqeedah = client.category(id="1")
book = aqeedah.books.list(limit=1).first()
if book:
print(book.title, book.url)
# Get full book details including table of contents.
detail = book.details()
print(detail.title, detail.author)
for entry in detail.toc[:3]:
print(entry.title, entry.href)
# Read the first page of the book.
page = detail.read_page(page_number="1")
print(page.book_title, page.content[:100])
# Search books by title — returns BookSummary items.
for result in client.booksummaries.search(query="\u0641\u0642\u0647", limit=3):
print(result.id, result.title)
# Full-text content search across all books.
for hit in client.searchresults.search(query="\u0627\u0644\u062d\u062f\u064a\u062b", limit=3):
print(hit.title, hit.snippet[:60])
# Fetch an author by ID — typed error handling for missing resources.
try:
author = client.authors.get(id="215")
print(author.name, len(author.books))
except BookNotFound as exc:
print(f"Author not found: {exc}")
print("exercised: categories.list / category.books.list / details / read_page / booksummaries.search / searchresults.search / authors.get")
Retrieve all book categories from the Shamela library. Returns the full category tree with IDs, Arabic names, book counts, and direct URLs. Categories are stable identifiers used to browse books via get_books_by_category.
No input parameters required.
{
"type": "object",
"fields": {
"items": "array of category objects with id, name, book_count, url"
},
"sample": {
"data": {
"items": [
{
"id": "1",
"url": "https://shamela.ws/category/1",
"name": "العقيدة",
"book_count": 807
},
{
"id": "2",
"url": "https://shamela.ws/category/2",
"name": "الفرق والردود",
"book_count": 151
}
]
},
"status": "success"
}
}About the Shamela API
Browsing and Discovery
The get_categories endpoint returns the full category tree with integer IDs, Arabic names, book counts per category, and direct URLs — no parameters required. These category IDs feed directly into get_books_by_category, which accepts a category_id and an optional page integer, returning a books array with per-book id, title, author, category, and url fields, plus a has_next boolean for iterating through paginated results. For bulk discovery, list_all_books accepts an optional limit parameter and collects books sequentially across categories, returning the same book-object shape.
Book Details and Reading
Given a book_id from any listing or search result, get_book_details returns the full toc array (table-of-contents entries with title and href), a metadata object containing publisher, edition, and page_count, plus author and title in Arabic. To read content, get_book_page accepts a book_id and page_number and returns the full Arabic content string for that page along with book_title and author. Page numbers correspond to the book's internal numbering as listed in the table of contents.
Search
Two distinct search modes are available. search_books_by_name performs title-based lookup using Arabic query terms and returns a non-paginated items array of matching books with id, title, and url. search_books_by_content runs full-text search across all book content, returning paginated results with title, author, url, and a snippet excerpt containing the matched term — useful for locating specific hadith phrases, fiqh rulings, or doctrinal passages.
Authors and Recent Additions
get_author_books takes an author_id (e.g. "215" for al-Bukhari) and returns the author's Arabic name plus their full books list. Author IDs appear in get_book_details responses. get_recently_added requires no parameters and returns the latest additions from the library homepage, giving you an items array with id, title, author (when available), and url.
The Shamela API is a managed, monitored endpoint for shamela.ws — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when shamela.ws changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official shamela.ws API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Index the Shamela library by category to build a structured offline reference of Islamic texts
- Run full-text
search_books_by_contentqueries to locate specific hadith or fiqh phrases across thousands of books - Extract structured table-of-contents entries from
get_book_detailsto build a navigable book reader - Retrieve all books by a specific author using
get_author_booksto compile a scholar's bibliography - Monitor
get_recently_addedto track new additions to the library for an update feed - Use
get_book_pageto stream Arabic book content page-by-page for text analysis or NLP training datasets - Build a category-aware book search tool by combining
get_categoriesandsearch_books_by_nameresults
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Shamela.ws have an official developer API?+
What does `search_books_by_content` return beyond matching book titles?+
results array where each entry includes title, author, url, and a snippet — a short excerpt of the book text surrounding the matched query term. Pagination is supported via the page parameter.Does `get_book_page` return the full text of the entire book at once?+
content for a single page identified by book_id and page_number. To retrieve an entire book, you need to iterate through page numbers using the range visible in the toc entries from get_book_details.Are user annotations, bookmarks, or reading history available through this API?+
Is there a way to filter books by publication date or scholarly tradition within a category?+
get_books_by_category response includes a metadata object per book (with fields like publisher and edition) but does not expose a filterable publication date field. The category_id is the only supported filter parameter. You can fork it on Parse and revise to add date-range or tradition-based filtering if that metadata becomes available in a response field.