shamela.ws APIshamela.ws ↗
Access the Shamela Islamic digital library via API. Browse categories, search books by title or full text, read page content, and explore authors.
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'
Get all book categories from the Shamela library homepage. Returns an array of category objects with their IDs, names, book counts, and URLs.
No input parameters required.
{
"type": "object",
"fields": {
"data": "array of category objects, each with id, name, book_count, and url",
"status": "string indicating success"
},
"sample": {
"data": [
{
"id": "1",
"url": "https://shamela.ws/category/1",
"name": "العقيدة",
"book_count": 807
},
{
"id": "12",
"url": "https://shamela.ws/category/12",
"name": "القواعد الفقهية",
"book_count": 55
}
],
"status": "success"
}
}About the shamela.ws API
The Shamela.ws API exposes 9 endpoints covering the full depth of one of the largest Arabic Islamic book collections online. You can retrieve category listings, fetch paginated book lists, pull structured metadata and tables of contents per book, read individual page text, and run full-text searches across the entire corpus. The get_book_page endpoint, for example, returns the actual Arabic text of any numbered page alongside the book title and author.
Browsing and Discovery
The get_categories endpoint returns all top-level categories from the Shamela library, each with an id, name, book_count, and url. Feed those category IDs into get_books_by_category to paginate through books within a category — the response includes a has_next boolean so you can walk pages until the collection is exhausted. For a broader sweep, list_all_books iterates across multiple categories up to a configurable limit, returning each book's id, title, author, category, url, and metadata in one array.
Book Details and Reading
Call get_book_details with a book_id to receive full publication metadata — author, publisher, edition details — alongside a structured toc array linking to individual sections. Once you have a section or page reference, get_book_page returns the Arabic text content for that specific page_number within the book, along with book_title and author. The get_recently_added endpoint surfaces the latest additions to the library without any parameters, returning id, title, author, and url for each entry.
Search
Two distinct search modes are available. search_books_by_name queries by title using a keyword (query in Arabic) and returns matching books with id, title, and url — useful for autocomplete-style lookups. search_books_by_content performs full-text search across the book corpus, returning paginated results where each match includes a snippet of the surrounding text, title, author, and url. Both endpoints expect Arabic-language queries.
Author Data
get_author_books accepts an author_id and returns the author's name alongside an array of all their works, each with id, title, and url. Author IDs can be obtained from book metadata returned by other endpoints — for instance, al-Bukhari's books are reachable via author ID 215.
- Build an Arabic Quran and Hadith research tool using
search_books_by_contentto surface relevant passages with surrounding context snippets. - Construct a browsable category index of Islamic texts by chaining
get_categorieswithget_books_by_categorypagination. - Generate author bibliographies by feeding author IDs from book metadata into
get_author_books. - Create a 'new arrivals' feed for an Islamic library app using
get_recently_added. - Build a page-by-page reader for classical Arabic texts using
get_book_pagewith sequentialpage_numberincrements. - Populate a book metadata database with titles, publication details, and tables of contents via
get_book_details. - Implement Arabic book title autocomplete by querying
search_books_by_nameon user keystrokes.
| 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 | 250 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 a list of matching books?+
results array includes a snippet — a short excerpt of the book text containing the matched term — along with title, author, and url. Results are paginated and you can pass a page integer to walk through additional matches.Are there any language limitations for search queries?+
search_books_by_name and search_books_by_content expect Arabic-language query strings. Transliterated or non-Arabic queries are unlikely to return useful results, given the library's Arabic-language corpus.Does the API expose user annotations, reading lists, or personal library features from Shamela accounts?+
Can I retrieve an entire book's text in one request?+
get_book_page, which requires both a book_id and a page_number. There is no single-call endpoint that returns a full book's text. You can fork this API on Parse and revise it to add a bulk-page retrieval endpoint if your use case requires it.