Quran Cloud Getting Started: API Keys & First Request (2026)

Getting started overview

Integrating with Quran Cloud involves a series of steps designed to provide access to its Quranic data API. The process begins with account creation, where users obtain the necessary API credentials. These credentials, typically an API key, are then used to authenticate requests to the Quran Cloud endpoints. Developers can access Quranic text, translations, and audio resources programmatically, supporting various applications from website content to academic research Quran Cloud API documentation. The API supports standard HTTP methods and JSON responses, making it compatible with most modern programming environments REST API data formats.

This guide focuses on the foundational steps:

1. Creating a Quran Cloud account.
2. Obtaining your unique API key.
3. Executing a first successful API request.
4. Identifying common next steps for further integration.

A quick reference table outlines these initial actions:

Create an account and get keys

To begin using the Quran Cloud API, you must first create an account on their platform. This registration process is standard and typically requires an email address and password. Upon successful registration, you will gain access to your personal dashboard.

Follow these steps to set up your account and retrieve your API key:

1. Navigate to the Quran Cloud Website: Open your web browser and go to the official Quran Cloud homepage.
2. Sign Up: Look for a "Sign Up" or "Get Started" button, usually located in the top right corner. Click this button to initiate the registration process.
3. Provide Registration Details: Enter your email address and choose a secure password. You may also be asked to provide basic profile information. Agree to the terms of service and privacy policy if prompted.
4. Verify Email (if required): Some registration processes include an email verification step. Check your inbox for a verification link from Quran Cloud and click it to confirm your account.
5. Access Your Dashboard: Once registered and logged in, you will be redirected to your Quran Cloud dashboard. This is your central hub for managing your account, subscriptions, and API keys.
6. Locate Your API Key: Within the dashboard, there should be a dedicated section for API keys or credentials. This section will display your unique API key, which is a string of alphanumeric characters. It is crucial to treat this key as sensitive information, similar to a password, as it authenticates your requests and links them to your account and usage limits.
7. Copy Your API Key: Copy the API key to a secure location. You will need to include this key in the header or parameters of every API request you make to Quran Cloud.

Quran Cloud offers a Developer Plan, which is a free tier providing up to 10,000 requests per month. This plan is suitable for testing and initial development Quran Cloud pricing details.

Your first request

After obtaining your API key, the next step is to make an authenticated request to a Quran Cloud API endpoint. This verifies your setup and allows you to retrieve data. For this example, we will retrieve information about the first Surah (Al-Fatiha).

The Quran Cloud API typically requires the API key to be passed as a query parameter or an HTTP header. For simplicity in a first request, a query parameter is often used. Refer to the Quran Cloud API documentation for specific parameter names and authentication methods.

Example: Fetching Surah Al-Fatiha (Surah 1)

This example demonstrates how to use cURL, a common command-line tool, to make an HTTP request. Replace YOUR_API_KEY with the actual API key you obtained from your dashboard.

Using cURL

A basic request to get Surah 1 might look like this:

curl -X GET "https://api.qurancloud.com/v1/surah/1?api_key=YOUR_API_KEY"

Explanation:

• curl -X GET: Specifies an HTTP GET request.
• "https://api.qurancloud.com/v1/surah/1?api_key=YOUR_API_KEY": This is the endpoint URL.
• https://api.qurancloud.com/v1/surah/1: Targets the API version 1 and requests data for Surah number 1.
• ?api_key=YOUR_API_KEY: Appends your unique API key as a query parameter for authentication.

Expected Response (abbreviated JSON):

A successful response will return JSON data containing information about Surah Al-Fatiha. The exact structure may vary slightly, but it will typically include details such as the Surah's name, number of verses, and potentially the text or translation data.

{
  "code": 200,
  "status": "OK",
  "data": {
    "number": 1,
    "name": "Al-Fatiha",
    "englishName": "The Opening",
    "englishNameTranslation": "The Opening",
    "numberOfAyahs": 7,
    "revelationType": "Meccan"
    // ... more data like verses, translations, etc.
  }
}

