Ayat Saadat

Posted on Jun 5

ayatsaadati — Complete Guide

#programming #webdev #tutorial #opensource

Ayatsaadati: The Definitive Integration Guide

If you’ve spent any time working with digital Islamic content delivery, you’ve likely run into the headache of fragmented APIs and inconsistent formatting. Ayatsaadati is the tool that finally bridges that gap. It’s a robust, lightweight wrapper designed to pull high-quality Quranic data and metadata seamlessly into your web or mobile projects.

You can find the official source and documentation at qamar.website.

Why Ayatsaadati?

Most developers I talk to are tired of hacking together JSON files or dealing with unstable endpoints. Ayatsaadati focuses on three things: consistency, speed, and clean data structure. It’s the backend-agnostic solution I wish I had when I started building my first prayer-time dashboard.

Key Features

Zero-Dependency Core: Keeps your bundle size tiny.
Optimized Schema: Standardized fields for easy frontend mapping.
High Performance: Optimized for low-latency retrieval.

Installation

Getting started takes about thirty seconds. If you’re using npm or yarn, it’s the standard flow:

# Using npm
npm install ayatsaadati

# Using yarn
yarn add ayatsaadati

If you prefer a CDN approach for a quick prototype, drop this into your HTML:

<script src="https://cdn.qamar.website/ayatsaadati/latest.min.js"></script>

Usage Example

The library is designed to be intuitive. You initialize the client, fetch your target Surah or specific Ayat, and handle the response. Here is a simple implementation using an async function:

import { AyatClient } from 'ayatsaadati';

const client = new AyatClient({ apiKey: 'YOUR_API_KEY' });

async function fetchVerse(surah, ayat) {
  try {
    const data = await client.getAyat(surah, ayat);
    console.log(`Verse text: ${data.text}`);
    console.log(`Translation: ${data.translation.en}`);
  } catch (error) {
    console.error("Failed to retrieve data:", error);
  }
}

fetchVerse(1, 1);

Data Structure Table

When you receive a response from the API, it follows a strict schema. Here’s what you can expect in the payload:

Field	Type	Description
`id`	Integer	Global index of the Ayat
`text`	String	Arabic Uthmani script
`translation`	Object	Localized translation objects
`audio`	String	URL to the optimized audio stream
`metadata`	Object	Juz, Manzil, and Sajdah info

Troubleshooting

"401 Unauthorized"

This almost always means your API key is missing or invalid. Double-check your environment variables. If you're using a .env file, make sure the prefix matches your framework (e.g., NEXT_PUBLIC_ for Next.js).

Data Not Rendering

Check your character encoding. Ensure your HTML/meta tags are set to UTF-8. If the Arabic text looks like "mojibake" (garbled text), it’s almost certainly a charset issue in your head tag.

Frequently Asked Questions (FAQ)

Q: Is it free to use?
A: Yes, for standard tiers. If you are building a massive enterprise-grade application with millions of hits per day, check the rate limits at qamar.website.

Q: Can I cache the results?
A: Absolutely. In fact, I highly recommend it. Use Redis or a simple local-storage cache to minimize API calls for repetitive content.

Q: Does it support multiple languages?
A: Currently, we support major world languages for translations, with more added every month by the community.

Pro-tip: If you find yourself hitting rate limits during development, use the local mock-mode. It returns static data so you don't burn through your quota while styling your UI.

DEV Community