← Back to Documentation

Digital Arabic Maqām Archive API

Comprehensive API for Arabic Maqām Theory

Table of Contents

API Overview

The Digital Arabic Maqām Archive API provides comprehensive access to Arabic music theory data, including maqamat (melodic modes), ajnas (tetrachordal structures), tuning systems, and advanced analysis tools for modulation and transposition. This API is designed for researchers, musicians, and developers working with microtonal music theory.

Key Features
  • Complete database of maqamat and ajnas with scholarly references
  • Multiple tuning systems with microtonal precision
  • Advanced modulation analysis between maqamat
  • Transposition calculations with cents tolerance
  • Academic source documentation

Notes

  • All endpoints return JSON responses with appropriate HTTP status codes
  • Cents tolerance parameters accept values between 0-50 cents
  • Note names use Arabic transliteration with diacritical marks in responses
  • Names can be provided with or without diacritics: All name parameters (note names, maqam names, jins names, tuning system names) accept both diacritical and non-diacritical versions (e.g., "maqam bayyat" = "maqām bayyāt")
  • Modulation analysis provides both theoretical and practical relationships
  • Academic sources include full bibliographic information for scholarly reference
  • Pitch classes are defined using frequency ratios (numerator/denominator) and cents values

Base URL

http://localhost:3000

All API endpoints are relative to this base URL. The API accepts JSON requests and returns JSON responses.

Get All Ajnas

GET /api/ajnas

Retrieve all ajnas (tetrachordal structures) - the melodic building blocks for maqamat. Each jins contains note names, source references, and theoretical commentary.

Response Codes

200 Successfully retrieved ajnas data
500 Server error - failed to load ajnas data

Example Request

curl -X GET "http://localhost:3000/api/ajnas" \
  -H "Content-Type: application/json"

Example Response

[
  {
    "id": "1",
    "name": "jins rāst nawā",
    "noteNames": [
      "nawā",
      "ḥusaynī",
      "awj",
      "kurdān"
    ],
    "commentsEnglish": "",
    "commentsArabic": "",
    "sourcePageReferences": []
  },
  {
    "id": "2",
    "name": "jins bayyāt",
    "noteNames": [
      "dūgāh",
      "segāh",
      "chahārgāh",
      "nawā"
    ],
    "commentsEnglish": "",
    "commentsArabic": "",
    "sourcePageReferences": []
  }
]
↑ Back to Top

Analyze Jins

POST /api/jins

Analyze a specific jins within tuning systems, including transpositions and pitch class analysis.

Request Parameters

Parameter Type Required Description
jinsID String Optional* Unique identifier for the jins (mutually exclusive with jinsName)
jinsName String Optional* Name of the jins (mutually exclusive with jinsID)
includeTranspositions Boolean Optional Whether to include all transpositions (ignored if newTonicForTransposition is specified). Defaults to false.
newTonicForTransposition String Optional If specified, returns only the transposition to this tonic note (overrides includeTranspositions)
centsTolerance Number Optional Tolerance value used as (+/-) for calculating possible transpositions within tuning systems that aren't based on frequency ratio fractions (e.g. 9/8, 4/3, 3/2) in their core data (0-50, default: 5)
tuningSystemID String Optional Specific tuning system to analyze
tuningSystemStartingNoteName String Optional Starting note name for tuning system note naming convention (must match first element in tuning system). If not provided, defaults to the first available note naming convention in the tuning system core data. This parameter affects the theoretical framework used for jins analysis.

* Either jinsID or jinsName must be provided, but not both.

** Names can be provided with or without Arabic diacritics (e.g., both "jins bayyāt" and "jins bayyat" are accepted).

Example Request (by Name)

curl -X POST "http://localhost:3000/api/jins" \
  -H "Content-Type: application/json" \
  -d '{
    "jinsName": "jins bayyāt",
    "includeTranspositions": true,
    "newTonicForTransposition": "dūgāh",
    "centsTolerance": 5,
    "tuningSystemID": "al-Farabi-(950g)",
    "tuningSystemStartingNoteName": "ʿushayrān"
  }'

Example Request (by ID)

curl -X POST "http://localhost:3000/api/jins" \
  -H "Content-Type: application/json" \
  -d '{
    "jinsID": "1",
    "includeTranspositions": true,
    "newTonicForTransposition": "dūgāh",
    "centsTolerance": 5,
    "tuningSystemID": "IbnSina-(1037)",
    "tuningSystemStartingNoteName": "ʿushayrān"
  }'
↑ Back to Top

Get All Maqamat

GET /api/maqamat

