Koran, hadisy, tłumaczenia i zatwierdzone audio

Zewnętrzne API jest celowo bardziej rygorystyczne niż strona publiczna: poza KitabGrid mogą trafić tylko treści zatwierdzone do publikacji oraz zatwierdzone pod względem źródła i ponownego użycia.

Base URLhttps://kitabgrid.com/api/v1

FormatJSON · UTF-8

UwierzytelnianieBearer / X-KitabGrid-Key

1. Proces dostępu

Podaj domenę/subdomenę, dane kontaktowe, cel użycia, wymagane zakresy danych i języki tłumaczeń.
Potwierdź wymagany adres e-mail.
KitabGrid ręcznie ocenia stronę, zakresy i skutki licencyjne.
Po zatwierdzeniu krótkotrwały jednorazowy link generuje klucz. Surowy klucz nie jest przechowywany ani wysyłany e-mailem.

2. Uwierzytelnianie i typy kluczy

kg_live_… — tajny klucz serwerowy. Używaj wyłącznie na backendzie. Zapytanie z tym kluczem jest odrzucane, gdy nagłówek Origin wskazuje użycie w przeglądarce.

kg_pub_… — klucz przeglądarkowy. Działa tylko z dokładnie zatwierdzonego originu HTTPS i nie jest traktowany jako prywatny sekret.

curl -H "Authorization: Bearer kg_live_REPLACE_ME" \ "https://kitabgrid.com/api/v1/quran/ayahs/1/1?lang=en&include=translations,audio"

fetch("https://kitabgrid.com/api/v1/quran/ayahs/1/1?lang=pl&include=translations", { headers: { "X-KitabGrid-Key": "kg_pub_REPLACE_ME" } }).then(r => r.json()).then(console.log);

Nie używaj kluczy API w query string. Klucze powinny znajdować się w nagłówku HTTP, aby zmniejszyć ryzyko wycieku przez adresy URL, referrery lub logi.

3. Endpointy API

Method	Endpoint	Zakres	Cel
GET	`/client`	authenticated	Bieżący klient, domena, zakresy i limity.
GET	`/languages`	authenticated	Języki przyznane klientowi i dostępne publicznie.
GET	`/quran/surahs`	quran.read	Katalog 114 sur tam, gdzie istnieją zatwierdzone dane.
GET	`/quran/surahs/{surah}`	quran.read	Metadane sury.
GET	`/quran/surahs/{surah}/ayahs`	quran.read	Stronicowane wersety; można dołączyć tłumaczenia/audio.
GET	`/quran/ayahs/{surah}/{ayah}`	quran.read	Pojedynczy werset z opcjonalnymi tłumaczeniami/audio.
GET	`/quran/reciters`	quran.audio.read	Zatwierdzeni recytatorzy z audio dopuszczonym do użycia.
GET	`/hadith/search?q=...`	hadith.read	Wyszukiwanie zatwierdzonych opublikowanych hadisów.
GET	`/hadith/collections`	hadith.read	Zatwierdzone zbiory opublikowane/częściowe.
GET	`/hadith/collections/{slug}`	hadith.read	Metadane zbioru.
GET	`/hadith/collections/{slug}/hadiths`	hadith.read	Stronicowane zatwierdzone hadisy.
GET	`/hadith/collections/{slug}/hadiths/{number}`	hadith.read	Pojedynczy hadis z opcjonalnymi zatwierdzonymi tłumaczeniami/audio.

4. Wspólne parametry

lang=en,pl: Lista przyznanych języków tłumaczeń oddzielona przecinkami, maksymalnie 5.
include=translations,audio: Dodaje tylko żądane bloki opcjonalne i tylko przy przyznanym odpowiednim zakresie.
reciter={id}: Wybiera konkretnego zatwierdzonego recytatora Koranu. Jeśli niedostępny, system nie podstawia innego po cichu.
page / per_page: Paginacja. per_page ma limit 50.

5. Zasady treści, źródeł i licencji

Tekst źródłowy Koranu/hadisów jest zwracany tylko przez zatwierdzone rekordy źródeł.
Tłumaczenia muszą być zatwierdzone; tłumaczenia hadisów dodatkowo respektują bramę opublikowanej wersji tłumaczenia, jeśli taki workflow istnieje.
Audio jest zwracane tylko wtedy, gdy samo źródło audio zostało zatwierdzone do ponownego użycia. Obsługa audio hadisów istnieje, ale nie zwróci plików, dopóki nie zostaną zapisane zatwierdzone nagrania.
Bloki źródłowe mogą zawierać tytuł, autora/tłumacza, wydawcę, edycję, URL źródła, nazwę/URL licencji i zakres ponownego użycia. Integratorzy muszą zachować wymaganą atrybucję i informacje licencyjne.

{ "data": { "surah": 1, "ayah": 1, "arabic": "…", "translations": [{ "language": "pl", "text": "…", "source": {"title": "…", "license_name": "…", "reuse_scope": "…"} }], "audio": {"available": true, "items": [{"reciter": "…", "url": "…", "source": {"title": "…"}}]} }, "meta": {"version": "v1", "request_id": "…"} }

6. Limity, CORS i błędy

Domyślny profil zatwierdzenia to 60 zapytań/minutę i 10 000/dzień, ale administrator może ustawić inny limit dla każdego klienta. Odpowiedź 429 oznacza przekroczenie limitu.

Klucze przeglądarkowe otrzymują dokładny Access-Control-Allow-Origin tylko dla zatwierdzonej domeny/subdomeny. Dla uwierzytelnionego dostępu przeglądarkowego nie jest używany wildcard CORS.

HTTP	Znaczenie
400	Nieprawidłowy parametr lub żądanie.
401	Brakujący/nieprawidłowy/unieważniony klucz.
403	Zakres, język, origin lub stan klienta nie pozwala na zapytanie.
404	Brak odpowiedniego zatwierdzonego rekordu publicznego.
429	Przekroczony limit minutowy lub dzienny.
503	Wymagana zależność API/danych jest niedostępna.