Skip to content

API Documentation ​

Digital Arabic Maqām Archive (DiArMaqAr) — programmatic access to historically documented maqāmāt, ajnās, and tuning systems spanning from al-Kindī (874 CE) to contemporary approaches.

Quick Start ​

Try this first:

bash
curl "https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents"

Base URL: https://diarmaqar.net/api

Documentation Resources ​

For Humans ​

For LLMs ​


API Endpoints ​

All API endpoints are organized by resource type. Each endpoint includes a link to detailed documentation with parameters, examples, and response formats.

Total: 27 endpoints across 7 resource categories.

Maqāmāt ​

Documented modal frameworks with historical source attribution.

Endpoints (8):

  • GET /maqamat - List all maqāmāt → Details
  • GET /maqamat/families - List maqām families → Details
  • GET /maqamat/{idName} - Get detailed maqām data → Details · Every maqām form in one request
  • GET /maqamat/{idName}/availability - Check maqām availability across tuning systems → Details
  • GET /maqamat/{idName}/transpositions - List transpositions for a maqām → Details
  • GET /maqamat/{idName}/compare - Compare maqām data across multiple tuning systems → Details
  • GET /maqamat/classification/12-pitch-class-sets - Classify maqāmāt by 12-pitch-class sets → Details · Transpositions that do not fit
  • GET /maqamat/classification/maqam-pitch-class-sets - Classify maqāmāt by maqam-based pitch class sets → Details

Ajnās ​

Documented tri/tetra/penta-chords with historical source attribution.

Endpoints (5):

  • GET /ajnas - List all ajnās → Details
  • GET /ajnas/{idName} - Get detailed jins data → Details
  • GET /ajnas/{idName}/availability - Check jins availability across tuning systems → Details
  • GET /ajnas/{idName}/transpositions - List transpositions for a jins → Details
  • GET /ajnas/{idName}/compare - Compare jins data across multiple tuning systems → Details

Tuning Systems ​

Historical tuning systems spanning from al-Kindī (874 CE) to contemporary approaches.

Endpoints (4):

  • GET /tuning-systems - List all tuning systems → Details
  • GET /tuning-systems/{id}/{startingNote}/pitch-classes - Get tuning system details (pitch classes) → Details
  • GET /tuning-systems/{id}/{startingNote}/maqamat - List maqāmāt available in a tuning system → Details
  • GET /tuning-systems/{id}/{startingNote}/ajnas - List ajnās available in a tuning system → Details

Pitch Classes ​

Note names and pitch class data across all tuning systems.

Endpoints (4):

  • GET /pitch-classes/note-names - List all note names → Details
  • GET /pitch-classes/note-names/{noteName} - Get pitch class details by note name → Details
  • GET /pitch-classes/note-names/{noteName}/availability - Check note name availability across tuning systems → Details
  • GET /pitch-classes/note-names/{noteName}/compare - Compare pitch class by note name across tuning systems → Details

Intervals ​

Calculate intervals between note names.

Endpoints (2):

  • GET /intervals - Calculate intervals by note names → Details
  • GET /intervals/compare - Compare intervals across tuning systems → Details

Sources ​

Bibliographic sources documenting the historical foundation of the archive's musical data.

Endpoints (5):

  • GET /sources - List all bibliographic sources → Details
  • GET /sources/{id} - Get a single bibliographic source → Details
  • GET /sources/{id}/tuning-systems - List tuning systems by source → Details
  • GET /sources/{id}/maqamat - List maqamat by source → Details
  • GET /sources/{id}/ajnas - List ajnas by source → Details

Modulations ​

Modulation routes between maqāmāt using al-Shawwā's 1946 modulation guidelines.

Endpoints (1):

  • GET /modulation-routes - Find modulation routes between maqāmāt → Details

Statistics ​

What the archive holds, and for every tuning system on every starting note: the ajnās and maqāmāt it can build, their transpositions (taṣwīr) and octave renderings, and the modulations from base forms, transpositions and octave renderings.

Endpoints (1):

  • GET /statistics - Get archive statistics → Details

Identifiers of transpositions ​

A transposed maqām or jins has one idName, and every endpoint returns the same one. It is the base idName, then _al_, then the tonic's note-name idName:

Display nameidName
maqām rāst al-qarār chahārgāhmaqam_rast_al_qarar_chahargah
jins segāh al-tīk ḥiṣārjins_segah_al_tik_hisar
maqām ḥijāz (al-Ṣabbāgh/ʿAbbās) al-saham/ramal tūtīmaqam_hijaz_alsabbagh_abbas_al_saham_ramal_tuti