Retrieve all maqamat (melodic modes) - complete modal structures in Arabic music theory. Each maqam contains ascending/descending sequences, suyur (melodic pathways), and source references.

Response Codes

200 Successfully retrieved maqamat data
500 Server error - failed to load maqamat data

Example Request

curl -X GET "http://localhost:3000/api/maqamat" \
  -H "Content-Type: application/json"

Example Response

[
  {
    "id": "1",
    "name": "maqām rāst",
    "ascendingNoteNames": [
      "rāst",
      "dūgāh",
      "segāh",
      "chahārgāh",
      "nawā",
      "ḥusaynī",
      "awj"
    ],
    "descendingNoteNames": [
      "ʿajam",
      "ḥusaynī",
      "nawā",
      "chahārgāh",
      "segāh",
      "dūgāh",
      "rāst"
    ],
    "suyūr": [...],
    "commentsEnglish": "",
    "commentsArabic": "",
    "sourcePageReferences": []
  }
]
↑ Back to Top

Analyze Maqam

POST /api/maqam

Analyze a specific maqam within tuning systems, including transpositions, modulations, and pitch class analysis.

Request Parameters

Parameter Type Required Description
maqamID String Optional* Unique identifier for the maqam
maqamName String Optional* Name of the maqam
includeTranspositions Boolean Optional Whether to include all transpositions (ignored if newTonicForTransposition is specified). Defaults to false.
newTonicForTransposition String Optional If specified, returns only the transposition to this tonic note (overrides includeTranspositions)
centsTolerance Number Optional Tolerance value used as (+/-) for calculating possible transpositions within tuning systems that aren't based on frequency ratio fractions (e.g. 9/8, 4/3, 3/2) in their core data. This affects the modulation possibilities: more transpositions allow for more modulations (0-50, default: 5)
tuningSystemID String Optional Specific tuning system to analyze
tuningSystemStartingNoteName String Optional Starting note name for tuning system note naming convention (must match first element in tuning system). If not provided, defaults to the first available note naming convention in the tuning system core data. This parameter affects the theoretical framework used for maqam analysis.
includeMaqamatModulations Boolean Optional Include maqam-to-maqam modulations
includeAjnasModulations Boolean Optional Include ajnas-based modulations

* Either maqamID or maqamName must be provided, but not both.

** Names can be provided with or without Arabic diacritics (e.g., both "maqam segāh" and "maqam segah" are accepted).

Example Request (by Name)

curl -X POST "http://localhost:3000/api/maqam" \
  -H "Content-Type: application/json" \
  -d '{
    "maqamName": "maqām bayyāt",
    "includeTranspositions": false,
    "newTonicForTransposition": "rāst",
    "centsTolerance": 5,
    "tuningSystemID": "al-Ṣabbāgh-(1954)",
    "tuningSystemStartingNoteName": "rāst",
    "includeMaqamatModulations": true,
    "includeAjnasModulations": false
  }'

Example Request (by ID)

curl -X POST "http://localhost:3000/api/maqam" \
  -H "Content-Type: application/json" \
  -d '{
    "maqamID": "2",
    "includeTranspositions": true,
    "newTonicForTransposition": "dūgāh",
    "centsTolerance": 5,
    "tuningSystemID": "IbnSina-(1037)",
    "tuningSystemStartingNoteName": "ʿushayrān",
    "includeMaqamatModulations": false,
    "includeAjnasModulations": true
  }'

Get Suyūr (Melodic Pathways)

POST /api/sayr

Retrieve suyūr (melodic pathways) for a specific maqam or from a particular academic source. Suyūr represent traditional melodic progressions and ornamentations within maqamat.

Request Parameters

Parameter Type Required Description
maqamId String Optional* Unique identifier for the maqam to retrieve suyūr from (mutually exclusive with maqamName and sourceId)
maqamName String Optional* Name of the maqam to retrieve suyūr from (mutually exclusive with maqamId and sourceId). Can be provided with or without Arabic diacritics.
sourceId String Optional* Unique identifier for the academic source to retrieve suyūr from across all maqamat (mutually exclusive with maqamId and maqamName)

* Either maqamId, maqamName, or sourceId must be provided, but only one at a time.

Example Request (by Maqam ID)

curl -X POST "http://localhost:3000/api/sayr" \
  -H "Content-Type: application/json" \
  -d '{
    "maqamId": "30"
  }'

Example Request (by Maqam Name)

curl -X POST "http://localhost:3000/api/sayr" \
  -H "Content-Type: application/json" \
  -d '{
    "maqamName": "maqām faraḥfazzā"
  }'

Example Request (by Source ID)

curl -X POST "http://localhost:3000/api/sayr" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "Al-Shawwā-(1946)"
  }'

