Piano Chords API
Sign up for freeSummary
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:
/chords
all chords
/chords/c
all chords for a specific root
/chords/major
all chords for a specific name
/chords/c/major
a specific chord
/chords?n1=c&n2=e&n3=g
chord search by notes
/chords?n1=48&n2=52&n3=55
chord search by midi keys
Response (v1)
The response is a JSON object. The chord information includes:
- the chord root and name separated by a
-
- an array of notes
- an array of intervals
- an array of midi keys
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:
- the chord root and name separated by a
-
- the API route of the chord
- an array of notes
- an array of intervals
- an array of midi keys
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:
1
2
b3
4
5
b5
5
#5
6
b7
7
b9
9
#9
11
#11
13
0
2
3
4
5
6
7
8
9
10
11
13
14
15
17
18
21
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:
c
d
e
f
g
a
b
csharp
dsharp
fsharp
gsharp
asharp
db
eb
gb
ab
bb