The separator is always _al_. The "al" inside a base name is closed up, so it never looks like a separator: maqam_hijaz_alsabbagh_abbas and jins_buselik_alhilu are base names, not transpositions.

The base form is its bare idName (maqam_rast). A rendering an octave away from the base form, such as maqām rāst on qarār rāst, is not a taṣwīr (isTransposed: false, isBaseForm: false), but it still names its tonic: maqam_rast_al_qarar_rast.

So the idName in a maqām's availableTranspositions list is exactly the maqam.idName you get back when you request that transposition. The same idName appears in:

  • each entry of GET /maqamat/{idName}/transpositions and GET /ajnas/{idName}/transpositions;
  • each entry of the transpositions array that includeTranspositions=true adds to GET /tuning-systems/{id}/{startingNote}/maqamat and .../ajnas;
  • the 12-pitch-class-set and maqām-pitch-class-set classifications;
  • ajnās named inside maqām responses;
  • modulation routes.

A classification set is named after one of its members, so its setIdName is that member's idName plus _set. A set that holds a base form is named after one (maqam_hijaz_kar_kurd_set); a set that holds none is named after a transposition (maqam_rast_al_kawasht_set). The rule is given in the 12-pitch-class sets endpoint description.

Using a transposed idName in the path ​

A transposed idName can go straight into the path. It means the same as the base idName with the tonic given separately:

PathSame as
/maqamat/maqam_rast_al_qarar_chahargah/maqamat/maqam_rast?transposeTo=qarar_chahargah
/maqamat/maqam_rast_al_nawa/compare/maqamat/maqam_rast/compare?transposeTo=nawa
/maqamat/maqam_rast_al_nawa/availability/maqamat/maqam_rast/availability?transpositionNoteName=nawa
/ajnas/jins_segah_al_tik_hisar/ajnas/jins_segah?transposeTo=tik_hisar

You still pass the usual tuning-system and starting-note parameters. Whether a tonic is reachable depends on the tuning system and starting note, so a transposed idName that cannot be built there gets the same 400 as the matching transposeTo would.

Name the tonic once. A transposed idName together with a transposeTo (or transpositionNoteName) for a different tonic is a 400. Giving the same tonic both ways is fine.

/maqamat/{idName}/transpositions and /ajnas/{idName}/transpositions list every transposition, so they take the base idName only. A transposed idName there is a 400 whose hint names the base idName to use.

Older spelling. Until October 2026, some endpoints closed up the separator, spelling maqām rāst on qarār chahārgāh as maqam_rast_alqarar_chahargah. These were the base response's availableTranspositions, the compare endpoints, both classification endpoints (including set IDs), and modulation routes. Separately, a request with transposeTo set to a note an octave away from the base form (transposeTo=qarar_rast for maqām rāst) used to return the bare base idName and display name; it now returns maqam_rast_al_qarar_rast, matching the rest of the API. If you stored one of the closed-up IDs, it is still accepted wherever an idName is: in the path of every /maqamat/{idName} and /ajnas/{idName} route, and in the maqamId and setId filters on the classification endpoints. It is read as the current spelling. Responses use only the current spelling.

Ajnās an octave from their own tonic. Until November 2026, a jins found at a maqām degree an octave from its own tonic kept its bare base idName: jins yegāh on nawā came back as jins_yegah with isBaseForm: false. It now names its tonic like every other form, jins_yegah_al_nawa, the same idName the jins endpoints give it.

Lower-octave modulation targets. Until November 2026, a target in lowerOctaveModulations could carry a name no other endpoint used. Maqām yegāh on nawā, moved down an octave, came back as maqam_yegah_al_yegah, although it is maqām yegāh itself. Every lower-octave target is now the same form, with the same idName, that the listings and GET /maqamat/all give.


Every maqām form in one request ​

GET /maqamat/all describes every maqām a tuning system can build from a starting note, so a client does not need one GET /maqamat/{idName} call per form.

Each item in maqamat is exactly the body GET /maqamat/{idName} returns for that form with the same options, minus the envelope (parameters, context, links). The response carries the envelope once. Code that reads one maqām response can read each item unchanged.