Example Response (by Maqam ID)

{
  "maqamId": "30",
  "maqamName": "maqām faraḥfazzā",
  "suyūr": [
    {
      "id": "Sayr Al-Shawwā-(1946)",
      "creatorEnglish": "Al-Shawwā",
      "creatorArabic": "الشوّا",
      "sourceId": "Al-Shawwā-(1946)",
      "page": 19,
      "commentsEnglish": "Begins on nawā, then ḥusaynī and 'ajam until muḥayyar ascending and descending, then descends from nawā until yegāh with a touch of qarār ḥijāz before ending on its qarār, yegāh. Therefore it is assumed that the initial ascents and descents are in jins nahāwand nawā as per the construction of the maqām.",
      "commentsArabic": "",
      "stops": [
        {
          "type": "jins",
          "value": "6",
          "startingNote": "nawā",
          "direction": "ascending"
        },
        {
          "type": "jins",
          "value": "6",
          "startingNote": "nawā",
          "direction": "descending"
        },
        {
          "type": "note",
          "value": "nawā"
        }
      ]
    }
  ]
}

Example Response (by Source ID)

{
  "sourceId": "Al-Shawwā-(1946)",
  "maqams": [
    {
      "maqamId": "30",
      "maqamName": "maqām faraḥfazzā",
      "suyūr": [
        {
          "id": "Sayr Al-Shawwā-(1946)",
          "creatorEnglish": "Al-Shawwā",
          "creatorArabic": "الشوّا",
          "sourceId": "Al-Shawwā-(1946)",
          "page": 19,
          "commentsEnglish": "Begins on nawā, then ḥusaynī and 'ajam until muḥayyar ascending and descending...",
          "commentsArabic": "",
          "stops": [
            {
              "type": "jins",
              "value": "6",
              "startingNote": "nawā",
              "direction": "ascending"
            }
          ]
        }
      ]
    }
  ]
}
↑ Back to Top

Calculate Modulations

POST /api/modulations

Perform comprehensive modulation analysis for a given maqam within a specific tuning system. Calculates both maqamat-to-maqamat modulations and ajnas-based modulations.

Request Parameters

Parameter Type Required Description
tuningSystemID String Required Unique identifier for the tuning system context
maqamID String Optional* Unique identifier for the source maqam (mutually exclusive with maqamName)
maqamName String Optional* Name of the source maqam (mutually exclusive with maqamID)
tuningSystemStartingNoteName String Optional Starting note name for tuning system note naming convention (must match first element in tuning system). If not provided, defaults to the first available note naming convention in the tuning system core data. This parameter affects the theoretical framework used for modulation analysis.
noteNameToModulateFrom String Required Which note name within the maqam to find modulations from
ajnasModulationsMode Boolean Optional Enable ajnas-based modulation analysis
centsTolerance Number Optional Tolerance value used as (+/-) for calculating possible transpositions within tuning systems that aren't based on frequency ratio fractions (e.g. 9/8, 4/3, 3/2) in their core data. This affects the modulation possibilities: more transpositions allow for more modulations (0-50, default: 5)

* Either maqamID or maqamName must be provided, but not both.

* Note names, maqam names, and tuning system IDs can be provided with or without Arabic diacritics (e.g., both "dūgāh" and "dugah" are accepted).

Example Request

curl -X POST "http://localhost:3000/api/modulations" \
  -H "Content-Type: application/json" \
  -d '{
    "tuningSystemID": "al-Farabi-(950g)",
    "maqamID": "2",
    "noteNameToModulateFrom": "dūgāh",
    "ajnasModulationsMode": true,
    "centsTolerance": 5
  }'
# Alternative using maqamName
curl -X POST "http://localhost:3000/api/modulations" \
  -H "Content-Type: application/json" \
  -d '{
    "tuningSystemID": "al-Farabi-(950g)",
    "maqamName": "maqām bayyāt",
    "noteNameToModulateFrom": "dūgāh",
    "ajnasModulationsMode": true,
    "centsTolerance": 5
  }'

Response Format

{
  "maqamatModulations": [
    {
      "targetMaqamID": "3",
      "modulationType": "direct",
      "commonTones": [...],
      "transitionPath": [...]
    }
  ],
  "ajnasModulations": [
    {
      "jinsID": "5",
      "modulationDegree": 2,
      "intervalPattern": [204, 182, 204]
    }
  ]
}
↑ Back to Top

Update Patterns

PUT /api/patterns

Update the patterns dataset with new pattern data.

Example Request

curl -X PUT "http://localhost:3000/api/patterns" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "id": "1",
      "name": "Pattern 1",
      "data": "pattern data"
    }
  ]'

