Piano Chords API

Sign up for free

Summary

An easy-to-use API for a quick search of piano chords. Forward search works by looking up the root note and/or a chord name; the chord finder works by entering a list of notes and/or midi keys, and returns an array of possible matches.

For guides about integrating the API into your application, please refer to the rapidapi documentation.

API versions

Depending on your needs, you can choose between two versions (see descriptions of responses below).

Base URL

API v1: https://piano-chords.p.rapidapi.com

API v2: https://piano-chords.p.rapidapi.com/v2

The API allows GET requests to these endpoints:

/chordsall chords
/chords/call chords for a specific root
/chords/majorall chords for a specific name
/chords/c/majora specific chord
/chords?n1=c&n2=e&n3=gchord search by notes
/chords?n1=48&n2=52&n3=55chord search by midi keys

Response (v1)

The response is a JSON object. The chord information includes:

Example response for /chords/ab/m

{
  name: "Ab-m",
  notes: [
    "Ab",
    "B",
    "Eb"
  ],
  intervals: [
    "1",
    "b3",
    "5"
  ],
  midiKeys: [
    68,
    71,
    75
  ]
}

Response (v2)

The response for all routes is an object with a result and an error property, both being arrays (or null). The properties of a chord object are:

Example response for /chords/ab/m

{
    error: null,
    result: 
        [
            {
                name: "Ab-m",
                route: "ab/m",
                notes: [
                    "Ab",
                    "B",
                    "Eb"
                ],
                intervals: [
                    "1",
                    "b3",
                    "5"
                ],
                midiKeys: [
                    68,
                    71,
                    75
                ]
            }
        ]
}

Intervals

The intervals are denoted as following:

intervals
12b345b55#56b77b99#911#1113
0234567891011131415171821
half tones

Invalid queries

In case of an invalid query, the response is an object with an error property holding an array of descriptive error messages.

Available chords

The data currently includes the following chords (notation according to their API routes):

major m dim dim7 sus2 sus4 7sus4 aug aug7 aug9 5 6 69 7 7b5 7b9 7sharp9 7b5b9 7sharp5b9 7b5sharp9 7sharp5sharp9 9 9b5 9sharp11 11 13 add9 maj7 maj7b5 maj7sharp5 maj9 maj11 maj13 m6 m69 m7 m7b5 m9 m11 mmaj7 mmaj7b5 mmaj9 mmaj11 madd9

Usage

Full list of chords:

Route: /chords

Response (v1): The response is a nested object where a chord can be accessed through response[root][name].

Response (v2): response.result is an array of all chord objects.


Get all chords for a certain root:

Route: /chords/{root}

Response (v1): The response is a nested object where a chord can be accessed through response[root][name].

Response (v2): response.result is an array of all chord objects for the specified root note.

Sharps are denoted as "sharp", flats as "b". The notation of the response depends on the request. A call to /chords/fsharp retrieves the same intervals and midi keys as a call to /chords/gb, but with different notation.


Get all chords for a certain name:

Route: /chords/{name}

Response (v1): The response is a nested object where a chord can be accessed through response[name][root].

Response (v2): response.result is an array of all chord objects for the specified chord name.

Refer to the table above for all available names and their notation.


Get a specific chord:

Route: /chords/{root}/{name}

Response (v1): The response is a chord object with the chordname, an array of notes, an array of intervals and an array of midi keys (see example response above).

Response (v2): response.result is an array with one chord object.


Search for a chord by notes or midi keys:

Route: /chords?n1={note_1}&n2={note_2}

Route: /chords?n1={midikey_1}&n2={midikey_2}

Response (v1): The response is either an empty object when no match is found, or an object of chord objects, accessible through response[chordname]. Only exact matches are returned.

Response (v2): response.result is an array of chord object(s), or an empty array when no match was found. Only exact matches are returned.

The query parameters can be entered in any order, the first doesn't necessarily have to be the root of the chord. Mixing notes and midi keys in one query is possible.

Valid midi keys are in the range 0 to 127. Valid note names are one of the following:

cdefgab
csharpdsharpfsharpgsharpasharp
db eb gbabbb