ParameterValuesWhat it does
formsbase (default), transpositions, allThe base form of each maqām, its transpositions (taṣwīr), or both
includeOctaveRenderingstrue / falseAlso returns each maqām an octave from its base form, such as maqam_rast_al_qarar_rast. These are neither the base form nor a taṣwīr, and they appear as modulation targets
fieldse.g. ajnas,primaryJins,modulationsKeeps only these top-level fields in each item. maqam is always kept. A field left out is not computed, so leaving out modulations, lowerOctaveModulations and stats skips the modulation analysis
offsetintegerWhere a page starts. Leave it out and follow next

includeModulations, includeModulations8vb, includeIntervals, includeSuyur, includeArabic, pitchClassDataType and centsTolerance work as they do for one maqām.

Pages. A full analysis is larger than one response can be. For al-Fārābī (950g) from ʿushayrān, all 440 forms (101 base forms and 339 taṣwīr) with both kinds of modulation are about 25 MB. So the response is cut into pages of at most about 5 MB. total counts every selected form, count counts the forms on this page, and next is the URL of the next page, or null on the last one. Requests without modulations usually fit on one page.

bash
# First page; then request each `next` URL until it is null
curl "https://diarmaqar.net/api/maqamat/all?tuningSystem=alfarabi_950g&startingNote=ushayran&forms=all&includeModulations=true&includeModulations8vb=true&pitchClassDataType=cents&fields=pitchData,ajnas,primaryJins,secondaryJins,tertiaryJins,ghammaz,modulations,lowerOctaveModulations"

Every page is cached at the edge and carries an ETag, so a client can check for changes with If-None-Match and get a 304 when nothing changed.


Kinds of maqām and jins form ​

Every maqām and jins form in a response carries formType, read from the form itself:

formTypeMeaningExample
baseThe base form: the form on the tonic the sources givemaqām rāst on rāst, maqam_rast
transpositionA taṣwīr: the form moved to another modal degreemaqām rāst on nawā, maqam_rast_al_nawa
octaveRenderingThe base form an octave or more away, on the same modal degreemaqām rāst on qarār rāst, maqam_rast_al_qarar_rast

A form's idName is its identifier. It is unique within a tuning system and starting note, and the same form has the same idName in every response. formType is on the maqam of a maqām response, on the jins of a jins response, on every entry of ajnas, on modulation targets, in the listings, and as jinsFormType on the structural jins entries.

Listing every form. GET /tuning-systems/{id}/{startingNote}/maqamat and /ajnas take includeOctaveRenderings=true. Each entry then has an octaveRenderings array next to transpositions, with the same shape. The base forms, transpositions and octaveRenderings together are every form a maqām response can refer to. In al-Fārābī (950g) from ʿushayrān, the octave renderings add 206 maqām forms and 108 jins forms, such as maqām yegāh on nawā (maqam_yegah_al_nawa) and jins yegāh on nawā (jins_yegah_al_nawa). In a maqām response, availableOctaveRenderings lists them next to availableTranspositions. GET /maqamat/all with includeOctaveRenderings=true returns the full detail of each.

Structural ajnās and the ghammāz ​

The sources give each structural jins as a degree: maqām rāst has its primary jins on rāst and its secondary jins on nawā. primaryJins, secondaryJins and tertiaryJins name that degree and the first jins the archive finds starting on it in the ascending form. primaryJinsDescending, secondaryJinsDescending and tertiaryJinsDescending read the same degree in the descending form. The sources give one degree per slot, not a separate descending one, so the descending jins is the archive's match, not a source statement.

Each entry has a jinsStatus:

jinsStatusMeaning
matchedA jins in the archive starts on this degree
noMatchingJinsThe degree is in the maqām, but no jins in the archive starts there in this tuning system. Maqām lāmī, degree IV (nawā), is one. The jins fields are null
degreeNotInMaqamThe stored degree is not one of the notes of this direction. maqamDegree and the jins fields are null

Each direction is read on its own. Until November 2026, an ascending entry with no jins took the jins of the descending form instead.

Each ghammaz entry has intervalFromTonic: the interval from the tonic up to the ghammāz, as cents, fraction and decimalRatio. For maqām rāst the ghammāz is nawā, at 3/2 (702 cents). fraction is exact in tuning systems defined by ratios and an approximation in the others.

Citing sources ​

GET /sources and GET /sources/{id} give each source a citation: the authors' family names and the year, such as al-Shawwā 1946. A book with both an original and an edition year gives both: al-Khulaʿī 1904/2011. Two authors are joined with "and", three or more become "et al.". With includeArabic=true, citationAr gives the same in Arabic, with western digits: الشوا 1946. displayName is unchanged: it is an identifier, not a citation.


