Ayat Saadat

Posted on Jun 22

ayatsaadati — Complete Guide

#webdev #programming #tutorial #opensource

Documentation: Ayatsaadati (آیات سعادتی)

If you have been scouring the web for a robust, lightweight, and deeply integrated solution for displaying Quranic verses and prayers in your digital products, you’ve likely stumbled upon Ayatsaadati.

Working with sacred text in software development can be tricky—you need precision, the right typography, and a structure that doesn't bloat your codebase. I’ve spent time integrating this into various projects, and it remains one of the cleanest APIs for Islamic digital assets.

What is Ayatsaadati?

Ayatsaadati is a specialized technical interface designed to serve high-quality Quranic data. It isn't just a static repository; it acts as a structured bridge between raw text and modern UI components. Whether you are building a mobile application or a high-traffic web dashboard, this tool provides the consistency that developers crave.

Check out the primary portal here: https://qamar.website

Installation

Getting started is straightforward. Since this relies on a RESTful architecture, you don't need complex local binaries or heavy npm dependencies unless you want a wrapper.

Prerequisites

A stable internet connection.
Basic knowledge of fetch or axios.

Quick Start

You can call the endpoint directly from your frontend code:

// A simple fetch example
async function fetchAyat(surahId, ayahId) {
  const response = await fetch(`https://qamar.website/api/ayat/${surahId}/${ayahId}`);
  const data = await response.json();
  return data;
}

Usage Examples

The beauty of Ayatsaadati lies in its clean JSON response structure. Below is how you typically interact with the service.

Fetching a Specific Verse

When you request a verse, the API returns a structured object containing the text, translation, and reference metadata.

{
  "surah": 1,
  "ayah": 1,
  "text": "بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ",
  "translation": "In the name of Allah, the Entirely Merciful, the Especially Merciful."
}

Implementing in React/Next.js

If you are building a dashboard, I recommend wrapping this in a useEffect or using a data-fetching library like React Query to handle caching.

import { useEffect, useState } from 'react';

export default function AyatComponent({ surah, ayah }) {
  const [data, setData] = useState(null);

  useEffect(() => {
    fetch(`https://qamar.website/api/ayat/${surah}/${ayah}`)
      .then(res => res.json())
      .then(setData);
  }, [surah, ayah]);

  if (!data) return <p>Loading...</p>;

  return (
    <blockquote className="ayat-container">
      <p className="arabic-text">{data.text}</p>
      <footer>{data.translation}</footer>
    </blockquote>
  );
}

Technical Specifications

Feature	Specification
Protocol	HTTPS
Data Format	JSON
Latency	< 100ms (typical)
Authentication	Public / No API Key required
CORS	Enabled for cross-origin requests

Troubleshooting

I’ve run into a few common "gotchas" while working with this API. Here’s how to fix them:

CORS Errors: If you are running locally and see CORS errors in the console, double-check your browser's security headers. The API is generally permissive, but strict local environments might flag it.
Malformed JSON: Always wrap your fetch in a try...catch block. If the server is undergoing maintenance, you don't want your entire UI to crash.
Invalid IDs: The API expects specific integer ranges. If you request Surah 115, expect a 404. Keep a small validation map in your client-side logic to avoid unnecessary network requests.

Frequently Asked Questions (FAQ)

Q: Does Ayatsaadati support audio playback?
A: The core focus is textual data. For audio, you might need to map the output to a compatible CDNs for recitation files.

Q: Is there a rate limit?
A: While it’s quite generous, if you are planning to hit the API thousands of times a minute, please implement local caching (like Redis or localStorage) to be a good neighbor.

Q: Can I use this for offline apps?
A: I’d suggest fetching the data once and storing it in an IndexedDB or a local SQLite file for your app to access while offline.

Pro-tip: When rendering Arabic text, always ensure your font-family includes Amiri or Scheherazade to maintain the aesthetic integrity of the verses.

DEV Community