If you receive a response similar to the above, your API key is correctly configured, and you have successfully made your first request to the Quran Cloud API.

Common next steps

Once you've successfully made your first API call, you can explore the broader capabilities of the Quran Cloud API. Common next steps often involve integrating the API into a programming language or framework, handling more complex queries, and managing your API usage.

1. Explore API Endpoints: Review the comprehensive Quran Cloud API documentation to understand all available endpoints. These typically include fetching specific surahs, ayahs (verses), translations, recitations (audio), and search functionalities.
2. Choose a Programming Language/SDK: While cURL is useful for initial testing, you'll likely integrate the API into an application using a programming language. Quran Cloud supports several languages for examples like JavaScript, PHP, Python, Ruby, and Go. Utilize your chosen language's HTTP client libraries (e.g., Python's requests, Node.js's axios, Java's HttpClient) to make requests programmatically.
3. Handle Responses: Learn to parse the JSON responses from the API within your application. This involves extracting the desired data (e.g., Surah name, Ayah text, translation) and displaying or processing it.
4. Implement Error Handling: Develop robust error handling for your API calls. The API will return specific HTTP status codes (e.g., 400 for bad request, 401 for unauthorized, 404 for not found, 500 for server errors) and error messages in the JSON response payload. Proper error handling improves application stability and user experience HTTP status code definitions.
5. Manage API Key Security: Never expose your API key directly in client-side code or public repositories. For server-side applications, store the API key in environment variables or a secure configuration management system. For client-side applications requiring direct API access, consider using a proxy server to hide the key or implement user authentication workflows that issue temporary, scoped tokens if supported by the API.
6. Monitor Usage: Regularly check your API usage within the Quran Cloud dashboard to ensure you stay within your plan's limits. If your application scales, you may need to upgrade your subscription plan Quran Cloud pricing tiers.
7. Implement Caching: For frequently requested data that doesn't change often (like Surah metadata or static translations), implement client-side or server-side caching to reduce the number of API calls and improve performance.
8. Explore Audio API: If your application requires audio recitations of the Quran, investigate the dedicated Audio API endpoints, which often involve different parameters or streaming considerations.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some typical problems and their solutions:

• 401 Unauthorized / Invalid API Key:
  • Problem: The API returns a 401 status code or an "Invalid API Key" message.
  • Solution: Double-check that you have copied your API key correctly from your Quran Cloud dashboard. Ensure there are no leading or trailing spaces. Verify that the parameter name used for the API key (e.g., api_key) matches what is specified in the Quran Cloud API documentation.
• 404 Not Found:
  • Problem: The API returns a 404 status code.
  • Solution: This usually means the endpoint URL is incorrect or the resource you're requesting does not exist. Verify the endpoint path (e.g., /v1/surah/1) against the Quran Cloud API reference. Ensure there are no typos in the URL.
• 400 Bad Request:
  • Problem: The API returns a 400 status code.
  • Solution: This indicates that your request was improperly formatted or missing required parameters. Review the parameters you're sending (e.g., Surah number, language, translation ID) and compare them with the Quran Cloud API documentation requirements for the specific endpoint you are calling.
• Network Issues / Connection Refused:
  • Problem: Your client (e.g., curl, browser) reports a network error or connection refusal.
  • Solution: Check your internet connection. Ensure there are no firewalls or proxy settings on your network that might be blocking outbound HTTP/HTTPS requests to api.qurancloud.com. Try accessing the Quran Cloud website directly to confirm general network connectivity.
• JSON Parsing Errors:
  • Problem: Your application fails to parse the JSON response.
  • Solution: This can happen if the response is not valid JSON or if your parsing logic is incorrect. Examine the raw response body if possible. Use online JSON validators to check the response format. Ensure your programming language's JSON parsing library is used correctly.
• Rate Limit Exceeded (e.g., 429 Too Many Requests):
  • Problem: The API returns a 429 status code.
  • Solution: You have exceeded the request limits for your current plan (e.g., 10,000 requests/month for the Developer Plan). Wait for the rate limit to reset, or consider upgrading your plan if you require higher call volumes.