Transpositions that do not fit a 12-pitch-class set ​

GET /maqamat/classification/12-pitch-class-sets groups maqām transpositions into 12-pitch-class sets. A few transpositions cannot form one. For what that means, see Maqāmāt that cannot form a 12-pitch-class set. The endpoint never skips these transpositions silently. It reports each one, with the key and the pitch classes that need it.

Counts and lists ​

  • Every response includes statistics.incompatibleMaqamatCount, the number of transpositions in this tuning system, from this starting note, that do not fit.
  • includeIncompatible=true adds the full list in incompatibleMaqamat, with its count in incompatibleMaqamatCount.

Each transposition that does not fit ​

FieldDescription
compatibleAlways false
reasonAlways "shared_key": two or more pitch classes need the same key, and the keys next to it are taken. This replaces the former "duplicate_ipn_reference".
explanationOne plain sentence, e.g. "ʿirāq (B-b2) and nīm kawasht (B-2) both need the B key, and the keys next to it are taken."
clashesOne entry for each key that more than one pitch class needs
clashes[].keyThe key, e.g. "B"
clashes[].notesThe notes that need that key. Each note has noteName (URL-safe), displayName, englishName, cents and centsInOctave. With includeArabic=true, each note also has displayNameAr.

centsInOctave is the note's position above the transposition's tonic, with the octave ignored. It is the value the 12-pitch-class set compares. Two notes in the same clash with different centsInOctave values are different pitch classes competing for one key.

Filtering by maqām (maqamId) ​

  • Some transpositions fit: the response has compatible: true and returns their sets as before. It adds incompatibleTranspositions, listing the transpositions that do not fit.
  • No transposition fits: the response is still 200. It has compatible: false, sets: [], incompatibleTranspositions, and an explanation of the form "No transposition of maqām X fits a 12-pitch-class set in <tuning system> from <starting note>."
  • The maqām cannot be built in this tuning system from this starting note (the tuning system lacks some of its notes): the response is still 200, with compatible: false, sets: [], an empty incompatibleTranspositions and an explanation saying so.
  • The maqām does not exist: the response is 404.

maqamId accepts a maqām's idName, its numeric id, or the idName of one of its transpositions. It matches exactly: maqam_hijaz does not also match maqam_hijaz_kar. The older closed-up spelling of a transposition (maqam_rast_alqarar_chahargah) is also accepted. See Identifiers of transpositions.

Example ​

In al-Ṣabbāgh (1954) from rāst, maqām faraḥnāk (al-Ḥilū) on qarār segāh does not fit. ʿirāq (B-b2) and nīm kawasht (B-2) are 29.5 cents apart, and both need the B key. The keys next to it are taken: nīm ʿajam is on Bb and rāst is on C.

bash
curl "https://diarmaqar.net/api/maqamat/classification/12-pitch-class-sets?tuningSystem=alsabbagh_1954&startingNote=rast&maqamId=maqam_farahnak_alhilu"

The entry for that transposition in incompatibleTranspositions:

json
{
  "maqam": {
    "id": "145",
    "idName": "maqam_farahnak_alhilu",
    "displayName": "maqām faraḥnāk (al-Ḥilū)"
  },
  "transposition": {
    "idName": "maqam_farahnak_alhilu_al_qarar_segah",
    "displayName": "maqām faraḥnāk (al-Ḥilū) al-qarār segāh",
    "isTransposed": true,
    "isBaseForm": false
  },
  "compatible": false,
  "reason": "shared_key",
  "explanation": "ʿirāq (B-b2) and nīm kawasht (B-2) both need the B key, and the keys next to it are taken.",
  "clashes": [
    {
      "key": "B",
      "notes": [
        { "noteName": "iraq", "displayName": "ʿirāq", "englishName": "B-b2", "cents": -141.2, "centsInOctave": 701.9 },
        { "noteName": "nim_kawasht", "displayName": "nīm kawasht", "englishName": "B-2", "cents": -111.7, "centsInOctave": 731.4 }
      ]
    }
  ]
}

The two centsInOctave values, 701.9 and 731.4, differ by 29.5 cents. They are two pitch classes, and both need the B key.


Getting Started ​

All endpoints return JSON. No authentication required.

Common parameters:

  • includeArabic (default: "true") - Include Arabic script alongside transliteration
  • includeSources (default varies) - Include bibliographic source references

For complete parameter documentation, see the Endpoints Reference.

For recommended example values, see Representative Examples.

Digital Arabic Maqām Archive Documentation