Nexus Programming · open data

Khassida API

The Khassida of Cheikh Ahmadou Bamba as plain JSON: the Arabic text, a Latin transcription, and French, English and Italian translations. No API key, no server, no rate limit.

Base URL https://khassida.nexusprogramming.dev/v1

Quick start

curl -s https://khassida.nexusprogramming.dev/v1/khassida/9/fr.karamati.json
const BASE = "https://khassida.nexusprogramming.dev/v1";
const { data } = await fetch(`${BASE}/khassida/9/fr.karamati.json`).then((r) => r.json());
data.bayts.forEach((b) => console.log(b.number, b.text));

Endpoints

PathReturns
/v1/meta.jsonVersion, counts, per-edition coverage, licence
/v1/editions.jsonThe available editions and their properties
/v1/khassidas.jsonEvery khassida with metadata, without text
/v1/khassida/{number}.jsonOne khassida, every edition
/v1/khassida/{number}/{edition}.jsonOne khassida, a single edition
/v1/edition/{edition}.jsonThe whole corpus in one edition

Every response carries the same envelope, so a client only ever unwraps data:

{ "code": 200, "status": "OK", "data": { … } }

A missing khassida or edition is a plain HTTP 404 from the web server, not an envelope with an error code. The full description is in openapi.yaml.

Editions

IdentifierLanguageUnitCoverage
Loading…

Every khassida is translated into French, English and Italian by the three bayt-level *.karamati editions — 193 of 193. The two verse-level editions are a partial extra that aligns translation to the hemistich rather than the full line. Spanish is not yet available.

Verses and bayts

Arabic poetry is written in bayts — full lines made of two hemistichs — and this dataset keeps both units. verses holds one entry per hemistich, which is the unit the Arabic text and the transcription are aligned to and what you want for following a recitation. bayts holds one entry per full line, with verseFrom and verseTo pointing at the hemistichs it spans; a translation that has to read as a sentence belongs here, which is why the *.karamati editions are bayt-level.

Each edition declares its unit, so a single-edition response returns verses for a verse-level edition and bayts for a bayt-level one, and says which in its unit field.

Pinning and caching

This host always serves the latest build of the default branch. For a build that never moves under you, fetch a release tag through the Statically CDN:

https://cdn.statically.io/gl/nexus-programming/khassida-api/v1.0.0/v1/khassidas.json

The payloads are immutable in practice, so cache them aggressively and refresh when sourceChecksum in /v1/meta.json changes.

En français

Une API ouverte et gratuite pour les Khassida de Cheikh Ahmadou Bamba : texte arabe, transcription latine et traductions française, anglaise et italienne, servies en JSON. Aucune clé, aucun serveur : chaque réponse est un fichier JSON généré depuis le dépôt. Les 193 khassida sont traduites au niveau du bayt (fr.karamati). Les poèmes appartiennent au domaine public ; les crédits sont dans le dépôt.