Get All Sources

GET /api/sources

Retrieve all academic sources and references used in the maqam theory database. These provide scholarly foundation for the theoretical content.

Response Codes

200 Successfully retrieved sources data
500 Server error - failed to load sources data

Example Request

curl -X GET "http://localhost:3000/api/sources" \
  -H "Content-Type: application/json"

Example Response

[
  {
    "id": "Shawqi-(1969)",
    "titleEnglish": "Qiyās Al-Sullam Al-Mūsīqī Al-ʿArabī",
    "titleArabic": "قياس السلم الموسيقي العربي",
    "sourceType": "Book",
    "contributors": [
      {
        "type": "Author",
        "firstNameEnglish": "Youssef",
        "lastNameEnglish": "Shawqi",
        "firstNameArabic": "يوسف",
        "lastNameArabic": "شوقي"
      }
    ],
    "editionEnglish": "",
    "editionArabic": "",
    "publicationDateEnglish": "1969",
    "publicationDateArabic": "١٩٦٩",
    "url": "",
    "dateAccessed": "",
    "originalPublicationDateEnglish": "",
    "originalPublicationDateArabic": "",
    "publisherEnglish": "Dar Al-Kutub",
    "publisherArabic": "دار الكتب",
    "placeEnglish": "Cairo",
    "placeArabic": "القاهرة",
    "ISBN": ""
  }
]
↑ Back to Top

Generate Transpositions

POST /api/transpose

Calculate all possible transpositions of a maqam or jins within a specified tuning system. Finds optimal pitch class mappings with microtonal accuracy.

Request Parameters

Parameter Type Required Description
tuningSystemID String Required Unique identifier for the target tuning system
maqamID String Optional* Unique identifier for the maqam to transpose (mutually exclusive with jinsID and maqamName)
maqamName String Optional* Name of the maqam to transpose (mutually exclusive with jinsID and maqamID)
jinsID String Optional* Unique identifier for the jins to transpose (mutually exclusive with maqamID and maqamName)
tuningSystemStartingNoteName String Optional Starting note name for tuning system note naming convention (must match first element in tuning system). If not provided, defaults to the first available note naming convention in the tuning system core data. This parameter affects the theoretical framework used for transposition analysis.
centsTolerance Number Optional Tolerance value used as (+/-) for calculating possible transpositions within tuning systems that aren't based on frequency ratio fractions (e.g. 9/8, 4/3, 3/2) in their core data (0-50, default: 5)

* Either maqamID, maqamName, or jinsID must be provided, but only one at a time.

** Names and tuning system IDs can be provided with or without Arabic diacritics.

Example Request (Maqam)

curl -X POST "http://localhost:3000/api/transpose" \
  -H "Content-Type: application/json" \
  -d '{
    "tuningSystemID": "al-Farabi-(950g)",
    "maqamID": "2",
    "centsTolerance": 5
  }'
# Alternative using maqamName
curl -X POST "http://localhost:3000/api/transpose" \
  -H "Content-Type: application/json" \
  -d '{
    "tuningSystemID": "al-Farabi-(950g)",
    "maqamName": "maqām bayyāt",
    "centsTolerance": 5
  }'

Example Request (Jins)

curl -X POST "http://localhost:3000/api/transpose" \
  -H "Content-Type: application/json" \
  -d '{
    "tuningSystemID": "al-Farabi-(950g)",
    "jinsID": "1",
    "centsTolerance": 5
  }'
↑ Back to Top

Get All Tuning Systems

GET /api/tuningSystems

Retrieve all tuning systems used in Arabic music. Each defines microtonal pitch relationships and frequency ratios for specific musical scales and theoretical frameworks.

Response Codes

200 Successfully retrieved tuning systems data
500 Server error - failed to load tuning systems data

Example Request

curl -X GET "http://localhost:3000/api/tuningSystems" \
  -H "Content-Type: application/json"

Example Response

[
  {
    "id": "Ronzevalle-(1904)",
    "name": "Modernist Arabic Tuning",
    "pitchClasses": [
      {
        "noteName": "rāst",
        "numerator": 1,
        "denominator": 1,
        "cents": 0
      },
      {
        "noteName": "dūgāh",
        "numerator": 9,
        "denominator": 8,
        "cents": 204
      }
    ],
    "description": "24-tone quarter-tone tuning system",
    "octaveDivisions": 24
  }
]
↑ Back to Top

🔎 Interactive API Explorer

Select an endpoint and options below to see a generated curl request and example output.
Names (note names, ajnas, maqamat, tuning systems) can be entered with or without diacritics.

GET /api/ajnas
↑ Back to Top