Search Quran content

Search for verses, chapters, juz, pages, and other Quran content. This is the primary search API used by Quran.com.

Use Cases

1. Command Bar / Search-as-you-type (Quick Mode)

Used in Quran.com's command bar for instant navigation. Returns both navigational results (chapters, juz, pages) and verse matches.

GET /v1/search?mode=quick&query=fatiha&navigationalResultsNumber=5&versesResultsNumber=10

2. Search Results Page (Advanced Mode)

Used for the full search results page with pagination and detailed verse results.

GET /v1/search?mode=advanced&query=mercy&page=1&size=20&translation_ids=131,20

3. Search with Exact Matching

For precise search queries, use exact_matches_only in advanced mode.

GET /v1/search?mode=advanced&query=الرحمن&exact_matches_only=1

Response Structure

navigation: Quick links to chapters, juz, pages matching the query
verses: Individual verse matches with optional highlighting
pagination: Standard pagination info for result sets

Query Parameters

mode string required

Possible values: [advanced, quick]

Search mode - quick for navigation/autocomplete, advanced for detailed results

Example: quick

query string required

Search query string

Example: mercy

filter_translations string

Comma-separated translation IDs to filter by

Example: 131,20

exact_matches_only string

Possible values: [0, 1]

Default value: 0

Return only exact matches (advanced mode only)

get_text string

Possible values: [0, 1]

Default value: 0

Include full verse text in results

highlight string

Possible values: [0, 1]

Default value: 1

Highlight matching text in results

navigationalResultsNumber number

Possible values: >= 1 and <= 50

Default value: 5

Number of navigational results to return (quick mode only)

versesResultsNumber number

Possible values: >= 1 and <= 50

Default value: 20

Number of verse results to return (quick mode only)

indexes string

Comma-separated list of indexes to search (quick mode only)

Example: quran,translations

translation_ids string

Comma-separated translation IDs

Example: 131,20,85

Responses

Search results returned successfully

application/json

Schema

Example (from schema)

Schema

pagination object

current_page number required

Current page number

next_page number nullable

Next page number, null if on last page

per_page number required

Results per page

total_pages number required

Total number of pages

total_records number required

Total number of matching records

result object

navigation object[] required

Quick navigation results (chapters, juz, pages, etc.)

Array [

result_type string required

Possible values: [surah, juz, hizb, ayah, rub_el_hizb, search_page, page, range, quran_range]

Type of result - determines how to navigate/display

key object required

Key for navigation (chapter number, verse key like "1:1", juz number, etc.)

oneOf

number

string

number

Key for navigation (chapter number, verse key like "1:1", juz number, etc.)

name string required

Display name of the result (chapter name, verse text preview, etc.)

isArabic boolean

True if the name contains Arabic text

isTransliteration boolean

True if the result is from transliteration matching

]

verses object[] required

Verse results matching the search query

Array [

result_type string required

Possible values: [surah, juz, hizb, ayah, rub_el_hizb, search_page, page, range, quran_range]

Type of result - determines how to navigate/display

key object required

Key for navigation (chapter number, verse key like "1:1", juz number, etc.)

oneOf

number

string

number

Key for navigation (chapter number, verse key like "1:1", juz number, etc.)

name string required

Display name of the result (chapter name, verse text preview, etc.)

isArabic boolean

True if the name contains Arabic text

isTransliteration boolean

True if the result is from transliteration matching

]

{
  "pagination": {
    "current_page": 1,
    "next_page": 2,
    "per_page": 20,
    "total_pages": 5,
    "total_records": 100
  },
  "result": {
    "navigation": [
      {
        "result_type": "surah",
        "key": 1,
        "name": "Al-Fatihah",
        "isArabic": false
      },
      {
        "result_type": "surah",
        "key": 36,
        "name": "Ya-Sin",
        "isArabic": false
      }
    ],
    "verses": [
      {
        "result_type": "ayah",
        "key": "1:1",
        "name": "بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ",
        "isArabic": true
      },
      {
        "result_type": "ayah",
        "key": "2:163",
        "name": "وَإِلَٰهُكُمْ إِلَٰهٌ وَاحِدٌ ۖ لَّا إِلَٰهَ إِلَّا هُوَ الرَّحْمَٰنُ الرَّحِيمُ",
        "isArabic": true
      }
    ]
  }
}