SDKs overview

Quran Cloud provides application programming interfaces (APIs) for programmatic access to Quranic text, translations, and audio content. To facilitate developer integration, various Software Development Kits (SDKs) and libraries are available. These tools encapsulate the underlying HTTP requests and responses, offering a more idiomatic way to interact with the API endpoints in specific programming languages. SDKs typically handle authentication, request formatting, and response parsing, streamlining the development process for applications that require Quranic data.

The primary benefit of using an SDK is the reduction of boilerplate code, allowing developers to focus on application logic rather than low-level API communication details. For instance, an SDK might provide a function like getVerse(sura, aya) that internally constructs the correct URL, adds the API key, sends the request, and returns a structured object containing the verse data. This approach aligns with common API integration patterns, where developers prefer to work with object-oriented or functional interfaces rather than raw HTTP clients. The Quran Cloud documentation provides detailed guides and examples for using these SDKs.

Official SDKs by language

Quran Cloud offers official SDKs and direct API examples in several popular programming languages. These resources are maintained by Quran Cloud to ensure compatibility and provide the most up-to-date methods for accessing their services. The official documentation typically includes code snippets and usage instructions for each supported language, demonstrating how to fetch data such as Quranic verses, surah information, and audio files.

While dedicated SDKs might not be available for every language as a separate installable package, Quran Cloud provides extensive examples that function as de facto SDKs, showing developers how to implement API calls using standard HTTP client libraries in their preferred language. This approach ensures that developers can integrate with the API even if a specific, pre-packaged SDK is not offered. Developers can review the official Quran Cloud API documentation for the most current list of supported languages and code examples.

Official Integration Examples

The following table summarizes the primary languages for which Quran Cloud provides direct integration examples and, in some cases, dedicated libraries. These examples serve as a foundation for building applications that consume Quran Cloud's data.

Language Package/Method Installation/Usage Maturity
JavaScript fetch API or axios client npm install axios or native browser fetch Stable (via direct API calls)
PHP cURL or Guzzle HTTP client composer require guzzlehttp/guzzle or native PHP cURL Stable (via direct API calls)
Python requests library pip install requests Stable (via direct API calls)
Ruby Net::HTTP or HTTParty gem gem install httparty or native Ruby Net::HTTP Stable (via direct API calls)
Go net/http package Standard Go library usage Stable (via direct API calls)
cURL Command-line utility Pre-installed on most Unix-like systems Stable (direct HTTP client)

Installation

Installation for Quran Cloud's integration methods typically involves installing standard HTTP client libraries for your chosen programming language. Since Quran Cloud primarily offers API examples rather than standalone SDK packages for every language, the installation process aligns with setting up a typical environment for making web requests.

For JavaScript (Node.js/Browser)

If you're working in a Node.js environment or a modern browser, you can use the native fetch API. For more robust features or older browser compatibility, a library like Axios is commonly used. To install Axios:

npm install axios
# or
yarn add axios

For PHP

PHP developers commonly use Guzzle, a PHP HTTP client, or the native cURL extension. To install Guzzle via Composer:

composer require guzzlehttp/guzzle

For Python

The requests library is the de facto standard for making HTTP requests in Python. Install it using pip:

pip install requests

For Ruby

Ruby provides the built-in Net::HTTP module. For a more convenient API, the HTTParty gem is a popular choice. Install it:

gem install httparty

For Go

Go's standard library includes the net/http package, which is used for making HTTP requests without external dependencies.

Quickstart example

This quickstart example demonstrates how to fetch a specific verse from the Quran Cloud API using Python's requests library. This approach is representative of how you would interact with the API in other languages, adapting the syntax for HTTP requests and JSON parsing.

Before running, ensure you have an API key from your Quran Cloud developer dashboard and have installed the requests library (pip install requests).

import requests
import json

# Replace with your actual API Key
API_KEY = "YOUR_QURAN_CLOUD_API_KEY"
BASE_URL = "https://api.qurancloud.com/v1"

# Example: Fetch Surah Al-Fatiha (1), Ayah 1 with English translation
surah_number = 1
ayah_number = 1
translation_id = 2 # Example: Sahih International (check docs for IDs)

endpoint = f"/quran/verse/{surah_number}/{ayah_number}/translation/{translation_id}"
url = BASE_URL + endpoint

headers = {
    "Authorization": f"Bearer {API_KEY}"
}

print(f"Fetching: {url}")

try:
    response = requests.get(url, headers=headers)
    response.raise_for_status() # Raise an HTTPError for bad responses (4xx or 5xx)
    data = response.json()

    if data and data.get("data"): # Check if 'data' key exists and is not empty
        verse_data = data["data"]
        print(f"\nSurah: {verse_data['surah_name']} ({verse_data['surah_number']})")
        print(f"Ayah: {verse_data['ayah_number']}")
        print(f"Text (Arabic): {verse_data['text_madani']}")
        print(f"Translation: {verse_data['translation']['text']}")
    else:
        print("No data found for the specified verse.")

except requests.exceptions.HTTPError as http_err:
    print(f"HTTP error occurred: {http_err} - {response.text}")
except requests.exceptions.ConnectionError as conn_err:
    print(f"Connection error occurred: {conn_err}")
except requests.exceptions.Timeout as timeout_err:
    print(f"Timeout error occurred: {timeout_err}")
except requests.exceptions.RequestException as req_err:
    print(f"An unexpected error occurred: {req_err}")
except json.JSONDecodeError:
    print(f"Failed to decode JSON from response: {response.text}")

This Python snippet demonstrates a fundamental interaction: constructing the API endpoint, adding the necessary authorization header with your API key, sending a GET request, and then parsing the JSON response. Error handling is included to manage common issues like network problems or API-specific errors. For additional API endpoints and parameters, refer to the Quran Cloud API reference.

Community libraries

While Quran Cloud provides official examples and direct API access, the developer community often creates and maintains independent libraries and wrappers. These community-contributed projects can offer alternative interfaces, additional features, or support for languages not directly covered by official examples. Community libraries are typically found on platforms like GitHub, npm, or PyPI.

When considering a community library, it is advisable to evaluate its maintenance status, documentation, and the activity of its contributors. Factors such as the number of stars, recent commits, and open issues can indicate the health and reliability of a project. While these libraries can accelerate development, they may not always be officially supported or updated in sync with API changes. Developers should consult the Quran Cloud documentation for any specific guidelines on third-party integrations.

Examples of common types of community contributions include:

  • Language-specific wrappers: Libraries that provide an object-oriented interface for the API in languages like Java, C#, or Swift, which might not have official SDKs.
  • Framework integrations: Modules or plugins designed to work seamlessly within popular web frameworks (e.g., a Laravel package for PHP, or a Django app for Python).
  • Utility functions: Small libraries that handle specific tasks, such as caching Quranic data, formatting verses for display, or integrating with other Islamic APIs (e.g., prayer times).
  • CLI tools: Command-line interfaces built on top of the API for quick data retrieval or scripting purposes.

Searching package managers (like npm for JavaScript, PyPI for Python, or RubyGems for Ruby) or code hosting platforms (like GitHub) using terms such as "Quran Cloud API client" or "Quran Cloud SDK" can help identify relevant community projects. For example, a developer looking for Python libraries might explore PyPI for Quran API clients, which could include projects compatible with Quran Cloud's API structure, even if not explicitly branded.

It is important to note that the quality and security of community-developed libraries can vary. Developers should perform due diligence, including reviewing the source code and understanding the project's dependencies, before incorporating them into production applications, as recommended by general best practices for API client library development.